Skip to main content
Link this machine’s dashboard to another machine over an encrypted channel and manage the links. Released in v0.73.0. Settings → Anywhere → Machines has the same actions. See Linked machines. Every verb talks to the running dashboard with this machine’s internal token, so the dashboard must be up (pan up); without one it prints the not-running message and exits 1. add-ssh and test-ssh also run through the dashboard: the dashboard server runs ssh with its own keys and ~/.ssh/config, not the shell you type the command in. pan connect is the exception: it starts the dashboard itself, on the machine you want to link to.
Links this machine to the one that printed <pairing-url> (pan pair or Pair a device there). By default the link goes both ways at operator level.
Failures name the cause and exit 1: not a pairing link, the other machine unreachable, the pairing link expired or already used, the other machine running an Overdeck without machine links, or a machine answering with a key other than the one the link names.

add-ssh

Links a machine that this machine reaches over SSH. The dashboard runs ssh to <host>, checks that the host has the same pan version, adopts the Overdeck dashboard already running there or starts one with pan up, forwards a loopback port to it, and links over that port. <host> is an SSH config alias (desk), user@host, a host name, an IP, or ssh://user@host:port. See SSH machines.
Overdeck started there means this machine ran pan up on the host, so removing the machine stops that server. was already running there means it adopted a running server, which removal never stops. The command can take up to a few minutes when it starts Overdeck. Failures print the server’s message and exit 1:

test-ssh

Checks that the dashboard reaches <host> over SSH and that the host has the same pan version. It never starts, stops or pairs anything.
A failure prints the same messages as add-ssh and exits 1. --json prints { reachable, panVersion, localVersion, versionMatches, error, message }.

add-fly

Starts a Fly.io VM that runs Overdeck, links it one way from this machine and, optionally, clones a project and starts a Claude Code or Codex conversation on it. The dashboard does the whole flow in one request, which takes a few minutes (longer with a large clone); the command waits for it. See Fly machines for setup, lifetime and cost.
Every failure after the VM exists destroys it again, removes any link it made and prints the server’s message, then exits 1:

list

Shows this machine (first row), every link with its state, load and capability tags, and the machines that hold access here.
LOAD is the machine’s last 15-second load sample: CPU pressure (PSI some avg10, n/a off Linux), free memory and working agents; - before the first sample or for a machine whose Overdeck predates it. TAGS lists its capability tags and reserved for a machine with anywhere.machine.placement: on-request (see Auto placement). The STATE cell carries the last incident (froze when the other dashboard stalled, network otherwise) and, for unsupported, revoked and offline, the detail. The SSH cell shows <destination> (<forward state>, <managed|external>) for an SSH machine and - for any other link. With no links: No linked machines. Link one with `pan machines link <pairing-url>` using a `pan pair` link from the other machine. With no inbound links, the Inbound table is replaced by Inbound: no machine links to this one.

Starting work on another machine: --machine, --machine auto, --needs

Three commands take a machine:
pan start <id> --machine fly starts the issue’s work agent on a new Fly machine, the same as pan start <id> --remote (PAN-4734); see Work agents on Fly. --machine fly refuses on pan worker run and pan lane start: a worker needs its issue workspace, which a new VM never has. A new Fly machine for a conversation is the new-conversation dialog’s Fly (new VM) choice, or pan machines add-fly --project <key> --message <text>. See Linked machines.

Messaging a conversation on another machine: pan tell @<label>/<conv>

pan tell @<machine>/<conv> sends a message to a conversation on a linked machine, through this machine’s dashboard and the encrypted link. <machine> is the link’s label or environment id. It prints Delivered to <conv> on <machine>, or the other machine’s error and exits 1. Only conversations are accepted after @<machine>/. --force and --when-limit-resets are refused for a conversation on another machine with <flag> does not work for a conversation on another machine. Nothing was sent. See pan tell for --message-id and --steer.

who

Lists which machines run agents or conversations for an issue: this machine first, then every online linked machine (2.5 seconds each; a machine that does not answer is named on stderr).
With no matches: No machine runs an agent or conversation for <ISSUE>. The issue id is upper-cased and must look like PAN-7.

add-project

Copies a project between linked machines through the normal project creation: the target clones the repository from its origin, registers it, then receives the chosen git-ignored files (written 0600; an existing file is kept and reported skipped). By default <machine>’s <project-key> is added to this machine; with --to <target>, this machine’s <project-key> is added to <target> (pan machines add-project <this label> <key> --to desk). Files cross only an operator-level link.
Removes the link and tells the other machine to revoke this machine’s access.
When the other machine cannot be reached it prints that it will see the link as revoked when it next connects. An unknown target prints No machine link matches "<target>" and exits 1. --json prints { ok, peerNotified, ssh, fly }. A Fly machine is destroyed unless you pass --keep-server, and its record here is deleted either way. With --keep-server nothing heartbeats the machine any more, so it stops itself within about 5 minutes and loses its disk:
For an SSH machine, unlink also stops its port forward. When this machine started the host’s server (managed), unlink stops that server too, unless you pass --keep-server. A second line says which:

