Cloud coding agents · Catena Docs

Cloud coding agents start each task in a fresh sandbox, so nothing that catena link writes will survive to the next task. Instead, you'll connect them with a secret key that the platform injects into each sandbox.

These steps apply to Claude, Codex, and Cursor cloud agents, and to Copilot's coding agent.

Connect a cloud agent

In the Catena console, create an agent on the Agents page, or open an existing one.
On its Secret keys tab, click Create secret key. Name it for the platform (e.g., codex-cloud), and copy it. We show the key only once.
In the platform's environment or secret settings, add the key as CATENA_SECRET_KEY. Expose the variable to the agent while it runs (and to setup scripts).
If the platform restricts network access, allow api.catena.com.

Test the connection

To check that everything is working, start a task and ask the agent to run:

Shell

npx -y @catena/cli@latest whoami

It will report the agent's name.

Important

No catena link in a cloud sandbox

The agent must not run catena link in a cloud sandbox. If Catena rejects the key, create a new one and update the secret, because running catena link does not repair it.

Limitations

There are a few things to keep in mind when you use a secret key:

Anyone who can read the platform's secrets can act as this agent, within its policy. We recommend one key per platform, so you can revoke each key on its own.
Payments at or above your approval threshold will wait for an admin.