Connect more than one agent
One owner account holds as many agents as you pair. Each agent is separate, with its own accounts, its own wallet, and its own name. You switch between them from the agent pills at the top of the agent view.
The rule that decides everything
An agent is a paired runtime. One runtime installation holds one live agent, because it has one citizen-ai MCP server. A second agent pairs from its own runtime installation, usually on its own machine.
If you send the setup link again to a runtime that is already paired, its MCP server gets the token of the new agent. The earlier agent stays in your account, but that runtime stops serving it. Pair the second agent on a second machine.
Add a second agent
- Prepare a second machine with an agent runtime. A laptop, a desktop, or a VPS all work. It needs Node.js 24 or newer.
- Open the agent view and select Connect another agent. The Connect an agent dialog opens.
- Copy the prompt and send it to the agent on the second machine.
- Open the approval link that the agent sends you. Choose a new agent, not a reconnect.
- Name the new agent. The name is how you tell the pills apart.
- The agent calls
citizenai_list_accountsto verify the connection.
The full setup is in Connect your agent.
What each agent keeps to itself
| Item | Shared across your agents |
|---|---|
| Owner account and sign-in | Yes |
| Payment history | Yes |
| Provider accounts, mailboxes, phone numbers | No |
| Wallet and balance | No |
| Marketplace capabilities you add | No |
| Browser profile and provider logins | No |
An agent cannot read another agent's accounts and cannot spend from another agent's wallet. See Authentication and tenancy.
Plan for this before you pair. Add a capability to each agent that needs it, and fund each wallet separately.
Switch between agents
The agent pills name every paired agent. Select a pill to open that agent. Each agent has its own URL, so you can bookmark one agent and return straight to it.
Which agent does the marketplace add to?
The connect dialog asks which agent receives the capability. Read the agent name in the dialog before you confirm a purchase, because the capability and the charge both belong to that one agent.
When to add an agent, and when not to
| You want to | Do this |
|---|---|
| Run a second workload in parallel | Pair a second agent |
| Keep two sets of provider accounts apart | Pair a second agent |
| Move one agent to a better machine | Re-pair that agent on the new machine |
| Repair an expired token | Re-pair. See Reconnect or repair |
| Stop an agent permanently | Remove it. See Remove an agent |
If the second agent does not appear
| Symptom | What to do |
|---|---|
| The new agent replaced the first one on the machine | You paired twice on one machine. Pair the second agent on a second machine. |
| The pairing code fails | Codes are short-lived. Ask the agent to start the setup again for a fresh link. |
| The new agent shows offline | Send the setup link to it again, and reconnect it on the approval page. |
| The new agent has no capabilities | Capabilities do not transfer. Add them to the new agent in the Marketplace. |
More detail is in Pairing paths.