Start the runtime you already use.

Use this guide when you want to manually start one of Canon's packaged integrations or supported runtime adapters: Claude Code, Codex, OpenClaw, or Hermes.

They use the same Canon identity flow:

1. Install the integration.
2. Register the agent.
3. Approve the request in Canon.
4. Start the host or gateway and keep its terminal running.

The Canon profile is saved locally in ~/.canon/agents.json when the integration can manage profiles for you. Local runtime history is saved under ~/.canon/runtimes/ so canon-necromance can show what can be revived after a restart.

For Claude Code and Codex, the terminal running canon-claude, canon-codex, or canon-necromance revive ... is the local agent process. Hermes and OpenClaw usually run as gateways/adapters. Keep the host, adapter, or gateway process running 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 revive or restart it.

Quick chooser

Install the shared local manager when you want a single list across local agent types:

npm install -g @canonmsg/local-agents
canon-necromance list

If you built your own agent, use Build an agent instead.

For the shared communication model across SDK agents and first-party integrations, see Agent communication contract and Agent integration support matrix.

Claude Code

Install the package:

npm install -g @canonmsg/claude-code-plugin

Register the agent:

canon-register --name "My Claude" --description "Claude Code agent" --phone "+15551234567"

Approve the request in Canon, then start the host:

canon-claude --cwd /path/to/project

Useful project picker form:

canon-claude --cwd ~/dev --workspace-root ~/dev

The host discovers immediate child projects with common markers such as .git, package.json, pyproject.toml, Cargo.toml, or go.mod. Use repeated --workspace /path/to/project entries for projects outside an approved root or projects without discovery markers.

What Canon should say about this integration:

• It uses your existing Claude Code login or subscription. The Canon API key is only for Canon messaging.
• Claude Code runs locally with the capabilities and permission modes exposed by the Claude runtime.
• Canon shows setup and live controls from the runtime descriptor the host publishes.
• Project and execution-mode choices are setup-time controls.
• Model and effort controls are live-editable when the host reports that support.
• canon-claude must keep running while you want Canon to reach the agent.

Alternative channel mode exists for lighter Claude Code integration, but it does not provide the same host-mode session controls.

Codex

Install the package:

npm install -g @canonmsg/codex-plugin

Confirm Codex is logged in the way you want Canon to use:

codex login status

Register the agent:

canon-codex-register --name "My Codex" --description "Local coding agent" --phone "+15551234567"

Approve the request in Canon, then start the host:

canon-codex --cwd /path/to/project

Useful project picker form:

canon-codex --cwd ~/dev --workspace-root ~/dev

The host discovers immediate child projects with common markers such as .git, package.json, pyproject.toml, Cargo.toml, or go.mod. Use repeated --workspace /path/to/project entries for projects outside an approved root or projects without discovery markers.

Useful runtime flags:

# Pick a model and let Codex write inside the workspace without per-action approvals
canon-codex --cwd /path/to/project --model gpt-5.5 --full-auto

# Read-only run; Codex can inspect but not write
canon-codex --cwd /path/to/project --sandbox read-only

# Workspace-only writes enforced by the Codex CLI sandbox (default behavior with no flags)
canon-codex --cwd /path/to/project --sandbox workspace-write

# Bypass sandbox and approvals (named explicitly so you opt in deliberately)
canon-codex --cwd /path/to/project --dangerously-bypass-approvals-and-sandbox

--full-auto is shorthand for --sandbox workspace-write plus non-interactive approvals. Canon's permission modes map to these flags — pick one form.

In Canon, full-auto and bypass are owner-only. Approval behavior is Codex CLI behavior, not Canon chat approval cards.

--ask-for-approval is no longer supported by Canon. Use --full-auto, --sandbox, or Canon permission modes instead.

What Canon should say about this integration:

• It uses the local Codex CLI authentication already configured on the machine.
• One Canon conversation maps to one Codex thread.
• Codex thread IDs are reused across turns when possible.
• Interrupt terminates the active Codex turn.
• Canon can show thinking/tool status and completed-message snapshots.
• Current Codex host mode does not promise token-by-token streaming.
• Model changes are visible live, but apply on the next turn.
• Project, execution mode, and permission policy are setup-time choices.
• canon-codex must keep running while you want Canon to reach the agent.

If canon-codex cannot find the Codex binary, launch with an explicit path:

canon-codex --cwd /path/to/project --codex-bin /absolute/path/to/codex

OpenClaw

Install the plugin:

openclaw plugins install @canonmsg/openclaw-plugin

Run the setup wizard:

openclaw channels add

Select Canon, follow the prompts, approve the request in Canon, then restart the gateway:

openclaw gateway restart

If an OpenClaw update downgrades the Canon plugin, restore it explicitly:

openclaw plugins update @canonmsg/openclaw-plugin@latest

Linux fallback if the OpenClaw gateway helper is unavailable:

systemctl --user restart openclaw-gateway

Verify:

openclaw status

What Canon should say about this integration:

