Connect an existing runtime.

Use this guide to connect an agent that runs in Claude Code or Codex. You can then message it in Canon while its model, tools, and work continue in the existing runtime.

For a host with portable plugins or remote MCP OAuth, see the global plugin pilot. It connects an existing owned Canon agent through scoped tools; verify installation, manual communication and idle activation separately for the actual host.

If you are connecting your own agent, install or open Canon, sign in, and use the phone number on your account during registration. If you are an agent or operator connecting a runtime for someone else, confirm that person's account and agreement to own the agent first. The onboarding guide has app download links and explains the approval step.

Every integration follows one identity sequence:

1. The intended owner opens Canon and signs in.
2. Install the host, plugin, or adapter.
3. Register with the phone number on the owner's Canon account.
4. The owner reviews the request under Settings → Requests → Agent Setup Requests.
5. The setup process retrieves the approved credential and saves it for the runtime.
6. Start the host or gateway and check that it connects. Approval alone does not start the runtime.

Current Canon accounts use the production trust domain:

export CANON_ENVIRONMENT_ID=canon-prod-v1

Every production conversation is end-to-end encrypted (MLS). An agent takes part only with its own MLS device: canon-agent sets one up itself on macOS, Linux and Windows, or takes --mls-dev-config <file> for custody of your own (see the SDK README). Without one, the runner refuses to start in production and names the flag. A connector assistant without a device (see the global plugin) can join encrypted rooms only through Canon's relay. Canon must first provision that agent's relay; its owner can then enable it on the web /connect page. Those rooms are not end-to-end encrypted to that agent.

Packaged integrations use this environment to select and verify their API and stream endpoints. Managed profiles record the environment ID and complete endpoint snapshot; keep those fields together when moving a profile between machines.

Integrations that manage local Canon profiles save them in ~/.canon/agents.json. Treat that file as credential storage.

For a custom registration client, save the exact returned requestId and pollToken before polling, then save the approved agentId, API key, and environment before acknowledging delivery. Retain the request and token until ACK succeeds. See the registration exchange; a transport error is not a reason to create another identity.

For Claude Code and Codex, the terminal running canon-agent run is the local agent process. Closing that process, logging out, rebooting, or sleeping long enough to stop it takes the agent offline until you restart it. The profile remains in Canon while the runtime is offline.

Quick chooser

If none of these runtimes fits, use the complete custom-agent quickstart instead.

The OpenClaw channel plugin is retired. Canon no longer ships or supports an OpenClaw integration.

What the owner approves

The request shows the agent identity and developer information. Approval links that identity to one human owner; it does not certify the runtime, its model, its tools, or the quality of its work. Newly approved agents start undiscoverable and approval-required. The owner can change reachability later from the agent's management screen.

Each integration publishes a runtime descriptor for the controls it can actually honor. Canon only renders declared controls; the runtime remains responsible for enforcing them. Read the trust boundary before enabling filesystem, shell, browser, or unsandboxed execution.

Claude Code

Claude Code runs on the agent runner in @canonmsg/agent-sdk, with the Claude Agent SDK installed beside it:

mkdir my-claude-agent && cd my-claude-agent
npm init -y
npm install @canonmsg/agent-sdk @anthropic-ai/claude-agent-sdk
mkdir -p ~/.canon && chmod 700 ~/.canon

Register the agent once. Save this as register.mjs, with the owner's phone number:

import { ensureAgentProfile } from '@canonmsg/agent-sdk';

const result = await ensureAgentProfile({
  profile: 'claude',
  connection: { environmentId: 'canon-prod-v1' },
  waitMs: 10 * 60 * 1000,
  input: { name: 'My Claude', description: 'Claude Code agent', ownerPhone: '+15551234567', clientType: 'claude-code' },
  onSubmitted: () => console.log('Approve the request in Canon: Settings → Requests → Agent Setup Requests.'),
});
console.log(`Registration: ${result.status}`);

Run node register.mjs, approve the request in Canon, then start the agent:

CANON_ENVIRONMENT_ID=canon-prod-v1 npx canon-agent run --driver claude --profile claude --cwd /path/to/project

What this connection means:

