Flagship features · Remote Orch term Tailscale

Remote Orch term

Pair the Orch term on your home PC with the one on your work PC over Tailscale, so the claude or codex on one PC can exchange messages and files (screenshots, logs, large files) with the agents on the other. Windows and macOS can be mixed freely.

Messages and files are the basics; devices with "Allow terminal" on also get a remote space. Besides agent messages and files, turning on "Allow terminal" per device on the receiving PC lets the home PC view that PC's terminal tabs and its files, Git, search, to-dos and notes (section below). The feature is off on Linux (the settings section is hidden).

What it does

There is a receiving PC (host) and a sending PC (client). Every Orch term can be both, and each direction is paired separately.
"Accept remote connections on this PC" is off by default. You have to turn it on, PC by PC, before any door opens.
When on, it accepts connections only on the Tailscale address (port 9620). It never opens to the office network, the LAN, or the internet, and it won't turn on if it can't find Tailscale.
Agents on paired PCs use chat_who · chat_send · chat_inbox (messages) and chat_send_file (files) — the same tools as agent chat.

Prep 1 — Install Tailscale

Install and sign in on both PCs

Install from tailscale.com/download on both PCs and sign in to the same tailnet. Each PC gets a Tailscale name such as work-win or home-mac. You'll use that name (or its 100.x.y.z address) when pairing.

Prep 2 — Turn on Tailnet Lock (recommended)

When a PC joins a tailnet, Tailscale's servers help. If those servers or your Tailscale account were compromised, an attacker could slip a fake PC into your tailnet. With Tailnet Lock on, a new PC can join only if a PC you already trust signs it, so even a compromised Tailscale server or account can't add a fake PC.

Orch term adds its own authentication on top of Tailscale (only paired device keys get through), so a missing Tailnet Lock is not an instant breach. But the point is layers of defense, so if you're turning on receiving for a work PC, we recommend turning Tailnet Lock on too. Follow Tailscale's Tailnet Lock docs to enable it.

Prep 3 — Narrow the scope with an ACL

Tailscale's access rules (ACLs) can limit your home PC to just the one Orch term port on the work PC. You put tags (tag:home, tag:work) on the PCs and write rules between tags. A tag is a label you attach to a PC in the admin console; the names are up to you.

{
  "tagOwners": { "tag:home": ["autogroup:admin"], "tag:work": ["autogroup:admin"] },
  "acls": [
    { "action": "accept", "src": ["tag:home"], "dst": ["tag:work:9620"] }
  ]
}

The example lets tag:home PCs reach only port 9620 on tag:work PCs. The key line is {"src":["tag:home"],"dst":["tag:work:9620"]}. The port is 9620 in release builds (dev builds add an instance number to 9620). For use in both directions, add one more rule the other way. The rule above is one line added to your existing acls array; replacing the default allow rules wholesale cuts other traffic in your tailnet. Also, tagging a device makes it owned by the tag rather than by a user, so it may need to re-authenticate.

Pairing

Pairing works only when a person sitting at the receiving PC approves it. There is no way to pair a new device remotely.

Receiving PC: turn on receiving and open the pairing window

Settings → Remote access → turn on "Accept remote connections on this PC" (the Tailscale address is shown). Press "Pair new device" and confirm with Touch ID / Windows Hello; a window opens that accepts one request, for 2 minutes.
Sending PC: add a remote PC

Settings → Remote access → "Add remote PC": enter the receiving PC's Tailscale name (or address) and a recognizable display name (e.g. Work-Win), then send the request.
Compare the 6 digits and approve

Both PCs show the same 6-digit number. Press "Approve" on the receiving PC only if the two numbers match. If they differ, don't — someone may be sitting in the middle. After approval each PC appears in the other's "Registered devices" list.

You can delete a registered device from the receiving PC's settings at any time; deleting it also cuts that device's current connection immediately.

Messages — consent is asked on the sending side

When the sending PC's agent calls chat_who, the tabs on the paired PC appear like Work-Win / claude — tab name.
The first time you send, the sending PC (where the person is) asks for permission. The receiving PC shows no permission prompt — it only records and notifies. Permission is per (my tab, their tab) pair, survives an app restart, and disappears when either tab is closed or the device is deleted.
Conversations start only from the sending PC. An agent on the receiving PC can only reply inside permitted conversations; it can't start one. That way, even a tricked agent on the receiving PC can't order around an agent on the sending PC. If the sending side denies a permission, the denial is final until that tab is closed and reopened.
The receiving tab gets one typed line carrying the source PC name, like from: Work-Win / claude. The 500-character limit and control-character stripping are the same as local chat.
If the other PC is offline, a message from the sending PC to the receiving PC isn't queued — you get an error right away (peer_offline). The receiving PC's replies are kept (up to 500 per device, 7 days) and delivered once each when the sending PC reconnects.
Messages are limited to 20 per minute per device pair (adjustable in settings).

