<!-- Source: https://console.uubright.com/docs/multi-host/ -->
# Several computers in one window

One window can show the tasks on more than one computer at once, for example your
Mac and an EC2 server. Tasks, **Needs you** and the board list every computer's work
together, and **New task** asks which computer to run on. Each computer keeps
running its own tasks and keeps its own sign-in. Nothing is shared between servers:
the window talks to each computer separately and puts what they report side by side.

With one computer, the app looks exactly as before. The only addition is **Add a
computer** under **Server settings**.

## Add a computer

1. On the other computer, choose **Connect your phone** (in the **⋯** menu or under
   **Server settings → Devices**) and choose **Copy link**. With the
   [relay](https://console.uubright.com/docs/phone-access/) on, the link goes through it; otherwise it connects to that
   server directly. In this window, paste the link rather than typing the short code:
   the link says which computer it is for.
2. In the window you want to add it to, open **Server settings → Add a computer**.
   Paste the link, give the computer a name such as `EC2` if you like, and choose
   **Add computer**. For a relay link, compare the fingerprint shown with the one on
   the other computer first.

The window pairs itself with the other computer as a device, the same way a phone
does. It keeps that computer's device token separately from every other computer's.
The token never goes to another computer. Once a window has several computers,
**Your computers…** at the end of the sidebar opens the same list.

A computer added with a link is paired as an ordinary device: from this window you
can work on it, but only its owner can add or remove its devices, so **Connect your
phone** and **Revoke** for that computer are refused here, and that computer's own app does not
offer them to this window's sign-in. Do those on that computer
itself, with its access token, or with `npm run pair` there. The exception is a
[remote host the Mac app added over SSH](https://console.uubright.com/docs/beta/#experimental-optional-add-a-remote-host-ssh):
the app proved it is you on that host, so its pairing is owner-grade and can connect
phones to the host and remove its devices. A phone paired that way is an ordinary
device.

### Allow the two servers to talk (direct links)

A browser blocks a page from calling a different server unless both agree. So that
the window served by one computer can reach another directly, set
`CCR_CLOUD_PEER_ORIGINS` on **both** servers. List the other server's address (scheme,
host and port, no path), and restart each server:

```sh
# On the server the window is open on (say https://mac.example.ts.net):
CCR_CLOUD_PEER_ORIGINS=https://ec2.example.com
# On the server being added:
CCR_CLOUD_PEER_ORIGINS=https://mac.example.ts.net
```

The first lets that server's web app connect to the second; the second lets that
server answer the first app's requests. Only origins you list get either. A server
never accepts cookies this way: every request carries the bearer token the window
was paired with.

You don't need peer origins for computers reached through the relay. The phone app
at the relay's address can hold every computer paired with that relay. A window
served by your own server can add relay computers only on the relay that server
uses (`CCR_CLOUD_RELAY_URL`).

## What you see

- **Sidebar and Tasks:** one group per computer, each with a header you can collapse.
  Each group lists the tasks of that computer's current workspace, pinned first and
  then newest started, the same order as with one computer. Pins belong to their
  computer.
- **Connection state:** the header's dot and word show **Connected**,
  **Reconnecting…** or **Offline**. When a computer stops answering (it sleeps, or the
  network drops), its tasks stay in the list, greyed, as last seen. They are never
  removed from the list. The other computers keep working.
- **Needs you:** every computer's questions, approvals, decisions and finished work,
  each card tagged with its computer. Answering a card sends the answer to that
  computer. Room hand-offs and room questions still come from the computer you are
  working on.
- **Board:** every computer's cards together, each card naming its computer.
- **Workspaces and projects** belong to a computer. With several computers, the
  workspace switch reads `EC2 · Default`, and New task says which computer it will
  start on.

Opening another computer's task switches the window to that computer. Its
workspaces, projects and settings are then the ones shown. Both stay signed in, so
switching back is instant.

## Run on

**New task** shows a **Run on** picker when the window has more than one computer.
It starts on the computer you are working on. Choosing another keeps the prompt
you've typed and switches the workspace, projects and agents to that computer's.
An offline computer can't be chosen.

## Open in editor

The task's **⋯** menu offers its worktree in your editor:

- **On the computer this window runs on** (local mode, opened at `localhost`):
  **Open in VS Code** and **Open in Cursor** open the task's worktree.
- **On a server that offers SSH:** set `CCR_CLOUD_SSH_HOST` on that server, for
  example `ubuntu@ec2.example.com`. **Open in VS Code (Remote-SSH)** and **Open in
  Cursor (Remote-SSH)** open the worktree over SSH with your own SSH setup.
- **Otherwise:** **Copy path** copies the worktree's path.

Container (Docker) tasks have no worktree on the server, so they show none.

## Remove a computer

Open **Your computers…** (or **Server settings → Add a computer**) and choose **Remove**
beside it. The window asks that computer to revoke its device token, then forgets the
computer's entry, token, pins and seen marks. Every other computer, and this
window's own sign-in, are left alone. Tasks keep running on the computer you removed.
If it can't confirm the revocation (it's offline), the window asks before removing
it anyway. Then revoke the device under **Devices** on that computer.

## When a computer answers as someone else

Each server has a random id (`instanceId` in `GET /api/health`), kept in its data
folder. The window records it when you add the computer. It checks the id again
before sending the token, and after any connection failure. If the address now
leads to a different server, for example a reused IP address, a wrong port or a
reinstalled server, the window marks it **Refused**. It sends that server nothing
more, not even a revocation. Remove the computer and add it again if it was
reinstalled. Relay computers are checked by the host key pinned at pairing.

Be clear about what this check is. `/api/health` needs no sign-in and the id isn't a
secret, so anything answering at that address can repeat it. The window trusts a
direct computer because it is **the same origin over HTTPS**; the id only catches an
address that has quietly changed hands. A board stream that drops is not reopened
as a stream: the window polls instead, so every request passes the check again.

## Limits

- **Server settings** stay with the computer this window is served from: Devices,
  phone pairing links, notifications and messaging. With several computers the page
  says so. **Server setup** shows the computer you are working on.
- **The iPhone app** keeps sign-ins in Keychain, so it doesn't offer direct
  computers yet; add them from a browser. Relay computers paired in the app work,
  with their keys in Keychain.
- Task ids in text from another computer stay plain text until you open that
  computer.

- Only the computer you are working on shows its live screen, artifact previews
  and room hand-offs. Open that computer's own address for its files.
- Moving a task between computers, and one server listing another's tasks, are not
  part of this; they come with team features.
- In the desktop app, **This Mac** uses its local service. Add another computer
  with its pairing link as above; **Add a server origin…** in the app menu lets a
  direct connection reach an origin you trust.
