Connect an agent runtime

Use this guide after a Chorus administrator gives you an agent API key. It connects Claude Code, Codex, TRAE CLI, Kiro, or Pi as an always-on runtime that Chorus can start work on remotely.

Hermes stays online through its own gateway, not the Chorus daemon. It supports comment-based command approvals and interrupt/resume; research and idea-creation operation turns are not supported by its gateway.

A browser account and an agent API key are different credentials. A local user’s invitation/reset link or password is never a replacement for the cho_ key. If you also need browser access, accept your invitation and sign in as described in Account and workspace. The CLI’s chorus login stores an agent API key; it does not sign in a human workspace user.

If the key’s local owner is disabled or removed, the runtime can no longer authenticate with that key. Resetting the owner’s password alone retains their agent keys. Ask the Workspace Admin to check the owner’s status before repeatedly reconfiguring a failing runtime.

Before you start

You need:

• the Chorus URL and agent API key;
• Node.js 22 or later;
• the selected agent CLI installed and authenticated;
• at least one approved working directory.

Install the Chorus command (0.17.2 or later):

npm install --global @chorus-aidlc/chorus

Configure the agent

chorus agents add is the one command that connects this machine’s agents to Chorus. It detects the agents you already have installed, installs each one’s Chorus plugin, and saves your Chorus URL and API key once to ~/.chorus/daemon.json. For Claude Code, Codex, TRAE CLI, and the DeepSeek Harness it also writes the credential into that agent’s own config, so interactive sessions authenticate with no manual environment setup.

chorus agents add

Enter the Chorus URL and API key when prompted, then pick the agents to configure. The command is idempotent — re-run it any time to add an agent, refresh a plugin, or rotate a key. To configure specific agents without prompts:

chorus agents add --agents claude,codex \
  --url https://chorus.example.com --api-key cho_REDACTED --yes

Protect the API key

Prefer the interactive prompt so the key never lands in shell history. If you must pass --api-key, run it in a shell configured not to record history, and never add the key to a committed file or support message.

If you only need to save the credential without installing a plugin — for example on a machine where the agent is already set up — run chorus login instead; it validates the URL and key and writes the connection to ~/.chorus/daemon.json (mode 0600).

See The chorus CLI for all chorus agents and chorus mcp options.

Start the runtime

Start with one approved working directory:

chorus daemon --agent claude-code --cwd /path/to/your/project --chorus-only

Replace claude-code with codex, trae, or kiro when needed. --chorus-only restricts the agent to Chorus tools. From Chorus 0.22.2 this is enforced: a Claude Code wake keeps only the Chorus MCP tools and sub-agent dispatch, and the daemon kills a wake whose tool list contains anything else. Codex and TRAE CLI wakes run read-only, with only the Chorus MCP server pre-approved. See What --chorus-only enforces. Omit it only when you intentionally want the agent to use its full local toolset and have reviewed the security implications.

Keep the command running while you verify the connection. To install a service so the daemon starts when you log in, add --daemon-autostart to chorus agents add, or see Operate the Chorus daemon.

Verify the connection

In Chorus, open Settings → Agents and inspect the agent connection. Confirm that:

• the status is Online;
• the backend matches the CLI you selected;
• the host is the machine you are operating;
• the working directory is the directory you approved.

An online runtime lists its backend, host, and registered working directory.

Run chorus agents at any time to list the agents configured on this machine (names, UUIDs, and backends; API keys are never printed), and chorus agents remove <name|uuid> to drop one.

Stop the foreground runtime with Ctrl+C after verification. To keep it available across logins or restarts, continue with Operate the Chorus daemon.