# Codex

The way you connect Codex to Catena depends on where Codex runs:

| Where Codex runs              | Use                                                                  |
| ----------------------------- | -------------------------------------------------------------------- |
| The Codex CLI on your machine | `catena link`, below                                                 |
| A Codex cloud task            | A secret key. See [Cloud coding agents](https://docs.catena.com/integrations/cloud-agents.md). |

## Connect the Codex CLI

1. Paste our setup prompt from
   [Connect an agent](https://docs.catena.com/connect.md#give-your-agent-this-prompt).
2. Codex runs commands in its own sandbox, which is separate from your Catena
   [sandbox](https://docs.catena.com/sandbox.md). Its default sandbox refuses network access to the Catena
   API (`api.catena.com`) and keychain writes, and the CLI needs both:
   - When the CLI's error names the Catena API host, approve the request for
     network access.
   - When `catena link` fails to store its key, approve the sandbox escalation
     when Codex asks, and run the command again.
3. Open the approval link, choose the organization and [policy](https://docs.catena.com/policies.md), and
   approve.
4. Tell Codex you approved. It will run `catena link` again, which prints
   `Done`.

If your sandbox settings cannot allow keychain writes, we recommend a
[secret key](https://docs.catena.com/connect/secret-keys.md) instead. Set it as `CATENA_SECRET_KEY` in the
environment Codex runs in, and skip `catena link`.

> [!NOTE] **No file fallback**
>
> When the keychain refuses a key, the CLI does not save it to a file. You'll
> need to allow the keychain write or use a secret key.

## Test the connection

To check that everything is working, ask Codex to run `catena whoami`. It will
report the agent's name.

## Limitations

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

- If Codex writes under `~/.config/catena` from inside its sandbox, that path
  must be writable. Allow it, or set `CATENA_HOME` to a writable directory that
  persists between runs.
- Payments at or above your approval threshold will wait for an admin.

## Related

- [Link with the CLI](https://docs.catena.com/connect/cli.md): Link a new or existing agent that runs in a terminal, on your own machine or a headless host, with catena link.
- [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.
- [Credential storage](https://docs.catena.com/connect/credentials.md): Where the CLI keeps an agent's signing key on each kind of host, and which credential mode to use when there's no keychain.
- [Cloud coding agents](https://docs.catena.com/integrations/cloud-agents.md): Connect Claude, Codex, and Cursor cloud agents and Copilot's coding agent to Catena with a secret key that the platform injects into each sandbox.