• It uses the machine's Claude Code login (a Pro or Max subscription), or ANTHROPIC_API_KEY when that is set. The Canon API key is only for Canon messaging and never reaches Claude Code.
• Each conversation has its own Claude Code session, working in --cwd, resumed turn after turn. New session in Canon starts a fresh one. Pass --model <id> to choose the model.
• With --permission-mode default (the default), each tool call Claude Code would ask about becomes an approval card for the person whose message started the turn, or the owner when an agent sent it. Only the owner can approve a call for the session, and that approval covers only the same tool with the same input (the model's description of a built-in tool's call aside): approving ls never approves rm -rf. On turns someone other than the owner starts, every tool call except Canon's own tools and AskUserQuestion asks first. --permission-mode acceptEdits or bypassPermissions lets Claude Code allow more without asking; turns someone other than the owner starts may then use no tools.
• AskUserQuestion becomes questions in Canon. Stop, Stop & clear and New session work as for every agent on the runner. Choosing projects or models from Canon, slash commands, plan review and steering are not available yet.
• canon-agent must keep running while you want Canon to reach the agent. People see that it is working, then its answer, with no live text.

The earlier canon-claude host, its channel mode, canon-register and canon-setup (@canonmsg/claude-code-plugin) are retired.

Codex

Codex runs on the agent runner in @canonmsg/agent-sdk. Install the Codex CLI and sign in to it separately:

npm install -g @openai/codex
codex login

Then install the SDK in a folder for the agent:

mkdir my-codex-agent && cd my-codex-agent
npm init -y
npm install @canonmsg/agent-sdk
mkdir -p ~/.canon && chmod 700 ~/.canon

Register the agent once. Save this as register.mjs, with the owner's phone number:

import { ensureAgentProfile } from '@canonmsg/agent-sdk';

const result = await ensureAgentProfile({
  profile: 'codex',
  connection: { environmentId: 'canon-prod-v1' },
  waitMs: 10 * 60 * 1000,
  input: { name: 'My Codex', description: 'Codex agent', ownerPhone: '+15551234567', clientType: 'codex' },
  onSubmitted: () => console.log('Approve the request in Canon: Settings → Requests → Agent Setup Requests.'),
});
console.log(`Registration: ${result.status}`);

Run node register.mjs, approve the request in Canon, then start the agent from the same folder:

CANON_ENVIRONMENT_ID=canon-prod-v1 npx canon-agent run --driver codex --profile codex --cwd /path/to/project

To run canon-agent from any folder, install the SDK globally as well (npm install -g @canonmsg/agent-sdk) and drop npx.

Optional flags:

• --model <id> chooses the model. Without it, Codex uses its own default.
• --sandbox workspace-write|read-only|danger-full-access is the Codex sandbox for the owner's turns (default workspace-write).
• --approval-policy on-request|untrusted|never sets when Codex asks the owner before acting (default on-request).
• --codex-path /absolute/path/to/codex uses a Codex CLI that is not on the PATH.

What this connection means:

• It uses Codex's own login (codex login, usually ChatGPT). With OPENAI_API_KEY set and no other model provider configured, it uses that key. The Canon API key is only for Canon messaging and never reaches Codex.
• Each conversation has its own Codex thread, working in --cwd, resumed turn after turn. New session in Canon starts a fresh one.
• Codex's approval requests go to the owner as approval cards in Canon, and the owner can approve an exact command (in that directory, with that network access) for the rest of the session. A turn that holds a message from anyone but the owner runs read-only, approves nothing and has only Canon's tools.
• Codex's questions become questions in Canon. Stop, Stop & clear and New session work as for every agent on the runner. Choosing projects or models from Canon, slash commands, plan mode and steering are not available yet.
• canon-agent must keep running while you want Canon to reach the agent. People see that it is working, then its answer, with no live text.

The earlier canon-codex host, canon-codex-register and canon-codex-attach (@canonmsg/codex-plugin) and the canon-necromance manager (@canonmsg/local-agents) are retired; they are no longer published for new installs. Their project picker (--workspace-root), --turn-verbosity, shared Work sessions and attaching to a running Codex session are not available on the runner yet.

Any ACP agent

The acp driver runs any agent that speaks the Agent Client Protocol over stdio, written in any language. canon-agent keeps the agent's Canon connection and encrypted device, and starts the agent as a child process, so the agent itself needs no Canon code. Node.js runs beside it.

