cadenya auth login, then start at After the claim.
What you do
Two things need a person. Both come later, and the page marks each one:- Claim the workspace, by signing up in a browser.
- Copy an API key into your app’s
.env.
Before the claim
1
Install Cadenya's skills
Skills teach your coding agent Cadenya’s commands, limits, and errors, so it reads them instead of guessing. Install them first:The installer asks which skills to add and which coding agents get them. Two matter for this page:
cadenya-start-without-account covers the temporary workspace and the claim, and cadenya-cli covers every command after it. To see the full set without installing anything, add --list.2
Install the CLI
Homebrew covers macOS and Linux. Chocolatey covers Windows:Then check the version:You should see:Temporary workspaces need 1.12.0 or later. A package manager can trail the newest release. If yours installs an older version, download the archive for your platform from the releases page.
3
Create a temporary workspace
One command creates a workspace and an API key that reaches only that workspace:You should see:Every
cadenya command run from this directory now uses that key and that workspace. So skip --api-key and --workspace-id, and don’t export CADENYA_API_KEY or CADENYA_WORKSPACE_ID in this shell. An exported key outranks the file.The command refuses to run when a Cadenya credential already exists (a stored login or CADENYA_API_KEY) and in CI. Temporary workspaces are for people who don’t have an account yet.4
Hand over the claim link
The agent’s next message goes to you, before it builds anything. A useful one carries the link and the deadline:
I created a temporary Cadenya workspace. To keep it, open this link and sign in or sign up before Mon Nov 16 13:52 EST:Whoever opens the claim link and signs in owns the workspace. So the link belongs in a reply only you read. In a pull request, an issue, or a shared channel, the agent leaves the link out and asks you to runhttps://app.cadenya.com/claim#...Keep the link private: whoever opens it can take the workspace. If nobody claims it by then, it’s deleted along with everything I build in it. You can also claim it by runningcadenya auth loginin this directory.
cadenya auth login instead.5
Connect a Tool Set
Before the claim, a Tool Set can call Cadenya-hosted endpoints and nothing else. (Your own hosts come after the claim.) The Faker MCP server at You should see:Cadenya syncs the server’s tools into the Tool Set. Give it a few seconds, then list them:You should see:(Yes, one of them generates curse words.)
free.cadenya.com is one of them, and it hands out sample data:6
Create and publish an Agent
One command creates the Agent and its first variation. The variation gets the prompt and the Tool Set:The command names no model, so the variation runs on the workspace default. A new Agent starts as a draft, and objectives need a published one:You should see:
7
Run an objective
Hand the Agent a task:You should see:The call returns at once, and the Agent gets to work in Cadenya. A few seconds later, list what happened:You should see (IDs and the last two columns trimmed):That’s the whole loop: a message, a tool call, a result, and an answer. Add
--display json to read each event in full.The answer comes from the demo model, which is scripted. A temporary workspace has no model credit, so its default model calls one read-only tool with made-up arguments and returns a templated summary. It proves the wiring. It can’t judge your prompt. Real models arrive with the claim, or sooner if you add your own provider key.Claim the workspace
This is the first step that needs you. Run this in the project directory, the one that holds.cadenya/temporary.json:
cadenya auth login afterward so the CLI has a credential.)
The claim changes four things:
- The workspace stops expiring and moves onto the Free plan.
- Cadenya adds $5 of promotional model credit, and its models replace the demo model as the default.
- The temporary API key stops working, and the CLI removes
.cadenya/temporary.json. The stored login takes over. - Trusted endpoints, memory layers, Widgets, and config files open up.
After the claim
The Data Agent proved the loop. Now your coding agent builds the real setup: a Tool Set on a host you pick, described in files your repository owns.1
Set the default workspace
The workspace keeps the ID it was created with. Store it as the CLI’s default:Lost the ID?
cadenya workspaces list prints it.2
Trust the hosts your Tool Sets call
Cadenya sends Tool Set requests only to hosts on your account’s trusted endpoints. That way, a Tool Set’s credentials never reach a host you didn’t pick. The Swagger Petstore lives at Then check the exact URL the Tool Set reads, and look for Trust only the hosts your own Tool Sets call, because every Tool Set in the account can reach a trusted host.
petstore3.swagger.io, so trust it:RESULT_TRUSTED in the result:3
Describe the setup in config files
The setup lives in your repository: a The settings name the workspace and the bundle key:The bundle key marks every resource this repository owns, so give each repository its own. The next step shows why.The Tool Set reads the Petstore’s OpenAPI spec from a URL:The Agent is published, so objectives can use it:And its variation sets the prompt, then gets the Tool Set:The variation names no model, so it runs on the workspace default, which the claim switched to a Cadenya model. To pick one, add
cadenya.yaml for settings, and a .cadenya/ directory with one YAML file per resource. Here’s the layout for an Agent with the Swagger Petstore as its Tool Set:cadenya.yaml
.cadenya/toolSets/petstore.yaml
.cadenya/agents/petstore-agent.yaml
.cadenya/agents/petstore-agent/default.yaml
modelConfig.modelId with a model’s ID. cadenya models list shows what your workspace can run. Each file’s external ID comes from its filename, which is why the Agent is petstore-agent. (Config files has every rule.)4
Check the plan, then apply
Validate first. It runs offline:You should see:But validate can’t see your workspace. So ask Cadenya what would change there:You should see (log lines trimmed):The Data Agent and the Faker Tool Set aren’t in the plan. They don’t carry your bundle key, so apply leaves them alone.When the plan matches what you expect, apply it:Once the Tool Set exists, Cadenya syncs the Petstore’s operations into it as tools.
cadenya tool-sets tools list external_id:petstore lists them.5
Give your app an API key
This is the second step that needs you. The CLI has a login, but your app needs a key of its own. Copy one from the API keys page and put it in your project’s Put the key in
.env, next to the workspace ID:.env
.env, not in a chat message, so it stays out of your coding agent’s transcript. Transcripts get shared. And keep .env out of git. (API keys covers scopes, and keys for a single workspace.)6
Dispatch an objective from your app
Install the SDK for your language:Then create an objective for the Agent. Both SDKs read The call returns the new objective at once. Read its events with the ID your app printed:This time a real model picks the Petstore tools and writes the answer.
CADENYA_API_KEY and CADENYA_WORKSPACE_ID from the environment, so let your framework’s .env loader handle the file:Temporary workspace rules
A temporary workspace has a deadline and a few limits. This section lists them.The deadline
A temporary workspace that nobody claims is permanently deleted 24 hours after it was created. That includes its Agents, Tool Sets, objectives, and secrets. Nothing comes back after that.--expire-after shortens the window (anything from 1h to 24h) and never lengthens it. Run the create command again in the same directory and you get the same workspace back. --fresh makes a second one.
The claim link
The CLI repeats the claim link in a few places: the create command,cadenya workspaces claim-status --wait, and every error that needs a claim. Keep that output out of CI logs, pull requests, and anything else that gets kept.
cadenya workspaces claim-status shows where the claim stands:
Add
--wait to block until the workspace is claimed or expired.
What waits for the claim
Your agent can create Tool Sets, Agents, and variations, publish Agents, and run objectives. The rest waits:
Going past a cap fails with the reason
REQUIRES_CLAIM. The features that aren’t available fail with HTTP 403 SCOPE_MISSING, because the temporary API key doesn’t carry that scope. The claim lifts both.
Models before the claim
A temporary workspace has no Cadenya-provided model and no model credit. Two options run objectives anyway:- The demo model. It’s the default, and it’s free. When the variation has a read-only tool, it calls one with made-up arguments, then returns a templated summary of the result. Without one, it sends back a scripted reply.
- Your own provider key. Add an AI provider key for Anthropic, OpenAI, OpenRouter, or another provider, and objectives run on real models right away. Pass the key on stdin so it stays off the command line:
The temporary key after the claim
The next request with the temporary key fails withTEMPORARY_WORKSPACE_CLAIMED, and the CLI removes .cadenya/temporary.json. If your app read that key from an env file, swap in a key from the API keys page.