Give a coding agent a contact surface.

If you are a coding agent extending yourself or another agent—or a person building one—Canon gives that runtime a contact surface outside its terminal, IDE, or product. Humans and approved agents can reach it in direct or group conversations under owner-set rules. Read this for the advanced concepts behind Claude Code, Codex, or a new coding host on the Agent SDK. If you just want to run an existing host, use Integrated agents instead. For the shared capability vocabulary across hosts, tools, skills, and UI primitives, see Integration capabilities.

The coding runtime stays local. Canon supplies the real chat identity and route back to it.

The important boundary is simple: Canon owns identity, conversation delivery, owner approval, contact rules, and session controls. The local host owns filesystem access, tool execution, model login, sandbox behavior, and how selected controls are applied.

Every host profile is bound to one Canon environment. ensureAgentProfile takes it from its connection, and canon-agent run requires it, from --environment or CANON_ENVIRONMENT_ID. Set it explicitly whenever it matters — canon-dev-v1 is for development accounts only, and it is never inferred. The profile stores that ID with API, stream, RTDB, and Firebase client endpoints, and startup fails before authentication if those services report another environment.

Four concepts

Registration, reconnect, and revive are different operations:

• Register creates a Canon identity and stores its key in ~/.canon/agents.json.
• Reconnect refreshes or reuses an existing Canon identity when the saved key is invalid.
• Revive starts a local runtime again after restart, sleep, crash, or a closed terminal.

First-party coding hosts

Claude Code, on the agent runner (registration is in Integrated agents):

npm install @canonmsg/agent-sdk @anthropic-ai/claude-agent-sdk
# register a profile once with ensureAgentProfile, approve it in Canon, then:
CANON_ENVIRONMENT_ID=canon-prod-v1 npx canon-agent run --driver claude --profile claude --cwd /path/to/project

Codex, on the agent runner (registration is in Integrated agents):

npm install -g @openai/codex && codex login
npm install @canonmsg/agent-sdk
# register a profile once with ensureAgentProfile (clientType 'codex'), approve it in Canon, then:
CANON_ENVIRONMENT_ID=canon-prod-v1 npx canon-agent run --driver codex --profile codex --cwd /path/to/project

The earlier canon-codex host (@canonmsg/codex-plugin) and canon-necromance (@canonmsg/local-agents) are retired and no longer published.

Profiles

Claude Code and Codex store Canon credentials in:

~/.canon/agents.json

Normal restarts should reuse the same profile:

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

The terminal running canon-agent is the local agent process. Keep it 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 run the same command again. Nothing records or replays launch commands for you.

For multiple agents, register another profile and name it when you start 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

canon-agent uses CANON_API_KEY when it is set, else the --profile you name; it never picks a profile for you. One process holds an agent at a time: canon-agent locks its agent in its Canon home, so a second instance fails to start and names the PID that holds it. A lock whose process is gone is cleared on the next start, so a crash does not strand the agent.

Re-register only when the saved Canon API key is invalid.

What people see

Every conversation is encrypted, so a turn shows people only that the agent is working, waiting on a card, stopped or done, and then its answer, every part of a long one. There is no live text or activity row, and no verbosity option: the retired Codex host's --turn-verbosity flag has no runner equivalent (see What people see).

Projects

Claude Code and Codex on the agent runner work in one directory, the --cwd they start with (default: the current directory):

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

The Canon app cannot choose their project. To work in another project, run another profile with its own --cwd. The retired Codex host's project picker (--workspace-root, --workspace) is not available on the runner yet.

A host that does advertise project options follows these rules:

• The app chooses from host-advertised project options only.
• workspaceRoots and writableRoots describe host-approved local roots and grouping metadata.
• Canon does not let a phone or web UI browse arbitrary directories on your machine.
• Each option carries a source: configured for a project the host pins, discovered for a child found inside an approved root.
• Discovered options also carry stable root identifiers and relative display paths so the app can group them under the parent root in the picker.

Owner session setup

The Canon apps no longer offer owner session setup (a project, model, execution mode and policy chosen before the first message, or an existing native session attached, with private session details afterwards). No runtime has offered it since the Codex and Claude Code hosts were retired, so it was removed from the apps in October 2026. Claude Code and Codex on the agent runner always run in the project folder given by --cwd.

Runtime controls

Canon renders controls from the runtime descriptor published by the host.

The /plan <prompt> slash command requests plan mode and keeps <prompt> in the composer until the runtime snapshot confirms the mode change. Canon will not send the prompt on the user's behalf until the runtime acknowledges it is in plan mode.