forward

Forwards a TCP port of a linked machine to 127.0.0.1 on this machine and prints the local URL, for previewing a dev server that runs there (PAN-4650).
The other machine connects only to its own 127.0.0.1. It refuses (port-refused) ports below 1024 or above 65535 and Overdeck’s own ports: the dashboard and its API, the supervisor, 80, 443 and Traefik’s dashboard port. A forward needs an operator-level link, and closes on --stop, when the link goes away, or after 30 minutes with no open connection. --list shows the open forwards; --json prints the forward (or the list) as JSON. The dashboard’s Preview button in a remote conversation does the same.

Through the overdeck.ai directory

These verbs need a signed-in machine (pan account login). See Find your machines through overdeck.ai. Each one exits 1 with the dashboard’s error text. On a machine that is not signed in, pan machines directory prints Sign in with pan account login to find your machines through overdeck.ai. and exits 0.

directory

Lists your account’s machines in the directory, then pending approval requests and your own join requests. --json prints the GET /api/directory response unchanged.

join

Asks your other machines (or the one named by --to) to link with this one, then waits up to 10 minutes for one of them to open the request.
Accept only if the approving machine shows the same code. Without a terminal (for example over a script) it prints Confirm with: pan machines accept <requestId> and exits 0; run that command after comparing the codes. --json prints { requestId, sas, fingerprint, approver }. After y it prints Accepted. The link appears in pan machines list when the approver finishes. A rejected or expired request prints The approval was rejected or expired. and exits 1; no answer in 10 minutes prints No machine opened the approval request within 10 minutes. and exits 1.

approve

Opens a direct connection to the requesting machine, prints the code and its fingerprint, asks Approve? [y/N] unless --yes, then approves. Answering no rejects the request and prints Rejected. Without a terminal and without --yes, it prints Pass --yes to approve without a prompt. and exits 1. The link appears in pan machines list once the other machine accepts.

accept and reject

accept confirms this machine’s join request after comparing the codes. reject refuses an incoming approval request or this machine’s own join request.

forget

Removes a machine from the directory and frees its slot on the free account. Links that already exist keep working over their other routes.

versions

Shows the Overdeck version and the version of each installed harness CLI on every machine: this machine first, then each linked machine. A linked machine that is not online shows its last known Overdeck version and no CLI versions.
There is one column per harness CLI found on any machine. While an update job has changed a version, the cell shows before → after. The UPDATE cell shows the machine’s update job: waiting (N turns) while it waits for running turns to end (after 30 minutes, waiting (N turns, M min: use --now)), then updating, restarting, done, failed: <component> or cancelled. After the table, each machine that needs another Overdeck version gets one line with the exact install command. Exit codes: 0 when the table printed; 1 when the dashboard is not running or refused the request.

update

Starts Update all: each online machine updates the harness CLIs installed there that it knows how to update (Claude Code, Codex CLI, Kimi Code CLI, OpenCode, Grok Build, and Pi when it was installed with npm). A CLI installed with npm is updated with npm install -g into its own npm prefix; otherwise the CLI’s own update command runs. A CLI installed with Homebrew, or one with no update command, is left alone. Then it updates Overdeck itself on an npm install -g install or a machine set up with pan connect (into its ~/.overdeck/runtime), and restarts its dashboard. By default each machine waits until no turn is running there. A development checkout or the desktop app keeps its Overdeck and still updates the CLIs. Offline, connecting, unsupported and revoked machines are skipped with the reason, and so is a machine whose link is agent-fenced: Update all needs an operator-level link.
Exit codes: 0 when the request went out, even if some machines were skipped; 1 when the dashboard is not running, refused the request, or a --machine label is unknown.

connect

