---
title: One computer, several people
nav: Shared computer
summary: Two plans — several instances on one OS user (simple), or one OS user per person (stronger separation). Either way, each person takes one paid seat.
order: 20
---
# One computer, several people

A family or team can share a computer, each person with their own Agent J. In terms of the [desk analogy](/docs/what/#desk), each person is a desk of their own: their own Agent, their own chair (seat), their own remotes and conversation. **Each person takes one paid seat.** One account can purchase multiple seats, or each person can purchase separately; see [seat pricing](/pricing/). Never reuse a bound installation code or copy another person's Agent J state folder.

## Which plan

| | Plan A: instances on one OS user (recommended) | Plan B: one OS user per person |
|---|---|---|
| Setup | three commands, no admin rights, no switching logins | create an OS user, switch to it, install there |
| Separate | Agent J data, remotes, conversations, preferences, background service, working folder | everything, enforced by the operating system |
| Still shared | the OS user's other files (`~/.ssh`, cloud keys, other projects, browser data), the AI logins and their quota, the program | only the machine (CPU, memory, disk, sleep settings) |
| Fits | family members or colleagues who trust each other, with nothing on the computer the other must not see | sensitive data on the computer (key stores, production servers, finances), or files people must keep from each other |

One question decides it: is there anything on this computer the other person's Agent must not read? If yes, plan B; if not, plan A is simpler.

## Plan A: several instances on one OS user

Each person gets a **numbered instance** (1–10). Instance 1 is the Agent J this computer already had: no option means instance 1, and it never moves. The second person uses 2, the third 3, and so on. Each instance has its own identity keys, relay channel, remotes, preferences, background service and working folder. A remote pairs with one instance, so messages never cross: one person's phone cannot connect to another person's instance or see their conversation.

Requires Agent J **0.20.0 or later** (`agentj --version`), with instance 1 installed and `agentj doctor` healthy. Linux uses a systemd user service and bubblewrap, macOS a LaunchAgent and sandbox-exec, as for a single install. The Agent on the computer ships with the `agentj-multi-seat` skill: just tell it "add another Agent J on this computer for Alex" and it follows this page step by step, stopping for the steps a person must do.

### Add an instance

First get an empty seat for this person on the account page (see [account](/docs/account/)) and press "Copy installation prompt" for the installation code. Keep the code only in a file with mode 600, delete it afterwards, and never paste it into chat.

```bash
agentj instances                                            # which numbers exist; use the smallest free one
agentj --instance 2 pair --check                            # creates instance 2 when missing (no pairing yet)
agentj --instance 2 login --seat-file /path/to/0600-file    # bind this person's seat
agentj --instance 2 pair --check                            # about half a minute later the route is account
agentj --instance 2 pair                                    # pair this person's phone
```

Creating an instance makes a new identity (`~/.local/state/agentj-2`), connects the same AI tool as instance 1 in `~/agentj-seats/2` with an **independent, fenced session** (instances 2 and up never share a desktop session), and installs its background service `agentj-2` (macOS `net.agentj.host.2`), started at login or boot.

### Pair this person's phone

The instance must be bound and online first. Two ways:

**Account page (no terminal, no passphrase).** On the account page, find this instance's own seat card (each instance has one) and choose "Add a remote (phone or browser)". Confirm with the account passkey, then scan the QR code with that person's phone (valid 5 minutes, one remote), or copy the pairing link on the card and open it on that phone.

**Terminal on this computer (also over SSH).** The person runs `agentj --instance 2 pair` and scans the QR code (valid 5 minutes, one use). When the phone cannot scan the terminal, `agentj --instance 2 pair --link` prints the link as well and `agentj --instance 2 pair --no-qr` prints only the link; the link is the pairing key, so open it on that phone yourself and never send it to anyone else. When the phone connects it shows a 6-digit code: type it into the same terminal (3 tries), or approve on the seat card with the passkey; whichever comes first counts. If this instance has an approval passphrase, the terminal asks for it too.

**Each instance has its own approval passphrase**, used only for terminal approvals. Always include the number: `agentj --instance 2 passphrase set` (choose one), `passphrase status`, `passphrase change`, `passphrase reset` (forgotten: deletes it and unpairs every remote of that instance). Without `--instance 2` these commands change instance 1's passphrase. The approval passphrase and the 6-digit code are always typed by a person, never sent in chat.

Then name it, add a note and check it:

```bash
agentj --instance 2 name Alex-J                             # the Agent name the phone shows
agentj --instance 2 label "Sales - Alex"                    # local note, shown only by agentj instances
agentj --instance 2 doctor
```

Every subcommand accepts `--instance N`; or `export AGENTJ_INSTANCE=N` first. To use another parent folder, set `AGENTJ_SEATS_ROOT` before creating.

| | Instance 1 (the original) | Instance N (2–10) |
|---|---|---|
| State (keys, remotes, logs) | `~/.local/state/agentj` | `~/.local/state/agentj-N` |
| Preferences | `~/.config/agentj/config.json5` | `~/.config/agentj-N/config.json5` |
| Background service | `agentj` / `net.agentj.host` | `agentj-N` / `net.agentj.host.N` |
| Working folder | unchanged | `~/agentj-seats/N` |

### Every instance needs a valid seat

From 0.20.0 every instance must be bound to its own valid seat. An instance that is not bound, whose seat is suspended (beyond the paid seats and past the grace period), or that could not confirm its seat with the Agent J account service for more than 72 hours passes no phone or Telegram message to its Agent and cannot pair a remote; it says why and where to fix it. The seat certificate is issued to each instance's own channel, so a seat on instance 1 does not cover instance 2. Check `seat` in `agentj --instance N status`.

### Upgrade, list and remove

All instances run one installed program. When any instance upgrades (`agentj update apply` or the phone's update button), every other running instance restarts on its own once idle, within 10 minutes; there is no need to upgrade each one. The nightly auto-update runs on instance 1 only. `agentj instances` lists number, name, online state, remotes, seat and working folder.

```bash
agentj --instance 3 unlink              # give the seat back to the account first; it becomes an empty seat again
agentj instances remove 3               # stops the service, deletes its state and preferences; the working folder stays
```

Instance 1 cannot be removed this way. To drop one phone only, use `agentj --instance 3 devices` and `agentj --instance 3 revoke <id>`.

### Good to know

- One Telegram bot connects to one instance only; give each instance its own bot if they use Telegram.
- All instances share this OS user's Claude Code and Codex logins, **and their quota**. To separate them, the person runs `claude setup-token` with their own account and writes the token into that instance's service env file (mode 600), then restarts the service; tokens never go through chat.
- Keep-awake is a whole-computer setting, managed on instance 1 only; the password-free admin helper exists once per OS user and belongs to instance 1.
- Local transcription models live in each instance's own folder, one copy each.

### What the separation covers

Plan A is **session and visibility separation, not a security boundary between people**. Each instance's Agent runs fenced and cannot see the other instances' keys, remotes, chat history or preferences, or other people's working folders. It can still see the rest of this OS user's files (`~/.ssh`, `~/.aws`, other projects, browser data), and an Agent can manage this user's background services. For real separation, use plan B.

### Exact prompt for your Agent (plan A)

```text
Help me add another Agent J instance on this computer for a second person. First read the full https://agentj.app/docs/multi-seat/en.md, confirm agentj is 0.20.0 or later and instance 1's doctor is healthy. Run agentj instances, pick the smallest free number, confirm it with me, then create it with agentj --instance N pair --check. I put the installation code in a file with mode 600; you only run agentj --instance N login --seat-file <file>, and never ask me to paste the code into chat. After binding, wait until the route is account, then ask me to run agentj --instance N pair myself to pair that person's phone; the passphrase and the 6-digit code are typed by a person. Finally run agentj --instance N doctor, report every ! and ✗ as it is, and explain in a sentence or two what this instance can and cannot see. Do not change instance 1's settings, seat or pairings.
```

## Plan B: one OS user per person

Each person creates their own operating-system user and installs Agent J inside it. Two users count as two computers, each with its own installation code, AI logins and phone pairing; everyone runs `agentj`. Within one account, choose different Agent names so you can distinguish them; sharing a hostname does not merge seats.

### macOS: create a user and switch without logging out

1. Open Apple menu → System Settings → Users & Groups → Add User. Create a standard user with a password, rather than a temporary Guest account. Enter administrator authorization only in the system prompt.
2. Enable Fast User Switching. Recent macOS versions use System Settings → Menu Bar → Add Controls → Fast User Switching, with an option to add it to Control Center. Older versions use System Settings → Control Center → Fast User Switching.
3. Switch to the new user, open Terminal and [set up AI tools](/docs/setup-agents/) with that person's own login. Follow the [installation page](/install/) inside this account.
4. Use a separate installation code and pair that person's phone. Switch back with Fast User Switching, keeping both users logged in. Background work continues while a user is switched out.

For an Agent comfortable with Terminal: check `sysadminctl -h` and whether the short username already exists. The following example asks for the password interactively; never place a password in arguments, chat or logs.

```bash
sudo sysadminctl -addUser spouse -fullName 'Second User' -password -
```

Replace `spouse` with an agreed, unused short username. The owner must enter the password at the computer's interactive terminal. If your tool cannot provide an interactive prompt, use System Settings. Do not automatically grant administrator rights.

**After a reboot, log in once as the second user.** macOS generally offers automatic login for one user; FileVault or other settings may prevent it entirely. Agent J runs as a LaunchAgent in a GUI login session. SSH login alone is insufficient. `agentj doctor` checks that session. When the computer stays unreachable, the phone's grey offline page explains that this Mac seems to have restarted and needs a login at the computer. Fast User Switching keeps an existing login alive; it does not start an account that has never logged in since boot.

References: [Apple: add a user](https://support.apple.com/guide/mac-help/mchl3e281fc9/mac), [Apple: switch users](https://support.apple.com/guide/mac-help/mchlp2439/mac).

### Linux: create a user and enable linger

Use your distribution's user settings to create a standard account, or run these commands with an agreed, unused username:

```bash
sudo useradd -m -s /bin/bash spouse
sudo passwd spouse
sudo loginctl enable-linger spouse
loginctl show-user spouse -p Linger
```

Enter passwords only at the interactive `passwd` prompt. An already paired Agent can request administrator rights with the `agentj sudo` phone password card; creating a password still needs an interactive system prompt. Never send it in chat.

Log in as the new user through the desktop or SSH. Sign into that person's AI tools, install Agent J, bind their seat and pair their phone. Installation recommends linger and `agentj doctor` warns when it is off; neither forces it on. Verify `Linger=yes`. Inside the new account you can also run:

```bash
loginctl enable-linger "$USER"
agentj service status
agentj doctor
```

Linger starts this user's systemd services at boot and keeps them running after logout, without requiring a desktop login. The computer must still be powered on and online, with its data and AI credentials accessible. Linger cannot unlock a home directory encrypted until login. A distribution without systemd needs an equivalent service arrangement.

Reference: [systemd loginctl](https://www.freedesktop.org/software/systemd/man/latest/loginctl.html).

### Windows with WSL2

The Agent J host runs in WSL2. Give each person a separate Windows user and a WSL2 distribution installed from that Windows login. Install Agent J, sign into AI tools and pair a phone separately inside each distribution. Adding only a Linux user within a shared distribution is not the same as a separate Windows account and distribution.

With systemd enabled in WSL, linger works within the running distribution, but **cannot start a stopped WSL virtual machine**. After rebooting Windows, log into that person's Windows account, open WSL and check `agentj service status`. Validate any Windows startup arrangement separately if unattended operation is needed. Configure computer sleep on the Windows side.

[Microsoft: systemd in WSL](https://learn.microsoft.com/en-us/windows/wsl/systemd) · [WSL security boundaries](https://github.com/microsoft/WSL/blob/master/doc/docs/technical-documentation/security.md).

### Isolation and shared limits

- Each OS user owns their home, Agent J state, AI logins, paired phones and conversations. Do not share a state folder or browser data directory, or open home permissions to the other user. System administrators still have access to local files.
- CPU, RAM, disk, GPU and network are shared. Two local speech models use two allocations of memory. Reduce concurrency or choose a cloud provider for your own seat when resources run short.
- Local settings pages and Agent J-managed OpenCode services automatically select free ports. Local ASR uses child-process pipes; statusline files and control sockets live in private user directories. Explicitly assigning the same port can still collide. If you separately set up browser automation, choose a free CDP port and a private browser data directory for each user instead of sharing fixed port 9222.
- Sleep policy, power and shutdown affect the entire computer. Record originals before changing settings and coordinate with other users. Restore only when the last user no longer needs the machine awake, and only after checking the value still matches your change. Never restore another seat's settings from one user's old snapshot. Lid closure, lost power and manual sleep can still disconnect every seat.
- The optional signed sudo helper now installs separately by OS UID. Users with a legacy helper must run `agentj sudo-helper install` again in their own account and authorize the phone card. Legacy machine-wide files are retained; never uninstall on another user's behalf.

### Exact prompt for your Agent (plan B)

Copy this to the Agent on the computer. The owner confirms the new username:

```text
Help me create a separate OS user for a second person on this computer and guide them through their own Agent J installation. First read the full https://agentj.app/docs/multi-seat/en.md and https://agentj.app/install.md. Check the OS, existing usernames and administrator access. Each OS user counts as a separate computer and requires a paid seat and their own installation code. Ask me to confirm the short username, then create a standard user. Passwords belong only in an interactive system prompt or a paired Agent J phone password card, never in chat, command arguments or logs. Preserve existing users' AI logins, seats, pairings and configuration; do not copy their state folders. On Linux recommend enabling this user's linger and verify it. On macOS explain Fast User Switching and remind me to log into the second user's GUI once after reboot. Then have me switch to the new account to sign into its AI tools, install following install.md and pair its own phone. Check the service and doctor for each installation. Explain actions I must take in the new account; do not install on its behalf from the old user's account.
```

Continue: [installation steps](/docs/install/) · [install page](/install/) · [FAQ](/docs/faq/).