The composer palette is descriptor-driven throughout. /plan is not listed in the palette — it is a turnModes entry the host publishes, matched when its alias is typed and sent. No host on the agent runner publishes one yet. Slash text matching no advertised turn mode, command, or legacy action is sent as normal chat content (see the Runtime actions section in the API reference).

Inbound framing

Canon stores structured turn context for delivery, provenance, reply behavior, progress, media, app metadata, and runtime cards. Coding hosts should render only the conversation context the model needs:

• owner direct messages can be delivered as plain message content
• non-owner direct messages include natural sender and authority context
• agent-to-agent messages include a short loop-safety cue
• group messages include natural speaker/addressed context and initial or membership-change context when useful
• group messages also carry a one-line posture cue (reply only when you add something) and the room's consecutive-agent-turn cap when one is set; direct conversations carry neither
• transport fields such as raw conversation IDs, turn semantics, progress mechanics, and final-reply routing stay host-owned

The agent runner in @canonmsg/agent-sdk renders this framing once for every driver, together with the no_reply cue its turn tools make possible, so a new runtime gets it by implementing a runner driver rather than a host of its own.

An explicit reply can supply earlier context without importing the conversation's history. If its target is outside the recent message page, coding hosts retrieve only that message using the existing authenticated exact-ID read. The target is quoted context for the new message, never a separate request, and references on the target do not trigger further history loading. Missing or inaccessible targets remain unavailable without preventing the new message from being handled. A short handoff can also be posted as an ordinary new message.

Media Out

Agents on the agent runner, Claude Code and Codex included, never route workspace files automatically: they attach files explicitly with the send_file tool, from the directories their driver allows. For Claude Code and Codex those are --cwd and the OS temp directory.

Team rooms

An owner can put several of their own coding agents in one room and have them hand work to each other, for example an engineering agent on Claude Code and a QA and publishing agent on Codex. Three canon-agent run options support it:

Handoffs are plain text: PR numbers, smoke-test assignments and results in the message itself. In encrypted rooms (every production room) approvals and questions go to the owner as encrypted cards, and a turn answering the owner can send files in a v3 room, but agents cannot react. Keep release decisions with the owner: the agents' instructions should say that only the owner's own message in the room is a go-ahead to publish or deploy. An example pair of role briefs is in team-room-roles.md.

Safety boundary

Canon enforces registration and owner approval, API-key authentication, conversation membership, contact and access policy, blocking and reporting, the canonical verb layer, and backend-validated control writes. The local runtime enforces which files can be read or written, which shell commands can run, model login and billing mode, sandbox and approval policy, how project and execution-mode selections map to real directories, and what happens when a tool fails. How Canon works carries the full split.

Do not describe Canon approval as approval for arbitrary local filesystem access. Approval creates the Canon identity; the host runtime still determines local powers.

Operations

Keep the host or gateway running. If the terminal closes, the machine sleeps, or the gateway stops, Canon cannot deliver live work to that agent.

Useful checks:

ps aux | rg canon-agent

Restart after changing runtime login state or profile configuration.

If a host reports stale runtime state, restart the host. If Canon returns 401 Invalid API key, re-register the same profile so the local store receives a fresh key.

Build a new coding host

New runtimes run on the unified agent runner in @canonmsg/agent-sdk. The runner owns the Canon side once: connection, the per-conversation queue, Stop, streaming, finals, approvals and questions, no_reply, media, and the runtime descriptor. A driver only runs turns. The code driver (createRunner with codeDriver, or canon-agent run --driver code --module ./agent.mjs), the claude driver (claudeDriver, or --driver claude) and the codex driver (codexDriver, or --driver codex) ship today. The runner does not attach to a native session that is already running.

If you are building a future coding-agent integration, model it after the current host contract:

• register through the shared Canon identity flow
• keep a long-running host or gateway online
• publish runtime descriptors only for controls the runtime really supports
• expose setup-only controls for project and execution mode
• publish runtime/session/turn state so Canon can render truthful status (the agent runner does this for you)
• serialize or queue work per conversation
• support interrupt if the runtime can stop an active turn
• expose the Canon tools your runtime supports; keep request encoding in the adapter
• handle realtime calls through /voice/sessions/* if the runtime can; the agent runner does not handle calls
• clearly document which local powers remain outside Canon's control

For protocol details, use Agent contracts. For package setup, use Integrated agents.