Part 2: Run it as a fleet worker
A fleet worker takes work from other machines over its fleet listener: a second port the daemon opens on the machine's own tailnet address (never 0.0.0.0, never loopback, and not behind Tailscale Serve, which would make every caller look like the machine itself). A request is run only when both checks pass:
- The fleet token. It is the serve token (Keychain item
darkmux-serve-token, or DARKMUX_SERVE_TOKEN), one value shared by every machine in the fleet. The check is that the caller holds that shared token. That keeps out something on an allowed machine that cannot read it (an agent container can reach tailnet addresses, but not the Keychain). It is not proof the caller is darkmux: any process running as your user can read the Keychain item, and machine list --deep sends the same token to every machine in the roster.
- The sending machine, as the network reports it. The worker asks Tailscale which node is on the other end of the connection (
tailscale whois), and accepts only a node on its own allow-list, fleet.accept_work. Deny by default: a node that is not listed runs nothing, token or not.
Each allow-list entry also has a scope: the profiles (on the worker) that machine may run. A profile outside it is refused, and so is a profile that runs on the worker's utility model: utility work (compaction, radio routing) always stays on the machine it serves.
security add-generic-password -U -a "$USER" -s darkmux-serve-token -w
darkmux config set runtime.daemon_auth_enabled true
darkmux machine trust laptop --profiles host,coder-studio --roles radio-host,coder
darkmux config set fleet.listener.enabled true
brew services restart darkmux
darkmux doctor 2>&1 | grep -i fleet
Then, from the laptop (the fleet token in its Keychain too, and the studio in its roster, below):
darkmux dispatch radio-host "summarize today's runs" --machine studio --profile host
With --wait (the default) the command returns when the studio's dispatch finishes, with its exit code and output. --no-wait returns as soon as the studio accepts the job. A refusal comes back immediately, naming the reason: studio does not accept work from macbook-pro, not in the allow-list scope: profile coder-big, or studio is busy running <session> (a worker runs one submitted job at a time). darkmux machine untrust laptop takes the laptop back off the list; both verbs take effect on the next request, with no restart. Removing a machine from the tailnet revokes it everywhere, and rotating the fleet token is one secret to redistribute.
What an entry grants, exactly. Roles: only the roles listed (a role is a tool palette; there is no "any role", and utility roles are refused). Images: the job runs on darkmux's own runtime image unless it names one the entry lists with --images. Workspace: --workspace true lets the peer mount any directory under this machine's darkmux worktrees base read-write as the job's workspace, including live worktrees your own git and test commands later run in. In effect that lets the peer run code on this machine, so grant it only to a machine you would give a shell; the default is none. (darkmux does not yet exclude worktrees that local missions are using.) A submitted job never mounts this machine's shared toolchain cache, so nothing it writes is run by your own later dispatches. One job at a time: a trusted peer that keeps resubmitting can keep the slot busy; that is accepted in a model where every trusted peer is yours.
Upgrade every machine. A 3.x daemon still claims work off the old Redis queue (darkmux:work) and re-creates it when it starts, so the unauthenticated queue stays open until no machine runs 3.x. darkmux doctor names any daemon still consuming it. Mixed versions also do not talk: a 4.0 machine sending to a 3.x one gets "no answer" (3.x has no fleet listener), and a 3.x machine's --machine dispatch waits on a queue no 4.0 machine reads, until its timeout.
The sender checks the receiver too. Every request that carries the fleet token (a --machine dispatch, machine status/resources <id>, machine list --deep, and the daemon's peer mission-graph proxy) first resolves the roster address, asks Tailscale which node is there, and refuses unless it is a tailnet node; the first contact pins that node in the roster (as machine add does), every later request checks it is the same node, and the connection goes to that verified address. Only this machine's own daemon and loopback (same-host) entries skip the check, and those never receive the token: whatever listens on a loopback port gets nothing (your own daemon does not ask for it from this machine), so reaching a peer through an ssh tunnel with the token is not supported. Anything a peer sends back has its control characters, bidirectional overrides and zero-width characters removed before it is printed; a field shown in a table or on one line also loses its newlines and tabs and is cut to its column, so a peer cannot print a line of its own.
The listener protects itself too: at most 32 connections at once and 3 per peer address, 3 seconds to send the request headers, at most 4 requests in flight per trusted machine once it is identified, and refusals logged at most 5 per peer per minute (the rest are counted and reported each minute). A node that routes a subnet can spread connections over many addresses, so the per-address cap bounds a single address, not a single node; the per-machine cap applies only after the token and identity checks. A job from another machine is never attributed to one of this machine's missions (its phase id is dropped).
Fail closed. If Tailscale cannot say who is calling (it is stopped, logged out, or the connection came over the office LAN rather than the tailnet), the request is refused. A hardware id is never used to decide: every flow record carries one, so any machine could repeat it.
Register each machine in the others' rosters: a sender finds a worker's address there (the host of the roster address, on fleet.listener.port), and machine list shows it. Use each machine's tailnet DNS name, not its IP — a peer that later sits behind Tailscale Serve routes by Host header, so a bare IP gets Tailscale's own 404 even though the daemon is healthy:
darkmux machine add mini-1 --address <peer-tailnet-dns-name>:8765
darkmux machine add <hub-id> --address <hub-tailnet-dns-name>:8765
darkmux machine list
The DNS name above resolves — but only reaches the daemon if something is actually listening on that machine's tailnet interface at :8765. The
quick-path daemon binds
127.0.0.1:8765 only; the
Tailscale Serve recipe proxies a
browser to it on
:443, a different port, and doesn't expose
:8765 on the tailnet. For
machine list --deep /
machine status to reach a peer at its default port, that peer needs a genuinely non-loopback daemon:
darkmux serve --bind <its-tailnet-ip> plus
DARKMUX_SERVE_TOKEN set to the fleet's shared token (a non-loopback bind refuses to start without one, and
machine list --deep already sends it). Keep the roster entry pointed at the DNS name regardless — it's still what survives Tailscale Serve ever landing in front of that daemon later.
