# Remote access

> Pair your computers, run agents in a remote project, answer approvals, and revoke a device's access.

Remote access runs an agent on another computer and shows its conversation on
this one. The host computer uses its own agent installation, sign-in, project
folder, and permission settings. Remote control is an alpha feature.

- App: **Settings → Remote access**
- CLI: `hansard remote`

## Choose the kind of access

| Task                                                 | Feature                                                                                             |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Start and control agents on another computer         | Remote access, described here.                                                                      |
| Back up the archive and receive it on your computers | [Personal Sync](https://www.hansard.dev/sync/personal-sync/).                                       |
| Read the archive from a browser on your network      | [Hosted viewer](https://www.hansard.dev/sync/hosted-viewer/), with a password and read-only access. |
| Share selected conversations with other people       | [Teams](https://www.hansard.dev/sync/teams/).                                                       |

Personal Sync does not authorize remote execution. A hosted viewer does not
give remote visitors agent controls.

## Pair two computers in the app

Direct connections use [Tailscale](https://tailscale.com). Sign both computers
in to the same tailnet, the private network your Tailscale devices share.
Install Hansard and sign in to the agent CLIs on the host computer.

On the host computer:

1. Open **Settings → Remote access**.
2. Turn on **Allow access from other devices**.
3. Under **Shared projects**, select **Share project** to add a folder if needed.
4. Under **Pair a device**, choose the projects the paired device can use.
5. Select **Show code**.

The code works once and expires after ten minutes. **Copy both** copies the
host address and code. The default project choice includes shared projects
and the 200 most recent project folders, leaving out agents' own scratch
folders, projectless chats, and worktrees. Choose a portfolio or **Only shared
projects** to narrow it.

Hansard keeps its background watcher and router running on each computer,
the host computer included: when the watcher stops, the remote host, the app,
or the next `hansard` command there starts it again within about two minutes,
which brings Hansard's router back too. A watcher you stop with **Stop** or
`hansard watcher stop` stays stopped. Windows also starts the watcher again
after it exits, as macOS and Linux do, from the task that starts it when you
sign in.

In a browser, **Show code**, a phone connection link, a device's projects, and
**Remove** first ask for the code that `hansard web` prints in its terminal.
See [Confirm answers and approvals in a browser](https://www.hansard.dev/sync/hosted-viewer/#confirm-answers-and-approvals-in-a-browser).

On the computer you will control it from:

1. Open **Settings → Remote access**.
2. Select **Add device**.
3. On **Pairing code**, enter the **Address** and **Code**.
4. Select **Pair**.

**Your other devices** lists each paired computer with its Hansard version,
what it shares (**All projects**, a portfolio, or a count of projects), and
each agent installed there: ready, signed out with the command that signs it
in there, or unable to reach its model API, with the address it tried. When
an agent there can't reach Hansard's router on that computer because the
router is stopped, **Start Hansard's router on** the device starts it there,
with its watcher if that is stopped too. When the computer runs an older
build of Hansard than this one, **Update Hansard on** the device installs
the newest release there through its own update path (the npm package, or the
signed Mac app) and restarts its background services on it. A Hansard there
from before this option, a source checkout, and the unsigned Windows preview
app need one update made on that computer. Two computers on the same release
can run different builds, so Hansard compares builds, not only version
numbers; a computer that runs a source checkout is told to run `git pull` in
its folder. Select what it shares to search its projects and start a
conversation in one. **Run a quick check** starts a short read-only run there
and reports the answer or the reason it failed. Right after pairing, **Allow**
lets that computer run agents on this one too, without a second code, and
**Let it run agents here** does the same for a computer paired earlier.

Agents on this computer can use paired computers as well. A new session's
context names them, and Hansard's `list_remote_devices`, `start_remote_run`,
and `follow_remote_run` tools show their readiness, start work there, and
follow it, and `stop_remote_run` stops a run they started. An agent that finds
a computer's router stopped, or a computer behind this one, only asks you to
start the router or the update, in Review. Pairing, access, and approvals stay
with you.

The **Agent messages** switch also lets identified agents exchange notes
across the paired connection. See [Agent messaging](https://www.hansard.dev/guides/session-messaging/#message-agents-on-your-other-computers).

## Start and control a remote conversation

1. Open a conversation or start a new one.
2. Select **This device** above the composer and choose the paired computer.
3. Choose its project folder and harness.
4. Enter a prompt and send it.

The conversation shows output, approvals, questions, and **Stop**. The
permission picker uses the host's available modes. A Codex conversation keeps
the permission mode of its first message.

Closing the connection or app leaves accepted work running on the host.
Offline computers stay listed but cannot accept a new conversation.

The project choice limits where work starts and which runs the device can
see. It does not confine the agent's file access. The agent keeps its native
permissions on the host.

## Connect through SSH or a relay

The **SSH** tab in **Add device** uses a Host from `~/.ssh/config`. Hansard and
the agent CLIs must already be installed on that computer. **Start remote
access there** starts hosting when it does not answer.

For networks without a shared tailnet, `hansard remote host relay` configures
a relay you host. Hansard has no public relay configured by default.
Run `hansard help remote` for the host, grant, transport, and relay options.

The [remote host reference](https://www.hansard.dev/reference/remote-host/) covers headless setup,
grant files, relay requirements, request receipts, and storage limits.

## Revoke access

- Select **Remove** under **Allowed devices** to revoke one device.
- Turn off **Allow access from other devices** to disconnect all devices.
- Select **Stop** under **Stop remote work** to stop work they already started.

Disconnecting devices alone leaves their accepted work running. Setting
`HANSARD_REMOTE_CONTROL=0` removes remote access controls and prevents new
remote execution. `hansard remote host stop` remains available.

## Phone access

The [Phone companion](https://www.hansard.dev/sync/phone-companion/) preview provides conversations,
agent controls, and an Inbox through an HTTPS gateway. Open **Settings →
Remote access → Connect a phone** to prepare Tailscale HTTPS access, choose
projects, and create a one-use connection link with a local QR code. Both
devices must connect to the same tailnet. A configured relay remains an
option for computers without Tailscale. **Guided setup** beside **Connect a
phone** walks the phone through Tailscale, HTTPS for the tailnet, the private
address, and the code to scan, and ends with adding the page to the Home
Screen.

**Claude Code approvals on your phone** stays off until you turn it on after
pairing. The [phone setup steps](https://www.hansard.dev/sync/phone-companion/#connect-with-tailscale)
cover HTTPS certificates, the Terminal command, and connection checks.
For read-only archive browsing, use the [Hosted viewer](https://www.hansard.dev/sync/hosted-viewer/).

## Troubleshooting

**A host is offline.** Check that both devices are online in Tailscale and
that **Allow access from other devices** is on at the host.

**An agent needs sign-in.** Sign in to that agent on the host computer, then
retry. A sign-in on the controlling computer does not sign in the host. The
device's row names the command, such as `codex login`.

**A run fails at once.** Select **Run a quick check** on that device. It names
the agent it ran and the text the agent printed, and any sign-in it needs.

**A project is missing.** Add it under **Shared projects** on the host and
check the paired device's project scope.