# Cloud coding agents

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](https://docs.catena.com/connect/secret-keys.md) 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

1. In the Catena console, create an agent on the **Agents** page, or open an
   existing one.
2. 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.
3. 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).
4. 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:

```sh
npx -y @catena/cli@latest whoami
```

It will report the agent's name.

> [!WARNING] **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](https://docs.catena.com/policies.md). 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.

## Related

- [Link with secret keys](https://docs.catena.com/connect/secret-keys.md): A secret key lets an agent act in Catena from hosts where catena link cannot store a credential, such as CI jobs, cloud sandboxes, and deployed services.
- [Claude Code](https://docs.catena.com/integrations/claude-code.md): Connect Claude Code to Catena with the CLI, and it will read accounts and make payments under the agent's policy.
- [Codex](https://docs.catena.com/integrations/codex.md): Connect the Codex CLI to Catena with catena link, or connect Codex cloud tasks with a secret key.