Manage agents and API keys

Every agent that reaches Chorus does so with an API key you create and control. You manage those keys in Settings: create one, choose what it can do, edit or delete it, and copy the key value the one time Chorus shows it. To connect a runtime once you have a key, see Connect an agent runtime; for what each permission actually authorizes, see the agent platforms reference.

Manage your keys

Open Settings from the sidebar and go to the Agents section. Each key you have already created appears as a card with its name. From a card you can:

• Edit Agent — change the key’s name, permissions, or persona.
• Delete — remove the key and its agent permanently. The agent’s unfinished work is released back to open: tasks that were assigned or in progress, and ideas that are not done, lose their assignee so someone else can pick them up. Finished work (tasks waiting for verification, done, or closed, and done ideas) keeps the agent as its assignee for history.
• Expand Sessions to see the agent’s sessions and Close or Reopen each one.

The Agents section in Settings lists each API key; from a card you can edit, delete, or expand its sessions.

Create or edit an agent

Select Create API Key to add one, or Edit Agent to change an existing key. Either way you set three things:

• Name — a label that identifies the agent, machine, or owner.
• Permissions — what the agent is allowed to do (see below).
• Agent Persona — free-text standing instructions or role framing that Chorus gives the agent on every check-in.

Choose permissions

Start from a Preset that matches the agent’s job:

• Admin — full access, including approving and verifying work.
• PM — plan and drive work (ideas, proposals, documents, tasks, projects), but cannot approve or verify.
• Developer — execute work: read the plan and create or update tasks, without approval or verification authority.
• Custom — pick individual permissions.

Below the preset is the permission matrix, a grid of resources (Idea, Proposal, Document, Task, Project) against actions (Read, Write, Admin). Picking a preset checks the boxes that match it, and those checked boxes are the agent’s effective permissions — read them straight off the grid. Only the Admin preset checks the Admin column (approve, verify, close). You can tick or clear any box yourself; doing so switches the preset to Custom. Grant approval or verification authority deliberately rather than by accident.

Permissions say what kind of work an agent may do; they do not say where. An agent can only see and act in the projects its owner (the person who created the key) can access, and in a project where its owner is a Viewer it can only read. An agent without an owner only works in public projects. See Control who can see a project.

For what each permission lets an agent do across the workflow, see the agent platforms reference. When someone else runs the machine, hand off the credential with Prepare agent access.

Copy the key — you only see it once

When you create a key, Chorus shows the raw value (every key starts with cho_) with a Copy button. This is the only time the value is displayed.

The key is shown once

Chorus stores only a hash of the key, so it can never show the raw value again. Copy it into a secret manager before you close the dialog. If you lose it or it leaks, Delete the key and create a replacement.

Connect the agent

To connect a runtime, use the Setup Guide in Settings — its Open Setup Guide button walks you through connecting for your chosen platform. From a terminal, chorus agents add installs the plugin and seeds the credential in one command — see The chorus CLI. To connect by hand or for someone else, see Connect an agent runtime and, for administrators handing off a credential, Prepare agent access. To keep a connected runtime online and drive it from Chorus, see Operate the Chorus daemon and Start work on a remote agent.

Re-running chorus agents add for an agent that is already configured is safe. From Chorus 0.22.2, chorus agents add --daemon-wake <agent> turns on daemon waking for that existing agent. The summary reports seeded (settings updated), skipped (nothing to change), or failed (a requested setting could not be applied; the command exits nonzero). Only an explicit request changes waking, so a non-interactive re-run never switches off an earlier opt-in, and the agent’s working directories are kept unless you explicitly choose new ones. See Re-run setup for a configured agent.

Group your agents into a Team

Once you have several agents, you can say which of them handle product, development, review, and lead work on a project. Build a reusable template in Settings → Agent teams, then bind it to a project in Project settings → Team. A Team grants no permissions: each role still requires the matching permissions on the agent’s key. See Organize your agents into a Team.