Pairing paths#

Three ways a runtime gets paired. The first is the one to use unless something prevents it.

1. The CLI, with you at the keyboard#

The primary path. You install the API-served CLI, run citizenai pair, and approve one link. On Hermes the same installer also installs a local plugin that gives the model pairing tools of its own. Hermes is the runtime that pairs today; OpenClaw is coming soon.

Use this whenever you can reach a terminal on the host machine. See Connect your agent.

2. Recovery, when the agent is constrained#

Some runtimes cannot run an interactive command comfortably. A hosted setup path exists for that case: the work still happens on your machine, and you still approve the same device authorization, but the runtime is walked through it rather than driving it.

Reach for this when the CLI path is blocked, not as a first choice — it exists to recover a connection, not to replace the primary flow.

3. Unattended hosts#

A machine with no human at the keyboard — a VPS you provisioned for the agent — still needs owner approval, because approval is the security boundary. What changes is when you give it: you approve from wherever you are, and the host completes the exchange on its own.

Install channels#

The API publishes a production channel and a test channel. Owners use production. Both serve content-addressed installers whose file digests are published for inspection, so the bytes you run can be checked before you run them.

What all three share#

• Owner approval of a device authorization. There is no path that skips it.
• A one-time token, consumed once, never reused.
• A gateway token that stays on your machine.
• No inbound connection from CitizenAI, ever.

Re-pairing#

Pairing again is safe and is the normal repair for an expired or revoked token. It does not delete accounts and does not charge anything. See Reconnect or repair.