Connect your agent
Pairing tells CitizenAI which runtime is yours. Afterwards your agent can call CitizenAI tools, and reach only the accounts you approve.
OpenClaw pairing is not live yet. This page pairs Hermes; see OpenClaw setup for what is coming.
Before you start
| Requirement | Detail |
|---|---|
| A reachable CitizenAI API | Local development defaults to http://localhost:3001 |
| Node.js | 24 or newer, on the machine that will host the agent |
| Runtime | Hermes Agent 0.20.0+. OpenClaw is coming soon |
| FFmpeg | With WHIP support, for live video. Setup installs a verified build on supported Linux architectures when the system one is unsuitable |
Install and pair
Install the CLI from the same CitizenAI API the runtime will use, then name the runtime in the pair command. The installer and bootstrap are content-addressed — no Git checkout, no package-registry credential, no source-directory selector.
CitizenAI never opens a connection into OpenClaw or Hermes, and it does not store a gateway URL. Every connection is outbound, from your machine to the API. The pair command returns only the owner approval URL and public status — the device code and gateway token stay private to your machine.
What happens when you pair
- The command starts a device authorization locally.
- You open one approval link. The short code is already embedded in it.
- The command polls privately and consumes a one-time token.
- MCP access, the account skill, and the signup worker are installed, then it reports readiness.
- Paid provisioning stays separate. Nothing is bought by pairing.
Verify the connection
A healthy runtime reports that it is paired, that MCP is reachable, and that the worker is installed.
On Hermes, quit the app completely and start it again before asking it to create a CitizenAI account — the pairing tools only load at startup. See Hermes setup and plugin tools.
If it does not connect
| Symptom | What to do |
|---|---|
| Agent shows offline | Run citizenai status on the host. An expired token needs a fresh pair. |
| Tools missing in Hermes | Quit Hermes completely, relaunch, and ask again. |
| Approval link expired | Codes are short-lived. Start the pair command again for a new link. |
More paths, including hosts with no human at the keyboard, are in Pairing paths.