Turns the machine you run it on (typically a fresh server you reached over SSH) into a lasting linked machine. It installs the Overdeck server as a service that survives logout and reboot, starts it, and prints one link. You paste that link into pan machines link on the machine that should reach this one. Run it from your normal login shell: it saves that shell’s PATH for the service, so agents started later find node and the harness CLIs. Linux and macOS only; on Windows it exits 1 and asks you to run it inside WSL.
Running npx @overdeck/core connect as a systemd service on a fresh VPS has not yet been tested end to end on a real VPS (#4863).
What it does, in order:
  1. Installs a durable copy under npx. npx runs from a cache that npm may delete at any time, so npx @overdeck/core connect first installs the same version into ~/.overdeck/runtime (npm install --prefix, no sudo) and runs itself again from there. Every path the service uses points into that copy. A machine that already has that version skips the install.
  2. Starts the dashboard. A dashboard already running from this install is left alone. Otherwise it starts one and waits up to two minutes for it. If a dashboard from another checkout held the port, it is replaced and the output says so.
  3. Installs the service. On Linux, the systemd user unit overdeck-supervisor.service: installed, enabled at boot, and started. On macOS, the launch agent ai.overdeck.supervisor. The service runs the supervisor, whose watchdog starts the dashboard again whenever it is down.
  4. Turns lingering on (Linux). See below.
  5. Prints the link. The link is printed last because it expires 10 minutes after it is created.
The last line appears only after an npx run. The link works once and is held in the dashboard’s memory, so a restart of this machine before you use it drops it; run pan connect again for a fresh one. Running pan connect again on a connected machine is safe: it installs nothing twice, leaves the running dashboard alone, and prints a new link.

Lingering (Linux)

Without lingering, systemd stops every user service when you log out and starts them again only when you log in, so the server would not come back after a reboot. pan connect turns lingering on with loginctl enable-linger. When that needs a password, it prints the command to run in another terminal:
It waits (checking every 2 seconds) until lingering is on, then carries on. Press Enter to continue without it. Without a terminal, or with --json, it does not wait. Continuing without lingering is not an error, and the output says what it means:

macOS

The launch agent ~/Library/LaunchAgents/ai.overdeck.supervisor.plist starts when you log in. macOS has no lingering for user agents, so a Mac that must come back after a reboot with nobody logged in needs automatic login (System Settings → Users & Groups). macOS 15+‘s Local Network privacy blocks that launch agent’s connections to other machines on this network until you allow them. pan connect prints the exact note:
Turn on node at the printed path in System Settings → Privacy & Security → Local Network; the entry only appears there after the server’s first attempt to reach another machine, so it will not be listed immediately after pan connect. Homebrew’s node is ad-hoc signed, so macOS can treat an upgraded binary as a new app: check the grant again after brew upgrade node. When node is not in the list at all, link over Tailscale instead (pan tailscale setup).

No systemd

In a container, without XDG_RUNTIME_DIR (for example after su instead of logging in over SSH as that user), or wherever systemctl --user does not work, pan connect runs the supervisor as a plain process and says why:
The same fallback applies when OVERDECK_HOME is not ~/.overdeck, unless you set OVERDECK_SUPERVISOR_UNIT=1. The first match wins:
  1. --url, exactly as given.
  2. This machine’s Tailscale address (100.64.0.0/10).
  3. The address you reached this machine at over SSH (from SSH_CONNECTION), unless it is a loopback address.
  4. Another address on a real network interface (container bridges are skipped), public addresses before private ones.
  5. localhost, with the pan pair warning that the link only works on this machine.
Unless the address is a Tailscale address, the output names the host and port the other machine must reach. If a firewall blocks that port, open it or set up Tailscale with pan tailscale setup, then run pan connect again.

After a reboot

On a Linux machine with lingering on, systemd starts the supervisor at boot. The watchdog waits out its 5-minute boot grace and then starts the dashboard, so the dashboard answers within about 6 minutes. A linked machine retries a failed connection with a back-off of at most about 45 seconds, so it shows this machine online again within about a minute after the dashboard answers. If Traefik is enabled here, the output adds that Traefik and CLIProxy wait for pan up after a reboot.

Updating and removing

Update a machine connected with npx from any linked machine with Update all (or pan machines update): it installs the newest version into ~/.overdeck/runtime with npm install --prefix (no sudo) and restarts the dashboard from it. On the machine itself, ~/.overdeck/runtime/node_modules/.bin/pan update does the same install. Running the newest version of pan connect also works, and also rewrites the service:
It installs that version into ~/.overdeck/runtime and rewrites the service. To remove the service:
pan connect installs only the Overdeck server. Agents on that machine still need the harness CLIs and Herdr: run ~/.overdeck/runtime/node_modules/.bin/pan install there.

Troubleshooting

The watchdog stops restarting the dashboard after three restarts within five minutes that do not bring it back healthy, and it remembers that across supervisor restarts (and so across reboots). If the dashboard is still down after a reboot, start it by hand:
Do not use pan up for this on a server: it expects the full host setup from pan install (terminal backend and sidecars), which a fresh server may not have. Still stuck? Ask in the Overdeck Discord or open a GitHub issue.