Files

An agent sends one file with chat_send_file, only to a paired PC (no whole-folder sends, no outside destinations). The receiving agent gets one line with the name, size, and sha256.
Received files are stored only in the inbox folder: remote-inbox/<device name>/<date>/ under the data folder. They are never opened or run automatically, and the agent is told only the path. macOS adds its "downloaded from the internet" warning; Windows adds the "this file came from another computer" mark.
Files go in chunks, resume after a drop, and are verified with sha256 at the end. If the receiving PC has too little free disk space, it refuses before starting.
A file over 100 MiB needs a confirmation on the PC where a person is. The per-file limit is 2 GiB by default (you can lower it in settings).
Sensitive files are blocked by default: ~/.ssh, cloud and tool credentials (~/.aws, ~/.kube, …), agent settings and tokens (~/.claude, ~/.codex, …), browser profiles, the Orch term data folder, and secret files like .env, *.pem, id_*. Symlinks are followed to the real path before checking, so you can't smuggle a file through a link.

Viewing the host PC's files, Git, search, to-dos and notes from a remote space

When you turn on Settings → Remote access → "Allow terminal" for a device on the receiving PC (e.g. the work PC; identity check required), the client PC (home PC) gets that PC's remote space in its title bar. While you are viewing a remote space, it is not only the terminal — the sidebar and file viewing point at the host PC too. There is nothing extra to turn on: "Allow terminal" also covers viewing and editing files, Git changes, search, to-dos and notes.

The sidebar switches by itself. Opening a remote space makes Explorer, Git, Search and To-dos show that host PC space's project folder, with a label like "Work-Win · space name" always visible above the sidebar. Going back to a local space restores this PC's state (expanded folders etc.) exactly. The Sessions list is not switched (it stays this PC). If a space has several projects, the default follows the host PC's active project, and you can pick another in the sidebar header (the choice stays on this PC only and does not affect the host PC).
Files open as "this PC only" tabs. Clicking a file in Explorer, the Git changes list or search results adds a dashed, yellow tab to the tab strip of the remote panel you are looking at. You can switch between it and the terminal tabs, and nothing appears on the host PC's screen (the person at the host PC sees no tab). The tab exists only on this PC — it disappears when the app restarts, and it can't be split, moved to another panel or renamed. ⌘W/Ctrl+W closes the visible "this PC only" tab (it never closes a host terminal tab).
Markdown and HTML reports. Markdown opens in the reading view (relative images and links resolve against the same project on the host PC), and the 👁 button switches to edit mode. An HTML report is shown rendered — CSS, scripts and images from the same folder come along. The report runs in an isolated frame, so it can't reach Orch term internals or files outside the project, and outside network requests are blocked (some resources — e.g. images referenced through CSS url() — may appear empty). Code and text open in the usual editor.
You can occasionally edit and save. Saving writes to the file on the host PC, with safeguards.
- If the host PC's editor has unsaved changes in the same file, saving is refused with "The host PC editor has unsaved changes" (there is no overwrite option).
- If the file changed on the host PC after you opened it, you get "Changed on the host PC in the meantime" — choose Reload or Overwrite anyway.
- If it changes on the host PC while you are editing, the tab shows "Changed on the host PC". A file you haven't edited refreshes by itself every 5 seconds.
- Files larger than about 900 KB open read-only. You can't create new files, only save existing ones. When the connection drops, the open content stays visible but becomes read-only, and unlocks when it reconnects.
Git is view-only. You can see the host PC project's changed files (staged and working tree) and per-file diffs; a diff opens as a "this PC only" tab. No commit, stage, push, revert, branch switch or Git graph. Changes outside the project folder (other folders of a larger repository) are not shown.
Search. Search in files (Ctrl+Shift+F) searches the host PC project; clicking a result opens a "this PC only" tab at that line.
To-dos. You see the host PC space's to-do board and can add items and move them between columns (including Done). Changes show on the host PC's board right away, and changes made there (by agents too) appear on this PC's board within seconds. No deleting or editing of to-dos.
Notes. While you view a remote space, the floating Notes window shows the host PC's notes, and the "Work-Win notes / This PC notes" switch at the top of the window toggles between them (default: host PC). Opening a note from the list opens a "this PC only" tab, and you can write new notes and edit memo (text) notes. Drawing, sequence and flowchart notes are view-only. If the host PC is editing that note, saving is refused. Notes can't be deleted.
CPU, memory and GPU. While you view a remote space, the status bar gauges switch to the host PC's values, prefixed with the host PC's name (updated every 2 seconds). Back in a local space they show this PC again. If the host PC runs a version from before this feature, the gauges are hidden.
Pasting images. Paste an image (a screenshot, say) into a remote terminal tab with ⌘V / Ctrl+V and it is sent to the host PC; the input box gets the path where the host PC saved it, which Codex and Claude read as an image. The host PC's clipboard is left alone, and images up to 20 MB can be sent.

