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.
link
<pairing-url> (pan pair or Pair a
device there). By default the link goes both ways at operator level.
add-ssh
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
<host> over SSH and that the host has the same pan
version. It never starts, stops or pairs anything.
add-ssh and exits 1. --json prints
{ reachable, panVersion, localVersion, versionMatches, error, message }.
add-fly
list
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
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
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.
unlink
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:
managed), unlink stops that server too, unless you pass --keep-server.
A second line says which:
forward
127.0.0.1 on this machine and prints the
local URL, for previewing a dev server that runs there (PAN-4650).
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
--json prints the GET /api/directory response unchanged.
join
--to) to link with this one, then waits up to
10 minutes for one of them to open the request.
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
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
versions
online shows its last known Overdeck version and no CLI versions.
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
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
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:
- Installs a durable copy under npx.
npxruns from a cache that npm may delete at any time, sonpx @overdeck/core connectfirst installs the same version into~/.overdeck/runtime(npm install --prefix, nosudo) 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. - 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.
- Installs the service. On Linux, the systemd user unit
overdeck-supervisor.service: installed, enabled at boot, and started. On macOS, the launch agentai.overdeck.supervisor. The service runs the supervisor, whose watchdog starts the dashboard again whenever it is down. - Turns lingering on (Linux). See below.
- Prints the link. The link is printed last because it expires 10 minutes after it is created.
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:
--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:
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, withoutXDG_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:
OVERDECK_HOME is not ~/.overdeck, unless you set
OVERDECK_SUPERVISOR_UNIT=1.
Which address the link uses
The first match wins:--url, exactly as given.- This machine’s Tailscale address (
100.64.0.0/10). - The address you reached this machine at over SSH (from
SSH_CONNECTION), unless it is a loopback address. - Another address on a real network interface (container bridges are skipped), public addresses before private ones.
localhost, with thepan pairwarning that the link only works on this machine.
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 forpan up after a reboot.
Updating and removing
Update a machine connected with npx from any linked machine with Update all (orpan 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:
~/.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: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.