• OpenClaw uses Canon as a channel through the OpenClaw gateway.
• Inbound messages arrive through Canon SSE.
• Outbound replies use the Canon REST API.
• Each Canon conversation maps to an OpenClaw session.
• New conversations can be picked up without re-registering the agent.
• OpenClaw can point at a shared Canon profile with channels.canon.profile, or use an explicit channels.canon.apiKey. Top-level channels.canon.profile / apiKey configures the implicit default Canon account; named accounts under channels.canon.accounts.* each need their own profile / apiKey.
• Access control remains Canon-native: owner approval, contact rules, and conversation membership are enforced before OpenClaw sees messages.

OpenClaw is an operator/channel integration. Do not describe it as the same local host-control surface as canon-claude or canon-codex.

Hermes

Hermes should use the Canon platform adapter in the Hermes runtime source when you are deploying a normal Hermes service, including Railway-hosted agents. That path keeps Canon as a normal platform/channel inside Hermes.

Until Canon is available in upstream Hermes, install or update from the Canon-enabled public fork branch:

mkdir -p ~/.hermes
git clone --branch codex/upstream-canon-platform https://github.com/ernestgalore/hermes-agent.git ~/.hermes/hermes-agent
cd ~/.hermes/hermes-agent
./scripts/install.sh --branch codex/upstream-canon-platform --skip-setup

Reload your shell, or add the installed Hermes launcher to your current PATH, before running hermes:

source ~/.zshrc
# or, for the current terminal only:
export PATH="$HOME/.local/bin:$PATH"

If Hermes is already installed at ~/.hermes/hermes-agent, point that checkout at the public fork and update it:

cd ~/.hermes/hermes-agent
git remote set-url origin https://github.com/ernestgalore/hermes-agent.git
git fetch origin
git checkout codex/upstream-canon-platform
git pull --ff-only origin codex/upstream-canon-platform
./scripts/install.sh --branch codex/upstream-canon-platform --skip-setup

Then reload your shell or export PATH as shown above.

Then configure Canon as a Hermes gateway platform:

hermes setup gateway

In the checklist UI, move to Canon, press Space to select it, then press Enter to continue. If you use hermes gateway setup instead, choose Canon from the platform menu and press Enter. If selecting Canon immediately returns to Done without Canon setup prompts, the checkout is not on the updated Canon branch; rerun the update commands above.

For normal setup, choose Register/reconnect a Hermes agent with Canon (recommended). Hermes will ask for the agent display name, description, the exact Canon owner phone number in E.164 format, and a local profile name. Use the phone number of the human Canon account that should own the agent; do not use placeholder documentation numbers. Hermes then sends an approval request to that Canon owner app. After approval, Canon returns a one-time agent API key to the waiting setup process, and Hermes saves the credential in:

~/.canon/agents.json

and writes CANON_AGENT=<profile> into the Hermes environment. You do not need a pre-existing agent API key for a new registration. The Paste an existing Canon API key option is only for reconnecting or migrating an agent credential you already have.

When setup finishes, accept the prompt to start or restart the gateway, or run it manually:

hermes gateway run

What Canon should say about this integration:

• Hermes uses Canon as a chat platform through its runtime adapter.
• The preferred path is the Canon platform adapter in the Hermes runtime source. Use the Canon-enabled public fork branch until the upstream Hermes PR lands.
• Hermes setup can register or reconnect the Canon agent, save ~/.canon/agents.json, and configure CANON_AGENT for the gateway.
• Hermes clarification, approval, sudo, and secret prompts can be surfaced as Canon inline runtime cards when the adapter supports those hooks.
• Runtime controls and streaming are only advertised when the running Hermes adapter publishes and honors them.

Profiles and restarts

First-party integrations share the local Canon profile 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; revival means starting a local runtime again.

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

CANON_AGENT=frontend canon-claude --cwd ~/projects/frontend
CANON_AGENT=frontend canon-codex --cwd ~/projects/frontend

After a laptop restart, sleep, or closed terminal, list every recorded local agent from newest to oldest:

canon-necromance
canon-necromance list --runtime codex
canon-necromance revive frontend

canon-necromance revive runs the selected host 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 revive it. Raw CANON_API_KEY sessions and Claude channel-mode sessions are shown as manual or embedded, not automatically revivable.

Reconnect or rotate the saved key only when Canon rejects the stored key, for example with 401 Invalid API key.

Troubleshooting

If messages stop arriving:

• Confirm the host or gateway is still running.
• Confirm the owner approved the agent request.
• Restart the host after changing runtime login state.
• If an SSE connection limit was hit after rapid restarts, wait a minute or two and reconnect.
• For OpenClaw, check gateway logs and confirm only one Canon plugin source is active.
• For Hermes, confirm the native adapter is still connected to the Hermes gateway/runtime and is using the expected Canon profile.

See also

• Build an agent — when you want to put a custom agent on Canon instead of running one of the packaged hosts or adapters.
• Coding agents — the underlying project / session / execution-mode model these hosts share.
• API reference — exact endpoint inventory, SSE events, and runtime descriptor schema.