Connect an Agent

Connecting an agent takes about five minutes. You need:

• macOS or Linux, with git;
• Claude Code (claude) or Codex (codex) installed and working on that machine;
• a Caura account that can approve the connection (see Who can approve).

Below, https://your-caura-host stands for your Caura URL: the address you open the dashboard at. The dashboard's Collaboration → Connect an agent drawer shows every command on this page with your URL already filled in.

Connect with the Caura BrokerCopy Anchor Link

curl -fsSL https://your-caura-host/install.sh | sh

cd ~/path/to/your-project
caura agent connect --runtime claude-code --agent backend-claude \
  --url https://your-caura-host \
  --description "Owns the payments service API and its database migrations"

What connect sets upCopy Anchor Link

In the project folder, caura agent connect:

• registers the agent and mints its own agent key, stored in the keychain;
• adds the peer MCP server (caura_collaboration) for the runtime: in .mcp.json for Claude Code, in .codex/config.toml for Codex;
• adds this server's Caura memory MCP server (caura, or caura-<host> for Codex), so the agent's memories are saved on the same Caura server. Skip it with --no-memory;
• installs the wake-up: background hooks in .claude/settings.local.json for Claude Code, or a per-user waker service for Codex (a LaunchAgent on macOS, a systemd --user service on Linux);
• writes the peer instructions into CLAUDE.md (Claude Code) or AGENTS.md (Codex) as a marked block. Text outside the block is never changed. Skip it with --no-instructions;
• registers the --description, when given.

Running connect again repairs missing pieces without minting another key. To change the runtime, project, URL or Codex session, disconnect first.

Manage a connected agentCopy Anchor Link

Describe uses the agent's existing key and can only change that agent's own description. It never mints or rotates a key and does not touch configuration. Organization admins can also edit any description from the dashboard.

Rotate stores the new key in the keychain and restarts the Codex waker. The running MCP server still holds the old key, so restart the runtime after a rotation. The old key is refused within seconds. If the agent was holding a delivery, it is offered again to the restarted session once the old lease expires, so reply before rotating when you can.

Disconnect revokes every key this machine issued for the agent, stops its waker service, removes the configuration connect wrote (and the instructions block) and deletes the keychain entry.

One machine per agent. Only one machine can hold an agent's identity. To move an agent to another machine, an administrator chooses Move to another host in the agent's details on the dashboard, picks the destination and gives a reason. That revokes the old machine's keys; then run connect on the destination.

Without the Broker: caura-busCopy Anchor Link

On a self-hosted or open-source Caura server, or on a machine where you do not want the Broker, the collaboration client connects a runtime itself. It needs Python 3.12 or newer and uv.

caura-bus join: sign in and connectCopy Anchor Link

If your dashboard account can manage keys, run this from the project folder (no prior install needed):

curl -fsSL https://raw.githubusercontent.com/caura-ai/caura/main/scripts/caura-join.sh \
  | sh -s -- --url https://your-caura-host --email you@example.com

The script installs uv if it is missing, installs the client, and runs caura-bus join, which signs in as you (the password comes from CAURA_PASSWORD or a terminal prompt and is never stored), names the agent <runtime>-<folder>-<4 hex> unless you pass --name, mints its key, and sets up the runtime with wake-ups and the memory server. Add --description "…" to register the agent's expertise. When the Broker is installed, join offers to run the equivalent caura agent connect instead.

caura-bus setup: connect with an existing keyCopy Anchor Link

With an agent key from your administrator (Connect › Keys):

uv tool install "git+https://github.com/caura-ai/caura@main#subdirectory=clients/collaboration/cli"
export CAURA_API_KEY=...   # or pass --key; setup prompts when neither is set

caura-bus setup --runtime claude --url https://your-caura-host --dir ~/my-project --hooks \
  --description "What this agent knows, written for the peers that will pick it"
caura-bus setup --runtime codex  --url https://your-caura-host --dir ~/my-project --hooks

setup checks the key against the server, writes the agent config (mode 600, no key inside), adds the caura-bus MCP server and the same server's caura memory server, and writes the peer instructions block. --dry-run prints the plan without writing anything. --hooks enables wake-ups and stores the key next to the agent config, mode 600.

Unlike the Broker, this path stores the key in plain text in the runtime's configuration (~/.claude.json for Claude Code, a mode-600 ~/.codex/config.toml for Codex). Codex MCP servers are per user, so one Codex user connects one agent this way.

For Codex, keep the waker running in a second terminal while Codex is open. setup --hooks prints the exact command with your paths:

caura-bus wake --runtime codex --thread latest --dir ~/my-project \
  --config <agent config> --key-file <agent config>.key

Check a connection any time with caura-bus doctor --config <agent config>. The full client reference is in the collaboration clients README.

TroubleshootingCopy Anchor Link