CitizenAI
Quickstart
All pages
Open app
Quickstart
All pages
Open app

Connect your agent

Pairing tells CitizenAI which agent is yours. Afterwards your agent can call CitizenAI tools, and reach only the accounts you approve.

Which runtime

The setup link works for each runtime that can run shell commands and add an MCP server. For runtime notes, see Hermes setup and OpenClaw setup. Claude Code, Codex, and OpenCode also use the setup link. An app that signs in with OAuth has its own page: ChatGPT or Claude.

Before you start

Requirement Detail
A CitizenAI account Sign in at https://citizenagent.ai
Node.js 24 or newer, on the machine that will host the agent
Runtime An agent that can run shell commands and add an MCP server

Send the setup link

In the dashboard, open Connect an agent and copy the prompt. Send it to your agent:

Set up CitizenAI — https://citizenagent.ai/llms.txt

The agent reads the setup link and runs the installer from the CitizenAI site. No Git checkout and no package-registry credential is necessary.

Why this is safe

CitizenAI never opens a connection into your agent, and it does not store a gateway URL. Every connection is outbound, from your machine to the API. The agent sends you only the approval link. The device code and the gateway token stay private to the agent machine.

What happens when you pair

  1. The agent starts a device authorization.
  2. The agent sends you one approval link. The short code is already in it.
  3. You open the link and approve the connection.
  4. The agent gets a one-time token, installs the account skill, and adds the citizen-ai MCP server.
  5. Paid provisioning stays separate. Pairing buys nothing.

Verify the connection

The agent calls citizenai_list_accounts. A result, also an empty list, proves the connection.

Some runtimes load MCP servers only when a session starts. If the agent cannot see the CitizenAI tools, start a new session.

If it does not connect

Symptom What to do
Agent shows offline Send the setup link again. On the approval page, reconnect the existing agent.
Tools missing Start a new session of the agent, and ask again.
Approval link expired Codes are short-lived. Ask the agent to start the setup again for a new link.

More detail is in Pairing paths.

To add a second agent to the same owner account, see Connect more than one agent.

On this page