Credential storage · Catena Docs

Each linked agent has one signing key, which the CLI uses to sign each request. The key itself is never sent to Catena, and where it's stored depends on the host.

Choose a credential mode

The table below shows where the key lives on each kind of host:

Host	Where the key lives	How to set it up
macOS	The macOS Keychain	`catena link`
Linux with a Secret Service keyring	The keyring	`catena link`
Linux with no keyring, such as a headless VM or a container with a persistent home directory	A file under `~/.config/catena/credentials/` that only your user can read	`catena link`
A container that loses its home directory on restart	A file under `$CATENA_HOME/credentials/` on a mounted volume	Set `CATENA_HOME`, then `catena link`
A host with no persistent disk: CI, serverless, a cloud sandbox that starts fresh for each task	An environment variable	A secret key in `CATENA_SECRET_KEY`

When catena link finishes, it prints which store it used. Every other command reads the key from that store, and catena unlink removes it.

Note

Hosts with no keychain

Do not use catena link --service on a host with no keychain. Plain link works there and falls back to the file store, while --service is for a person provisioning a deployed service.

The file store

On a Linux host with no keyring (such as the computer a Meta Muse agent runs on), the CLI writes the key to a file under ~/.config/catena/credentials/ ($XDG_CONFIG_HOME/catena/credentials/ when that is set, or $CATENA_HOME/credentials/) that only your user can read.

The file permissions keep other users on the machine from reading the key. However, any program that runs as your user can read it, so we recommend treating access to the machine as access to the credential. The agent's policy limits what anyone holding the key can do, and you can revoke the link from the console at any time.

Docker

A container that loses its home directory on restart will lose the profile and key along with it. To keep them, you'll need to point CATENA_HOME at a volume before linking and keep it set for every later command:

Shell

export CATENA_HOME=/data/catena
catena link --name "Container agent"

The value must be an absolute path. Once it's set, profiles, credential files, and pending link requests will all move there, readable only by your user.

Sandboxed agent tools

Some agent tools run commands inside a sandbox that refuses access the CLI needs. When that happens, the CLI's error will say what was refused. Below are the refusals you may see, and what to do about each one.

Refused	What to do
Network access	The error names the host. Allow network access to that host.
Keychain writes	Codex's default sandbox refuses them. Run the command again with the sandbox's approval or escalation, and if the sandbox can't allow it, use a secret key. The CLI does not move a refused key into a file.
Writes under `~/.config/catena`	Allow that path, or set `CATENA_HOME` to a writable directory that persists between runs. Note that a rule that allows the older `~/.catena` path does not cover the new one.

Where profiles live

Profiles and their settings live in ~/.config/catena (or $XDG_CONFIG_HOME/catena), or in $CATENA_HOME when it's set. CLI 0.18 and later move an older ~/.catena there on first run and leave a link at the old path.

Revoke access

To revoke a linked machine, you can run catena unlink on it or unlink it from the agent's page in the console. To revoke a secret key, use the agent's Secret keys tab.

Both take effect immediately. We check each signed request against the link, so an unlinked or revoked key will fail on its next request.