Share one daemon across your computers
Networked Seamless step by step - set up the Server with seamlessd setup, connect each Client, pair computers on the Devices page, sign in and approve from any browser, and every step by hand.
On this page
- The topology
- Set up the Server
- A new computer
- A computer already running Seamless
- Check the Server
- Connect each Client
- The relay's root step
- Who a relay serves without peer_auth
- Windows is always a key client
- Check a Client
- Pair computers on the Devices page
- Revoke a computer
- A renewal means re-pairing each relay
- Sign in to the console from another computer
- Approve from another computer
- Locked projects and agents on other computers
- When the Server is out of reach
- What a remote device does not get
- How doctor reports it
- Updates on a shared daemon
- Windows: a second user on one box
- By hand: widen the Server
- By hand: TLS
- mkcert (the friction-free path)
- openssl (no extra tool)
- Why https changes the Claude Code wiring
- By hand: connect a Client with the Server's key
- By hand: install a relay
- Related
The default install is Standalone: one daemon per computer, bound to loopback. This guide is the other shape, Networked: one computer, the Server, runs the daemon and keeps the data, and every other computer is a Client of it, so a laptop, a desktop and a build box share a single corpus instead of three that drift apart. Networked Seamless explains the model - the relay, pairing, and what stops when the Server is out of reach. This page is the steps.
It is an opt-in with real tradeoffs. The bearer key is you, and so is a computer paired with the Server: either reaches every project but the locked ones, except that under peer_auth a relay reaches only what the account it names may. So the supported boundary is computers you trust on a network you trust - see the security posture. Some daemon-side captures stop working for agents on another computer, deliberately and visibly; what a remote device does not get is the honest list, and it is worth reading before you start.
Set up the Server first: every Client needs its address.
The topology
| Server | Client | |
|---|---|---|
role |
server (the default) |
client |
| Daemon | seamlessd serve |
none - serve refuses outright |
| Service (launchd / systemd / Scheduled Task) | installed | none (a relay, if you install one, runs as a service of its own) |
| Data dir, database, corpus | here | none; seam status does not even print a data dir |
| Config keys that matter | addr, server_url, allowed_hosts, tls.cert_file, tls.key_file, mcp.api_key |
role, server_url; a key device adds its own mcp.api_key, and tls.ca_file for a certificate it compared |
| Console, gardener, embeddings | here | the Server's |
A Client's config is deliberately tiny. role: client requires server_url - a
client that dials nowhere is a contradiction, and loading one is an error - and
tls.cert_file on a client is refused too: a client holds no server
certificate, it trusts one with tls.ca_file. Through a relay, server_url
names the relay's socket, unix:///opt/seamless/run/seamlessd.sock, and the
config holds no key at all.
Set up the Server
A new computer
On the computer that will keep the data, run the installer in a terminal:
curl -fsSL https://thereisnospoon.org/install | sh
Once it has downloaded and verified the release, and before it installs
anything, it asks seamlessd setup
how this computer will be used:
How will you use Seamless?
[1] Standalone everything on this computer: the daemon, the data, and the agents that use them
[2] Networked one computer keeps the data, and the others connect to it
Enter 1 or 2 [1]: 2
Set up the Server first: each Client needs its address and a pairing code.
[1] Server this computer keeps the data, and the other computers connect to it
[2] Client this computer connects to the Server and keeps no data of its own
Enter 1 or 2: 1
Then it decides where the other computers reach this one:
Where will the other computers reach this one?
[1] Tailscale <server name>: this computer's name on your tailnet, with a certificate from the tailnet
[2] Domain a name of yours, with its certificate and key
[3] LAN a name on your local network: setup shows how to make its certificate
Enter 1-3 [1]:
- Tailscale is offered, and is the default, when Tailscale runs here and the
tailnet issues certificates for this computer's MagicDNS name. Setup gets the
certificate with
tailscale cert, into~/.config/seamless/tls. Otherwise a line says why Tailscale is not offered, and the choices are the other two. - Domain is a name of yours with a certificate and key you already have:
setup asks for the name, then the
Certificate fileand theKey file. - LAN is a name on your local network; setup offers this computer's own,
with
.localadded when it has no domain. It prints anmkcertand anopensslcommand that make the name's certificate in~/.config/seamless/tls, to run in another terminal, and then asks for the files. The other computers trust mkcert'srootCA.pem, or the openssl certificate itself (how).
Setup takes a name only when it resolves on this computer, A and AAAA, to
addresses this computer holds and none of them loopback. It takes a certificate
only when it loads as a pair with its key, names the host and is valid now, and
the key is readable by your account alone (chmod 600). It then binds the
narrowest address that holds every address of the name - one IPv4 address of
it, with the IPv6 addresses serve listens on beside it (a tailnet name's two),
else the wildcard - and says each choice in one line:
| Row | What it says |
|---|---|
address |
the server_url the other computers dial |
certificate |
the file, until when it is valid, and how to renew it |
bind |
the addr, and why it holds every address of the name |
passkeys |
the passkey origin, derived from server_url |
allowed |
no other name: the daemon refuses (421) a request that names another host |
key |
who can read the TLS key, and what that means for the console's origin |
Next, Start fresh, or from a backup? Enter starts fresh. A backup - a
seamlessd export archive or one from Settings > Backups - is restored into the
empty data directory before anything is installed
(details). Only then does
setup write ~/.config/seamless/seamless.yaml: addr, server_url,
allowed_hosts and tls, with the bearer key. The installer installs the
binaries, wires this computer's agents for https, starts the service and waits
for it to answer.
The install ends with what each Client needs, as seamlessd devices code
prints it:
To connect another computer to this server:
Address: https://<server name>:8081
Certificate fingerprint: <SHA-256 of the certificate>
(the other computer shows it before it pairs: they must match)
Pairing code: get one on the console's Devices page, or run `seamlessd devices code` here
The code is the approval: whoever enters it first pairs as you.
It is followed by the one-liners for macOS and Linux and for Windows, which
carry the certificate's fingerprint, by a reminder that each code works once,
and by locked projects as a step setup does not do yet, with the
guide that does it by hand.
Run a one-liner on each Client, with a code of its own
(below). On a Server widened by hand without
server_url, the address is this computer's loopback, and the closing says
another computer cannot use the one-liners (below).
A script answers the same questions in the environment: SEAMLESS_SETUP=server
with SEAMLESS_SERVER_NAME, plus SEAMLESS_TLS_CERT and SEAMLESS_TLS_KEY
unless the name is this computer's Tailscale name, whose certificate setup gets
from the tailnet:
curl -fsSL https://thereisnospoon.org/install | SEAMLESS_SETUP=server SEAMLESS_SERVER_NAME=<this computer's tailnet name> sh
Every knob is in the CLI reference.
A computer already running Seamless
Run seamlessd setup on it. It says how the computer is set up and offers the
changes it can make:
This computer is set up as Standalone.
[1] Keep it as it is
[2] Make it the Server, so other computers connect to it
[3] Turn on locked projects (peer_auth)
Enter 1-3 [1]:
Choose Make it the Server. Setup asks the same address questions, but it
never edits a config that exists: it prints the lines to put in
~/.config/seamless/seamless.yaml, replacing any it has, and the installer
command to run again, which restarts the daemon and wires the hooks for https.
With locked projects on, the daemon's config and TLS pair are its own
account's, so setup prints the root steps that put them in place instead
(the Server's address).
Setup does not change the address of a computer that is the Server already:
that is by hand.
Check the Server
seamlessd doctor
Its transport rows are the ones to read:
| Row | What it tells you |
|---|---|
bind |
Loopback is OK. Non-loopback without TLS is a warn naming what travels in the clear; non-loopback with TLS is OK with the reminder that the bearer key is still the only authentication. |
bind.addresses |
Dials the bind and the IPv6 addresses serve listens on beside it. Another process answering at one is a fail: it would answer for the daemon there, and serve refuses to start while it holds one a name points at. |
server_url |
Fetches /healthz through the advertised URL. A 421 here is a fail that names the Host header it just refused - the allowlist and the advertised name disagree. |
tls |
Off, or the certificate's expiry and whether its SANs cover the advertised host. |
tls.key_file |
Who can read the TLS key: your account alone is info, group or world a warn. |
server_url.addresses |
Every address the server_url host resolves to, against what the daemon listens on. One the daemon does not hold is a warn. |
tailscale |
info when the tailnet issues certificates for the host: then the bind holding every address of the name, not the TLS key, keeps another page off the console's origin. |
device pairing |
How a computer pairs here, and how many are paired or waiting. No TLS is a warn: a relay cannot pair, and a pairing over plain http from another computer is refused; with a plain http server_url to another host no computer can pair, and no code is minted. An address of this computer's loopback (server_url unset on a wildcard bind derives http://127.0.0.1:8081) is a warn too: the one-liners carry it, so another computer cannot use them. A server_url that names a user is a warn: no code is minted and no one-liner printed until it is taken out. |
peer_auth devices |
Under peer_auth only: a warn for each key device paired with a one-time code alone, before peer_auth, which is still you over TCP though no passkey approved it: revoke it and pair it again, so a passkey approves it. |
relay owners |
Without peer_auth only: an info listing each relay with the uid its pairing recorded as yours, the one uid served through it, and a warn for each relay whose pairing recorded none (paired before, or by a relay of an earlier release), every caller of which is you: re-pair it to bind the owner's uid (why). |
peer_auth relays |
Under peer_auth only: each relay peer_auth.relays maps, and whether it is paired and approved with a passkey. A warn when the uid its pairing recorded is not the mapping's owner_uid: the mapping judges, but one of the two is wrong. |
relay renewal |
From 14 days before the TLS certificate's expiry, and past it, a warn naming every relay paired here: each pins this exact certificate, so after the renewal each must pair again, and the row prints the command (why). Nothing while no relay is paired. |
Every row is in the doctor reference.
Connect each Client
On the Server, get a pairing code: Get a pairing code on the console's
Devices page, or seamlessd devices code in the Server's terminal.
Either shows the code once, valid for 10 minutes and for one computer, with a
one-liner for each kind of Client that carries the Server certificate's
fingerprint. The code works once, so the line the Client's shell keeps in its
history is dead after use. On the Client, run its one-liner:
macOSLinux
curl -fsSL https://thereisnospoon.org/install | SEAMLESS_SETUP=client SEAMLESS_SERVER_URL=https://<server name>:8081 SEAMLESS_SERVER_FINGERPRINT=<fingerprint> SEAMLESS_PAIR_CODE=<code> sh
Windows
$env:SEAMLESS_SETUP='client'; $env:SEAMLESS_SERVER_URL='https://<server name>:8081'; $env:SEAMLESS_SERVER_FINGERPRINT='<fingerprint>'; $env:SEAMLESS_PAIR_CODE='<code>'; irm https://thereisnospoon.org/install.ps1 | iex
Setup then pairs the computer before anything is installed, and finishes once the install is done:
- It shows the Server's certificate. It reads the certificate in a
handshake that sends nothing, and shows its SHA-256 fingerprint: compare it
with the
Certificate fingerprintthe Server printed: the one-liner'sSEAMLESS_SERVER_FINGERPRINThas setup compare it (at a terminal without it, setup asks you); on a mismatch nothing is sent. A certificate this computer's own roots do not trust - one made with mkcert or openssl - is trusted only once it was compared, and then as that certificate alone, kept in~/.config/seamless/server-ca.crt. Without the knob, such a run stops and names it. A plainhttp://address is refused unless it is this computer's own loopback: the code, and a key of this computer's, would cross the network in the clear, and the Server refuses such a pairing too. - It pairs as a relay or a key device. On macOS and Linux it pairs a
relay, unless
SEAMLESS_PAIR_AS=keymakes it a key device, for a computer where you have no root (a container, CI). Windows always pairs a key device. - A key device pairs at once. Its key, the pairing's answer, goes into a
new
~/.config/seamless/seamless.yaml(0600) withrole: client, the Server's address and, for a certificate it had to compare,tls.ca_file. The key is never printed. Setup pairs one only where no config exists yet: move an existing one aside first. Under peer_auth it waits for your approval on the Devices page. - A relay gets its config now and its root step at the end. Setup writes a
config of
role: clientandserver_url: unix:///opt/seamless/run/seamlessd.sock, with no key, and the installer wires your agents to that socket. Once the install is done, setup prints the relay's one root step (below), with a row of its own for the pairing code. It never runs a command as root. - It checks. For a key device,
seam doctor, then a session calledseamless-setup-check, whose host the Server reports back: the name the Server records this computer's work under. For a relay that does not serve yet, it says to runseam doctoronce it does.
A relay Client pairs again the same way, with a new code; a key device first needs its config moved aside, since setup never edits one. A computer that runs a daemon of its own (Standalone, or the Server) is refused: its data would have to move first. Every knob is in the CLI reference.
At the terminal, with no variable set, the installer asks instead. Choose Networked, then Client:
The Server's address: its setup printed it, and so does seamlessd devices code there.
Server address (https://host:8081): https://<server name>:8081
fingerprint <SHA-256 of the certificate>
the Server's certificate, SHA-256: its setup printed it (Certificate fingerprint), and so does seamlessd devices code there
Does it match what the Server printed? [y/N]: y
How will this computer reach the Server?
[1] Relay a small service of its own account: your agents need no key, and locked projects can open to them (one root step)
[2] Key a key of this computer's own, for a computer where you have no root (a container, CI); it never opens a locked project
Enter 1 or 2 [1]:
Enter at the fingerprint question is no, and no sends nothing. Windows skips the last question. Setup then asks for the pairing code: a key device at once, a relay just before its root step.
With the Server's own key, SEAMLESS_SERVER_URL with SEAMLESS_MCP_API_KEY
installs a key client of the Server's shared key, as before: it pairs nothing,
and the Devices page does not list it (by hand).
The relay's root step
The relay names each of your agents to the Server by the uid this computer's
kernel reports, so it runs as an account of its own, where no process of yours
can change what it says, and making that account takes root once. Setup prints
the commands with this computer's values, to read and then run as an
administrator, in four blocks. Each block is one list of commands whose lines
end in &&: paste a block whole, and it stops at its first failure. Every
command names its tools by their full paths (/usr/bin/sudo, /usr/bin/tee),
so none is found on your PATH, and every value is quoted for the shell:
-
Its account and a group. A system account,
_seamless(on macOS made withdscl, on Linux withuseradd --system), and a group,_seamlessowner, holding you and it alone: the socket's. -
The layout, root's copy of
seamlessd, and the pin. Root's/opt/seamless,/opt/seamless/binand/opt/seamless/etc; the relay's/opt/seamless/run, its home, and/opt/seamless/relay(0700) for its key. Your shell reads theseamlessdthe installer just put in your~/.local/bin, and root only writes what it reads, to/opt/seamless/bin/.seamlessd.new: root opens no file of yours, so a symlink there to a file only root may read fails before root runs.shasum -a 256 -c(Linux:sha256sum -c) checks that copy is the binary setup ran as, and only then is it made root's and moved to/opt/seamless/bin/seamlessd. A certificate you compared is printed in the step itself, and root writes/opt/seamless/etc/server-ca.crtfrom there. Then the account is pinned in/opt/seamless/etc/daemon-account, as Deploy it pins the daemon's. -
The pairing, as its account:
/usr/bin/sudo -u _seamless -H /opt/seamless/bin/seamlessd relay pair --server https://<server name>:8081 --fingerprint <fingerprint> --owner-uid 501 --code -with
--ca-file /opt/seamless/etc/server-ca.crtfor a certificate you compared. It waits for you to paste the code. Setup never puts it in a command line, where other accounts and your shell history would keep it, and shows it again only when you typed it at its question: a code you set inSEAMLESS_PAIR_CODEis yours already. The key it makes stays in/opt/seamless/relay.--owner-uidis your uid on this computer, which setup fills in: the Server records it with the pairing, and without peer_auth serves that uid alone through this relay (below). Under peer_auth it waits again, until you approve it on the Devices page. -
Its service: on macOS the LaunchDaemon
com.arctop.seamless.relay, on Linux the system unitseamless-relay.service, each running/opt/seamless/bin/seamlessd relay serve --socket-mode 0660 --socket-group _seamlessowneras_seamless. Only you, and the relay, reach its socket.
After an update. Updating this computer replaces your own seamlessd
(~/.local/bin) alone; the relay keeps running root's copy. Run
seamlessd setup again and paste block 2 alone: it copies the new
seamlessd, checks it, and moves it into place. Then restart the relay, which
runs the binary it started with until then
(its service says how). Blocks 1, 3 and 4 have
nothing to do: the account exists, the relay is paired (block 3 would refuse),
and the service is loaded. Until then seamlessd doctor warns
(relay.binary).
After the blocks, setup prints what the Server needs: under peer_auth it judges
each caller this relay names once you map it, and refuses it until then. Add
the line it prints to the daemon's config, /opt/seamless/etc/seamless.yaml,
and restart the daemon (what it does):
peer_auth:
relays:
<this computer's name>:
owner_uid: 501 # your uid on this computer
On a Server with peer_auth, an account on this computer that runs restricted
agents joins _seamlessowner too and gets a line of its own there,
restricted: {<its name>: <its uid here>}. Without peer_auth that does not
apply: the Server serves your uid alone through the relay.
On Linux, log out and back in once: your agents join _seamlessowner at your
next login. Approvals then happen in the Server's console, with a passkey, from
any browser (below).
Who a relay serves without peer_auth
A Server without peer_auth has no account to serve anyone but you as. So a
relay's pairing records your uid on its computer (seamlessd relay pair --owner-uid), and the Server serves that uid alone through it. A request the
relay forwards for another uid is refused (403), in words that name the remedy:
forbidden: uid 502 on relay example-laptop is not the owner's uid there (501, recorded when the relay paired). This server runs without peer_auth, so through a relay it serves the owner's account alone: to give that account access of its own, turn peer_auth on and map it as restricted (peer_auth.relays: {example-laptop: {owner_uid: 501, restricted: {<its name>: 502}}}), then restart the server
A request that forwards no caller at all is refused too (400): a relay of this
release forwards its caller with every request. The Server's /healthz is
not judged, since the relay probes it for itself.
seamlessd relay pair takes the uid from --owner-uid, which always wins, and
without it from SUDO_UID, the account that ran sudo -u _seamless. With
neither it refuses, and it refuses uid 0: root is never the owner. The setup
root step's line always carries --owner-uid.
A relay paired before the Server recorded the owner's uid, or by a relay of an
earlier release, has none recorded. It keeps working exactly as before, every
caller it forwards being you, and the Server's seamlessd doctor (relay owners, a warn) and Devices page say to re-pair it to bind the owner's
uid: revoke it, then pair it again with a relay of this release
(below). A relay of this release pairing with a Server of
an earlier release is refused before the code is used, and says to upgrade the
Server first: that release does not record the uid.
Under peer_auth nothing of this applies: peer_auth.relays.<relay>.owner_uid
judges, and the Server's seamlessd doctor warns when the uid the pairing
recorded is another one.
Windows is always a key client
Setup offers a Windows computer Standalone and Client only:
How will you use Seamless?
[1] Standalone everything on this computer: the daemon, the data, and the agents that use them
[2] Networked connect to a Server on another computer, as its Client
Windows has no peer_auth and no relay, so a Windows computer can be a Client but not the Server.
Enter 1 or 2 [1]:
A Windows Client is a key device, always: SEAMLESS_PAIR_AS=relay is refused
there, and seamlessd relay refuses to run. Its pairing gives it a key of its
own, which the Server's Devices page lists and revokes, and setup says what
that means: a key device never opens a locked project, since the Server cannot
tell its agents apart, so they never hold a lease. Run agents that need a
locked project on the Server's computer, or on a macOS or Linux computer behind
a relay the Server maps (below).
The same holds for a macOS or Linux computer paired as a key device.
Check a Client
On the Client, any time:
seam doctor # the server answers, and tools/list works
seamlessd doctor # the client report: role, server_url, key, hooks, MCP
A client's seamlessd doctor is a deliberately short list: role and
server_url reachability, the API key, the MCP tool count, and the same
desired-state hook and MCP comparisons the server runs. The database, schema,
repo map, feature skills, gardener, LLM, and embedder checks are all absent,
because every one of them describes a machine that is somewhere else. The
server_url probe is a fail on a client rather than the server's info
line: until the server answers there are no briefings, no memories, and no
tools on this machine.
On a relay's Client the socket is the relay's: one that does not answer names
its service (com.arctop.seamless.relay on macOS, seamless-relay.service on
Linux) and how to start it, or, with none installed yet,
its root step.
On a computer with a relay, it adds the relay's rows: the account the relay
runs as, its layout, whether root's copy of seamlessd is the one you run
(relay.binary, a warn after an update until you update it), its pairing
and the uid it recorded as yours (relay.owner, a warn for a pairing an
earlier release made, which recorded none), the pinned certificate's expiry
(relay.certificate, a warn from 14 days before it: a renewal means
re-pairing the relay), its socket, who may connect to it
(relay.access, a warn when every local account can), and whether the
Server answers it. The pairing is readable by the relay's account alone, so
run doctor as that account to see it
(sudo -u _seamless -H /opt/seamless/bin/seamlessd doctor).
Pair computers on the Devices page
A Server that serves other computers - TLS, a bind beyond loopback, or a
server_url naming another host - has a Devices page in its console,
/console/devices, and seamlessd devices does the same in the Server's
terminal (reference). Elsewhere
neither exists.
-
Pair a computer. The page shows the Server's address and its certificate fingerprint. Get a pairing code mints a code, shown once, valid for 10 minutes and for one computer, with the one-liners.
seamlessd devices codeprints the same with a new code; under peer_auth, run it as the daemon's account:sudo -u _seamless env SEAMLESS_CONFIG=/opt/seamless/etc/seamless.yaml /opt/seamless/bin/seamlessd devices code -
Waiting for your approval, under peer_auth only: each computer that used a code, with its fingerprint and until when it waits. Approve with a passkey only a computer whose fingerprint is the one its own screen shows; Deny one you do not recognize. Approving needs a signed-in browser on the passkey origin and a passkey enrolled there; the page says which is missing. Without peer_auth nothing waits: the code is the approval.
-
Paired: each relay with its key's fingerprint and each key device with the start of its key, when it paired and whether your passkey or its one-time code approved it, and when it was last seen. A relay also shows the uid its pairing recorded as yours there; without peer_auth, one that recorded none carries a warning to re-pair it to bind the owner's uid (why).
-
Revoked and expired: what ended, and how.
seamlessd devices list prints the same list in the terminal. Without TLS on
the daemon's own listener a relay cannot pair, and the Server refuses a pairing
over plain http from another computer: its code, and a key device's key, would
cross the network in the clear. A key device can still pair through a TLS proxy
on the Server's own computer. Where server_url is plain http to another host
no computer can pair, so the page and seamlessd devices code say pairing
needs TLS there and mint no code; the devices paired before stay listed and
revocable.
Where server_url names a user (https://user:password@host), the page,
seamlessd devices code, setup's closing and doctor mint no code and print no
one-liner, and say to take it out: Seamless uses none, the one-liners would
carry it, password and all, into the other computer's shell history, and setup
there refuses such an address. The address they show has no user. Leave
scheme://host:port in server_url and restart the daemon; the devices paired
before stay listed and revocable.
Where the Server's address is this computer's loopback - server_url unset on a
wildcard bind derives http://127.0.0.1:8081, or https:// with TLS - the
page, seamlessd devices code, setup's closing and doctor say the one-liners
carry it, so another computer cannot use them: they pair a client on the
Server's own computer only. Set server_url to the address the other computers
reach the Server at (by hand; setup's address step
writes it only when it makes a computer the Server), then restart the daemon.
Revoke a computer
Revoke on the Devices page, or in the Server's terminal (as the daemon's
account under peer_auth, like devices code):
seamlessd devices revoke <id or name>
The computer's credential is refused from its next request, and the requests it is making end: at once from the page, within 30 seconds from the terminal. A relay's leases, read grants and waiting access requests end with it. A pairing that waits is denied instead.
To pair it again, get a new code. A relay pairs again with the root step's
pairing line plus --replace, once its old pairing is revoked (the Server
refuses a second live device of the same name), and then restarts:
/usr/bin/sudo -u _seamless -H /opt/seamless/bin/seamlessd relay pair --server https://<server name>:8081 --fingerprint <fingerprint> --owner-uid <your uid here> --replace --code -
A renewal means re-pairing each relay
A relay pins the exact certificate the Server presented when it paired, its
SHA-256, and nothing looser: tailscale cert issues a new key at every
renewal, and certbot does too unless told to reuse it, so a pin on the key
would not survive a renewal either. A renewed certificate is another
certificate, and every relay refuses it until it pairs again.
- Ahead of time. From 14 days before the served certificate's expiry,
the Server's
seamlessd doctor(relay renewal, a warn) and its Devices page say that every relay paired there must pair again after the renewal, and name them. Doctor'stlsrow warns from 30 days out that the certificate is due; the relay row comes inside that. On each Client,seamlessd doctoras the relay's account shows the pinned certificate's expiry (relay.certificate), a warn from the same 14 days. - After the renewal. Restart the Server so it serves the new
certificate. Every call through a relay then fails, and the relay's refusal
says why: the pinned fingerprint, the one offered and its dates, and the
command that pairs it again, the one above. Compare the offered fingerprint
with the one the Server itself shows (its Devices page, or
seamlessd doctorthere), and pin that one: a changed certificate is also what an interception looks like, so the command never fills in the offered fingerprint for you. Revoke the relay on the Devices page, get a code, and run the command with the Server's fingerprint.
A relay paired with an earlier release recorded no expiry: its doctor says so
(relay.certificate, info), and re-pairing records it.
Sign in to the console from another computer
The console is the Server's: open https://<server name>:8081/console/ in a
browser on any computer. It signs in one of two ways.
- With the key, the default: the login page takes the Server's bearer key, once per browser. A Client with a relay holds no key, so it comes from the Server's config.
- With a passkey, once
console.sign_in: passkeyis set in the Server's config (file only) and the daemon restarted. No browser needs the key then, the Server's included. Add each device's passkey from the device:seamlessd approvers add, on the Server, prints the Add a passkey address (/console/passkeys/addon the passkey origin), which is not a secret. Open it on the device and create the passkey there; the page shows a short code. On the Server,seamlessd approvers approve --code <code>- as the daemon's account under peer_auth - shows that passkey and asks before it adds it. Approve only a code your own device shows.
A passkey works only for the name it was made for, and needs that name over
https: the passkey origin is the host
of the Server's TLS server_url. One synced through iCloud Keychain, Google
Password Manager or another password manager is added once for every device it
syncs to, and a device without one can use your phone's through the browser's
QR prompt. A localhost passkey works only in a browser on the Server itself.
The rest is in the console reference.
On a Client whose server_url is a relay's socket, seamlessd console-open
opens nothing - a browser cannot dial a socket - and names the console's address
instead.
Approve from another computer
A browser on any computer approves with a passkey in the Server's console, and
the Server verifies the ceremony: an agent's access request (/console/access),
a console unlock on the project's unlock page, a lock change on the project's
Overview, a pairing on the Devices page under peer_auth, and a restore while a
project is locked. The browser must be signed in, on the passkey origin, with a
passkey enrolled for the Server's name.
Under peer_auth, terminal approvals run only on the Server's computer:
seam approve, the command a console unlock's Approve from a terminal
shows (seamlessd console-open --unlock), and seamlessd approvers. Each proves
itself by becoming the daemon's account, which exists only there, so a relay
never vouches that you said yes. A terminal on the Server counts wherever you
sit: SSH to it.
Locked projects and agents on other computers
Run agents that need a locked project on the Server's computer, on its peer_auth socket (a terminal there, or SSH to it), or on a macOS or Linux computer behind a relay the Server maps:
- Behind a relay the Server maps in
peer_auth.relays, an agent is judged as the Server's socket judges one: your uid on that computer is you, the relay names the program of every process it forwards, and an agent asks for access as it would on the Server. Your approval names that computer, and its lease is keyed on the relay and the process, so it opens the project to that agent's process tree there and nothing else. A relay from before program names files nothing: update Seamless on that computer. - Behind a relay the Server does not map, every request is refused.
- On a key device, or a key client of the Server's own key, an agent never holds a lease, so it never opens a locked project. A Windows computer is always this case.
Mapping a relay, its restricted accounts (each with the plain reach, or one its entry shapes as an entry on the Server does), and what the Server then does with their requests are in Agents on another computer: relays.
When the Server is out of reach
A Client keeps no data and answers nothing from memory, so its agents lose
Seamless until the Server answers again: a session starts with no briefing,
tools and seam commands fail with the reason, and what the hooks would have
sent is lost. A relay refuses every call at once, with 502 and the reason.
Networked Seamless
has what each path does, and
Troubleshooting
the fixes.
What a remote device does not get
Sessions, projects, memories, notes, tasks, trials and recall all work over the network. What does not is every capture where the daemon reads the agent's filesystem, because on a remote device those paths are not the daemon's to read:
| Capture | Remote behavior |
|---|---|
| Claude Code plan-mode capture (plan-file saves, presentation, approval) | skipped |
| Subagent transcript capture and spawn-prompt matching | skipped |
| Git HEAD stamps on captured plans | left empty, which reads as unknown downstream |
| Session-end transcript harvest, token harvest, model sniff | skipped |
| Codex rollout harvest | skipped |
| The gardener's ship-evidence pass (git history behind a stale plan) | no evidence from repos mapped to another host |
This is a host check, not a "does the file exist" check, and that is the point: two devices with the same username and home layout produce the same transcript and plan-file paths, so a missing-file test would sometimes find a real file - the wrong one - and capture another machine's session as this one's. A paired computer's host is the name it paired with: the Server records every request of it under that name, whatever the request says.
Under peer_auth on the Server, a Client with a relay gets these captures back,
except the gardener's ship evidence. Its seam hook reads the transcript, the
plan file and the subagent transcript itself, beside the agent, and sends what
it found, as hooks on the Server's own socket do
(what changes with peer_auth on).
A key client, and a relay to a Server without peer_auth, get the table above.
The same host scoping protects project mapping. The repo map is keyed by
(host, path), and the moved-repo heal that re-points a project when its
mapped path has vanished only ever stats this daemon's rows. A remote
client's path is never stat'd on the server's disk.
One consequence to know about: a session on another host that sends no
repository root cannot be placed in a project. The daemon will not derive one -
that would mean reading its own disk to answer a question about the client's -
so the session succeeds with global scope and says so, as a warning field
on session_start and as a register-project-remote-root hook error event.
Current seam resolves the roots locally and sends them, so this is the
signature of a client too old to do that.
How doctor reports it
None of this is silent. On the server:
remote sessions- an info line listing which other machines used this daemon in the last 24 hours and how many local captures were skipped for them. With no remote sessions it readsnone in 24h, which is also how you notice a client that is not reaching you.repo map- counts local mapped paths and stats only those; rows belonging to other hosts are reported as present but "not verifiable from here" rather than treated as missing.
Every skip is also an event in the log (hook.error, stage
remote-host-skip, with the capture name and the host), recorded at INFO -
on a shared daemon a skip is the design working, not a fault.
Updates on a shared daemon
The server's automatic update check
covers the server: its briefing notice reaches every session, and a session on
another machine is told that the server can update - an action for whoever
runs it, not for that machine. A server the installer made also
updates itself by the same rules as any other
install, and a live session on any paired machine counts: it waits for all of
them to go quiet, or for its deadline. Updating the server does not update the
clients: each paired machine keeps its own seam binary (the hooks and the MCP
bridge), and updates it by re-running the pairing commands
seamlessd client-config prints on the server. A client runs no daemon, so it
has no update check of its own and never updates itself.
A relay runs root's own copy of seamlessd, /opt/seamless/bin/seamlessd,
which nothing updates by itself yet: updating a Client leaves its relay on the
old binary, and doctor warns (relay.binary). Run seamlessd setup again for
a fresh root step and paste its second block alone (a block printed before the
update carries the old binary's hash, so its check refuses the new one), then
restart the relay (after an update).
Windows: a second user on one box
The Windows install is per-user in where it writes (%USERPROFILE%) but not
isolated in what it registers: the Scheduled Task name (Seamless) is global
and the port is shared, so the last installer to run wins and a task belonging
to another account cannot be replaced without admin.
The client role is the clean way out of that collision, because a client
install registers no Scheduled Task at all. The first user runs the server;
every other user on the box pairs as a client against it. They do not even need
the steps above - client-config says so in its own loopback refusal - a
second user on the same machine can pair directly:
seamlessd install-hooks --server-url http://127.0.0.1:8081 --api-key <key>
seamlessd uninstall on such a client reports the service as not installed
and leaves the running daemon alone, and --purge removes only the config
directory - never the data dir, which belongs to the server.
By hand: widen the Server
Setup's address step writes these keys on a first install. By hand - on a
Server set up before setup existed, to change its address, or with a config
you keep yourself - edit the server's ~/.config/seamless/seamless.yaml:
addr: "0.0.0.0:8081" # listen on every interface
server_url: "http://studio.local:8081" # what clients dial
Both keys, not one. addr answers "where do I listen"; server_url answers
"where do clients reach me", and they stop having the same answer the moment
the bind is a wildcard. Leaving server_url unset on a wildcard bind derives
http://127.0.0.1:8081 - an address that means "your own machine" on every
client that receives it - and the daemon warns about exactly that combination
at startup. Putting the wildcard in server_url instead is refused outright at
config load, in any spelling of the unspecified address: http://0.0.0.0:8081
reaches, at most, the machine doing the dialing, so it can never be the right
answer to "where do clients reach me".
A concrete IPv4 addr (one LAN or tailnet address instead of the wildcard)
also listens on its interface's IPv6 addresses that reach no further, so a
dual-stack name reaches the daemon over either family. Beside a private or
tailnet address that means only unique local addresses (fd…), never a global
IPv6 address the internet may reach. Doctor's bind row lists them.
Naming server_url also arms the Host-header allowlist: the daemon then
answers the loopback names, a concrete bind host, and the host of server_url,
and refuses everything else with 421 Misdirected Request. Add any further
name the daemon is reached by - a short hostname, a raw IP - to
allowed_hosts. (A wildcard bind has no concrete host of its own, which is why
naming one somewhere is what turns the guard on there.)
Restart the daemon and check it:
seamlessd restart
seamlessd doctor
Doctor's transport rows are the ones above.
By hand: TLS
Plain http over a LAN is a legitimate choice for a key client and Seamless will
not stop you - seamlessd client-config prints a warning and continues. But
the bearer key and every memory it fetches cross the network unencrypted, so
prefer https. Pairing needs it: the Server refuses a pairing over plain http from another computer, a relay's and a key device's alike.
Both tls.cert_file and tls.key_file must be set; one without the other is
refused at load, because it cannot serve TLS. With both set the listener is
https (TLS 1.2 floor), the console session cookie is marked Secure, and
server_url derives an https:// scheme.
The certificate must cover the host of server_url - bare host, no scheme,
no port, lower-cased. That is the name clients verify and the name doctor
checks the SANs against.
mkcert (the friction-free path)
mkcert installs a local CA into your system trust store and issues certificates from it:
mkcert -install # once per machine
mkcert -cert-file ~/.config/seamless/seamless.crt \
-key-file ~/.config/seamless/seamless.key studio.local
mkcert -CAROOT # prints the CA directory
Server config:
addr: "0.0.0.0:8081"
server_url: "https://studio.local:8081"
tls:
cert_file: "~/.config/seamless/seamless.crt"
key_file: "~/.config/seamless/seamless.key"
Copy rootCA.pem from the mkcert -CAROOT directory to each client and point
tls.ca_file at it there. That one file is what makes the seam CLI trust the
server; it is the only TLS key a client has. A relay takes the same file at
pairing (--ca-file).
openssl (no extra tool)
A self-signed certificate works just as well as long as it carries the SAN and
is usable as its own root - CA:TRUE, which is why the second -addext is not
optional. Needs OpenSSL 1.1.1 or newer for -addext:
openssl req -x509 -newkey rsa:2048 -sha256 -days 825 -nodes \
-keyout ~/.config/seamless/seamless.key \
-out ~/.config/seamless/seamless.crt \
-subj "/CN=studio.local" \
-addext "subjectAltName=DNS:studio.local,IP:192.168.1.10" \
-addext "basicConstraints=critical,CA:TRUE"
Include every name and address clients dial in subjectAltName; a client that
dials an IP the certificate does not list fails in the TLS handshake. Then copy
seamless.crt - the certificate, never the key - to each client as
~/.config/seamless/server-ca.crt, and write that client's whole config:
role: "client"
server_url: "https://studio.local:8081"
tls:
ca_file: "~/.config/seamless/server-ca.crt"
mcp:
api_key: "<the server's key>"
Renewal is manual on both paths - nothing auto-renews - which is why doctor's
tls line warns from 30 days out. A renewed certificate is a new one to every
relay, which pins the exact certificate it paired with: a renewal means
re-pairing each relay, and from 14 days out doctor's relay renewal row names
them (how).
Why https changes the Claude Code wiring
Under an https:// base URL, install-hooks writes a different shape on
purpose: every Claude Code hook becomes a command hook (including
UserPromptSubmit, normally the one http hook), and the MCP registration
becomes the seam mcp-proxy stdio bridge instead of a direct URL. Claude Code
performs http hooks and http MCP connections with its own client, which has
nowhere to be told about tls.ca_file; against a private CA that request dies
in the TLS handshake. Routing both through seam puts them on the CLI's trust
store, which does read tls.ca_file. Under plain http the shapes are
unchanged.
By hand: connect a Client with the Server's key
On the server, ask for the pairing block:
seamlessd client-config # add --redact to paste it into a ticket
It prints the server URL, the key, the minimum client version, and three paste-able commands: the macOS/Linux installer one-liner, the PowerShell one, and the manual form for a machine that already has the binaries:
seamlessd install-hooks --server-url https://studio.local:8081 --api-key <key>
That command writes role: client, server_url, and mcp.api_key into
~/.config/seamless/seamless.yaml on first run and wires the detected agent
clients against the server's URL. Like every other config bootstrap it never
edits a config file that already exists: it errors and names the exact lines to
add by hand. The one existing file that is not an error is one that already
says exactly this, so re-running the installer is safe.
The installer one-liners are the same thing with the binaries and the download
included - SEAMLESS_SERVER_URL plus SEAMLESS_MCP_API_KEY, which is a pair:
the URL without the key is a hard error. A client install skips the service
branch entirely - the run prints the service step as skipped, naming the server
it is a client of - and polls the server's /healthz instead of a local one.
client-config refuses rather than printing a command that cannot work:
| Refusal | Why |
|---|---|
this install is role: client |
it has no clients of its own to pair; run it on the server |
mcp.api_key is empty |
a client would have nothing to authenticate with |
server_url is loopback |
pasted on another machine it dials that machine's port 8081. It names the fix: server_url plus addr: 0.0.0.0:8081, then restart |
Check the Client as above.
By hand: install a relay
The relay's root step, as setup prints it, is the
reference: the same commands with this computer's values filled in. These are
they with placeholders, for a Client set up another way (one paired with the
Server's key, say). The Server needs TLS on the daemon's own listener; on the
Client you need an administrator. root's group is wheel on macOS, root on
Linux.
-
On the Server, get a pairing code on the Devices page, or with
seamlessd devices code, and note the certificate fingerprint it shows. -
The account and the socket's group. On macOS, make
_seamlesswith thedscllines in Deploy it, then the group, with another unused id below 500, and its two members:/usr/bin/sudo /usr/bin/dscl . -create /Groups/_seamlessowner PrimaryGroupID <unused id> /usr/bin/sudo /usr/bin/dscl . -append /Groups/_seamlessowner GroupMembership <you> _seamlessOn Linux:
/usr/bin/sudo /usr/sbin/useradd --system --user-group --shell /usr/sbin/nologin --home-dir /opt/seamless/home _seamless /usr/bin/sudo /usr/sbin/groupadd --system _seamlessowner /usr/bin/sudo /usr/sbin/usermod -aG _seamlessowner <you> /usr/bin/sudo /usr/sbin/usermod -aG _seamlessowner _seamless -
The layout, root's copy of
seamlessd, and the pin (macOS; on Linux use-g root,root:rootand/bin/chown). Your shell reads the binary and root only writes it, so root opens no file of yours:/usr/bin/sudo /usr/bin/install -d -o root -g wheel -m 0755 /opt/seamless /opt/seamless/bin /opt/seamless/etc && /usr/bin/sudo /usr/bin/install -d -o _seamless -g _seamless -m 0755 /opt/seamless/run && /usr/bin/sudo /usr/bin/install -d -o _seamless -g _seamless -m 0700 /opt/seamless/home /opt/seamless/relay && /usr/bin/sudo /usr/bin/tee /opt/seamless/bin/.seamlessd.new >/dev/null < ~/.local/bin/seamlessd && /usr/bin/sudo /usr/sbin/chown root:wheel /opt/seamless/bin/.seamlessd.new && /usr/bin/sudo /bin/chmod 0755 /opt/seamless/bin/.seamlessd.new && /usr/bin/sudo /bin/mv -f /opt/seamless/bin/.seamlessd.new /opt/seamless/bin/seamlessd && seamless_uid=$(/usr/bin/id -u _seamless) && printf '%s %s\n' _seamless "$seamless_uid" | /usr/bin/sudo /usr/bin/tee /opt/seamless/etc/daemon-account >/dev/null && /usr/bin/sudo /bin/chmod 0644 /opt/seamless/etc/daemon-accountA certificate made with mkcert or openssl also goes in, for the pairing to trust: its root (mkcert's
rootCA.pem, or the openssl certificate itself) as/opt/seamless/etc/server-ca.crt, root's, mode0644. The relay refuses to run with any part of this that another account could rewrite, and says which. -
Pair it, as its account, pasting the code when it waits (
--code -keeps it out of the process list and your shell history), and adding--ca-file /opt/seamless/etc/server-ca.crtfor the certificate above:/usr/bin/sudo -u _seamless -H /opt/seamless/bin/seamlessd relay pair --server https://<server name>:8081 --fingerprint <fingerprint> --owner-uid <your uid> --code ---fingerprintmakes sure the code goes only to that certificate.--owner-uidis your uid on this computer (id -u), which the Server records: without peer_auth it serves that uid alone through the relay (why). Under peer_auth the command waits until you approve the relay on the Devices page, and prints the key fingerprint the page shows for it. Once paired, it prints the certificate it pinned, the name it speaks for and the uid it recorded as yours. -
Run it as a service, as its account, never as root:
/opt/seamless/bin/seamlessd relay serve --socket-mode 0660 --socket-group _seamlessowner, from the LaunchDaemon or the systemd unit in the service reference. Without the socket flags every local account may connect; a Server without peer_auth refuses every one but yours, and a relay paired with an earlier release, which recorded no uid, takes each one for you. -
Point your agents at it. Your config on the Client names the socket and holds no key:
role: client server_url: "unix:///opt/seamless/run/seamlessd.sock"Then install the hooks and MCP registration against it:
seamlessd install-hooks --client claude # or codex, or all -
Under peer_auth, map it on the Server in
peer_auth.relays, by the name the Devices page shows, to your uid on the Client, and restart the daemon (how). Until then the daemon refuses it. -
Check it.
seam doctoron the Client reaches the Server through the relay.seamlessd doctoradds the relay's rows (relay.account,relay.pairing,relay.socketand the rest): run as you, they cover the account, the layout and the socket; run as the relay's account (sudo -u _seamless -H /opt/seamless/bin/seamlessd doctor), its pairing and whether the Server accepts it too.
Related
- Networked Seamless - the model: the relay, pairing, approvals, and what stops when the Server is out of reach.
- Install & deploy - the security posture you are accepting, and the installer overrides.
- Configuration -
role,server_url,allowed_hosts, and thetls:block with every default. - seamlessd CLI -
setup,client-config,devices,relay,install-hooks --server-url, andserveunder TLS. - Lock projects behind your approval - peer_auth on the Server, and the relays it maps.
- Import, back up & restore -
seamlessd exportand a merge import, which is how you fold each device's existing local instance into the shared one before switching it to a client. - Hooks - the identity the hooks send, and what the daemon does with it.