Not possible: Git writes (commit, push…), deleting notes or to-dos, editing to-dos, creating / renaming / deleting / drag-moving files and folders, downloading files, and opening editor tabs in the host PC's terminal layout. To hand over a file, use "Files" above (chat_send_file).

Sensitive files stay blocked here too. Credential folders such as .ssh, .aws, .kube, .docker, .gnupg and secret files are left out of listings, search and opening, even if the project is outside the home folder. Symlinks that point outside the project folder are not followed.
Nothing is shown on the host PC's screen. What you view or edit from home is recorded only in the audit log (action kind and project-relative path only — never file contents, search queries, or note and to-do bodies). The to-do, note and file changes themselves do show up in the host PC's board, list and files.
If the host PC runs an older build, you see "Update the host PC to view its files" while the terminal keeps working as before (update both sides). When the connection drops, open content stays read-only.

Identity check — 12 hours and sleep

On the sending PC, you confirm with Touch ID / Windows Hello every time you start a connection. An agent never raises this prompt for you.
The check is valid for 12 hours. It also expires when the PC goes to sleep (confirm again after waking). A screen lock does not expire it — agents keep working while you're away.
On expiry the connection drops and the status bar shows "Verification needed". If an agent calls chat_send then, it just gets an auth_required error. Click the status bar and confirm to reconnect.
While the check is valid, a brief network drop reconnects automatically without a new check.

The receiving PC's lock screen

While a sending PC is connected, the whole Orch term window on the receiving PC is covered by a "Remote in use" lock screen (so people in the office can't watch messages being typed into terminals). The in-app browser is hidden too.

The lock screen shows the connected device's name (e.g. "Home-Mac connected") and a [Disconnect all] button. Disconnecting needs no identity check. After it, the sending PC does not reconnect by itself, and the receiving PC refuses that device for 60 seconds.
To keep using the receiving PC, press [Keep using this PC] and confirm your identity on that PC. The remote connection stays up.
You can't quit the app while locked (⌘Q and closing the window do nothing). Unlock or "Disconnect all" first.
For cases like testing at neighboring desks where people sit at both PCs, you can turn off "Lock screen while connected" per device. That can be done only on the receiving PC, and only after an identity check.

What you can see in settings

Settings → Remote access covers turning receiving on, pairing a new device, the registered-device list (last connected, delete), adding a remote PC, message-rate and file-size limits, disconnect all, and the audit log. The audit log keeps, for 30 days: pairings, connections, disconnects, identity checks, messages (bodies are not stored — length only), files (name, size, hash), and rejected connection attempts. Connections also show in the status bar.

Troubleshooting — when a corporate VPN breaks the connection

Some corporate VPNs (observed: SECUI VPN on Windows) rewrite the Windows route table when they connect and drop the Tailscale routes (100.x). Tailscale still shows "Connected", but the other PC can't be reached.

Symptom: adding or connecting to a remote PC ends in a timeout, and ping <peer's 100.x address> gets no reply.
Check: in PowerShell, run Find-NetRoute -RemoteIPAddress <peer's 100.x address>. If the outgoing interface is Ethernet or Wi-Fi instead of Tailscale, the route is gone. The Tailscale log may also show it re-adding routes several times a second (it's fighting the VPN over the route).
Fix: turn the corporate VPN off, then restart Tailscale with tailscale down → tailscale up. Once the route is back, connecting works right away. Whether both can run at once depends on the VPN's policy, which Orch term can't change.
You don't need to add a Windows Firewall rule. Orch term only opens its port on the Tailscale address, and the cause here is the route, not the firewall.

Risks and limits

If your home PC is taken over, the attacker can do whatever that PC's agents could. Malware can't pass the identity check behind your back, but a PC taken over after you've confirmed looks the same as a normal connection. Its agents could order the work agents around inside permitted conversations and fetch any file the work agents can read (outside the block list). That's why access stays narrow (chat: messages and files) and the permissions, rate limit, lock screen, and audit log above limit the damage.

Turn on two-factor authentication for your Tailscale account, and narrow the scope with Tailnet Lock and ACLs. If you lose a registered device, delete it on the receiving PC right away.
"Allow terminal" grants a full shell with that PC user's permissions, plus viewing and editing project files. Turn it on only for devices you trust. It turns off screen lock while that device is connected, and you can turn it off on the receiving PC at any time (open remote channels close immediately).
The safest choice for a PC with sensitive material is to leave this feature off. Receiving is off by default.
Check your company policy before turning it on for a work PC. Security policy may forbid accepting connections from an outside PC on a corporate machine, or require prior approval. Using it without permission is your responsibility.
If the other PC's Orch term has a different remote protocol version, the connection is refused with "update the other PC".