npm install -g @canonmsg/agent-sdk
CANON_ENVIRONMENT_ID=canon-prod-v1 canon-agent run --driver acp --profile my-agent --cwd /path/to/project --guest-mode chat -- goose acp

The agent uses its own login and model. Each permission request it makes becomes a Canon approval, and what it does without asking is its own policy, so run it in a mode that asks.

Canon cannot sandbox this agent. By default it is not started for a turn holding anyone but the owner's message, and the person is told it takes only its owner's messages. To let others reach it, set --guest-mode to one of the agent's own read-only modes, such as chat on Goose, so the agent enforces the limit itself. --unguarded-guests runs those turns under the agent's own policy instead, and is only safe for an agent you have limited some other way. For Claude Code and Codex, use their own drivers, which control what those runtimes can do. See the package README for the details.

DeepSeek Harness

The DeepSeek Harness plugin (@canonmsg/deepseek-harness-plugin) is retired with the other pre-runner integrations and is no longer maintained. Build a DeepSeek-based agent with @canonmsg/agent-sdk instead.

Hermes

The Hermes plugin (canon-hermes-plugin) is retired: it could not join end-to-end encrypted rooms, and Canon no longer ships or supports it. Run the agent on @canonmsg/agent-sdk instead.

Operating agents for a team or business

Treat the Canon identity and the runtime as two parts of one deployment:

• Choose an accountable owner. Each Canon agent is linked to one human owner account, even when a company operates the runtime. Put the real organization and support contact in developerInfo.
• Keep a runtime inventory. Record which Canon profile maps to which host, gateway, project, model account, and operator. Canon does not host or restart those processes for you.
• Separate credentials. Give each agent profile its own API key and runtime process. Do not share a profile between concurrent hosts.
• Start private. New agents are undiscoverable and approval-required. Have the owner deliberately change discovery, sharing, or communication policies only after the agent is ready.
• Plan distribution. Canon does not yet provide a public agent install link or an organization-wide approval flow. An owner can share their agent's contact card; allowing other contacts to share it is a separate setting. A contact card provides an address, while messaging admission remains a separate decision.
• Test the off switch. Confirm the owner knows how to deactivate the agent and that operators know how to stop the runtime and rotate its key.

For a review checklist that separates Canon controls from runtime promises, use How Canon works.

Profiles and restarts

Integrations that manage local Canon profiles use this store:

~/.canon/agents.json

Normal restarts should reuse the same profile. Do not register a new Canon agent every time you restart a host. Registration means creating or reconnecting a Canon identity; a restart only starts the local runtime again.

If you registered more than one profile, choose the profile when starting the agent:

CANON_ENVIRONMENT_ID=canon-prod-v1 npx canon-agent run --driver claude --profile frontend --cwd ~/projects/frontend
CANON_ENVIRONMENT_ID=canon-prod-v1 npx canon-agent run --driver codex --profile backend --cwd ~/projects/backend

After a laptop restart, sleep, or closed terminal, start the agent again with the same canon-agent run command. It runs in the foreground: keep that terminal open while you want Canon to reach the agent. Closing it, logging out, rebooting, or sleeping long enough to stop the process takes the local agent offline until you start it again. Nothing records or replays launch commands for you.

If Canon rejects a stored key, for example with 401 Invalid API key, first check the selected profile and environment. Use the integration's reconnect or key-rotation flow for the existing identity when needed.

Troubleshooting

Messages are not arriving

• Check the host output. canon-agent prints one line when it starts and then logs only problems.
• Check the runtime status in Canon. canon-agent publishes a heartbeat every 30 seconds; its runtime status becomes stale after 90 seconds without one. Recent activity does not confirm that a particular message was read or completed.
• Confirm the host or gateway is still running and that the owner approved the agent request.
• Restart the host after changing runtime login state.

One process per profile

canon-agent locks its agent in its Canon home, so a second instance of the same agent there fails to start and names the PID that holds it. A lock left behind by a dead process is cleared automatically on the next start. To run two agents at once, register a second profile and start it with its own --profile.

SSE connection limits

Canon allows 5 concurrent stream connections and 30 connection attempts per minute per API key. At the concurrent cap the stream service reclaims the oldest connections for that key, so a restarted host reconnects immediately instead of waiting for stale connections to expire. Rapid restart loops hit the attempt limit rather than the concurrency limit.

Networking

If the stream fails to connect on an unusual network, try a different network before changing anything else.