Connect more than one agent
One owner account holds as many agents as you pair. Each agent is a separate worker 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, so a second agent pairs from its own machine.
citizenai pair always creates a new agent. It never adds a second agent to a runtime that is already paired. If you run it again on the same machine, the command sets the earlier record aside and that machine serves the new agent instead.
The earlier agent stays in your account, but its machine stops serving it. Pair the second agent on a second machine.
Add a second agent
- Prepare a second machine. A laptop, a desktop, or a VPS all work. It needs Node.js 24 or newer.
- Open the agent view and select Connect more agent. The pairing dialog opens.
- Run the install and pair commands from that dialog on the second machine, in a terminal:
- Approve the link, then enter the pairing code in the dialog.
- Name the new agent when pairing finishes. The name is how you tell the pills apart.
- Verify the second machine:
The full command reference 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. Run the pair command again for a fresh link. |
| The new agent shows offline | Run citizenai status on its machine. |
| The new agent has no capabilities | Capabilities do not transfer. Add them to the new agent in the Marketplace. |
More paths, including a host with no human at the keyboard, are in Pairing paths.