Modes

SpanDock is one app that runs in one of several modes. The mode decides what a computer does: collect telemetry from a team, report to someone else's server, or work on its own. You choose it once, on first launch, and SpanDock remembers it across restarts and updates.

The modes

Mode	Runs on	Receives from	Sends to
Server (hub)	One always-on machine	Its own tools and every paired client	Its destinations, including the local store
Satellite	Extra always-on machines	Its own tools and the clients assigned to it	Its destinations, and the hub for storage
Client	Each developer machine	Its own tools	Its server only, plus an optional local copy
Standalone	One machine	Its own tools	Its destinations

Server

SpanDock Server runs on one always-on machine. It stores every signal in an embedded database, fans telemetry out to your destinations, and serves paired clients over an encrypted WireGuard tunnel (no account, no open ports). It also manages client identities and their settings, offers MCP for chat tools, and has a built-in assistant.

When you add satellites, the first server becomes the hub. It keeps the settings and the history, and satellites take their settings from it.

Satellite

SpanDock Satellite is an extra server that joins a hub to spread clients and delivery across machines. Clients pair with and connect to a satellite exactly as they would to any server. A satellite forwards to your destinations itself and sends every record to the hub for storage. Its settings are managed on the hub. See Satellites and failover.

Client

SpanDock Client runs on a laptop or workstation. It receives telemetry from the local tools and forwards everything to its server through the encrypted tunnel. If the server can't be reached, it queues uploads on disk and sends them when the connection returns. A local copy of the data is optional. Its settings can be managed from the server. See Pairing clients.

Each client has its own identity. It sees only its own data, while the server administrator sees everything.

Standalone

Standalone does both jobs on a single machine, with no tunnel. Use it for a personal setup or to try SpanDock.

How the mode is chosen

On the first launch the dashboard opens at http://127.0.0.1:8787 and asks whether this computer is a server, a client or standalone. When you add a server to an existing hub, choose Join it as a satellite instead.

Until you choose, SpanDock runs only the setup page: no receiver, no database, no tunnel. After you choose, it saves the mode and restarts in it. Every later launch, updates included, uses the saved mode.

Headless machines

A machine with no screen, such as a VM, can't show the setup page in a browser. Choose the mode once on the command line instead:

./spandock -role=server -open=false -menubar=false

The -role flag accepts server, client or standalone. It is needed only on the first start. If a later start passes a -role that disagrees with the saved mode, SpanDock refuses to start rather than switching, so a stale login item can't start the wrong mode.

To join a headless satellite, see Satellites and failover.

Seeing and changing the mode

The current mode shows under Settings → Mode, and next to the version in the sidebar.

To change it, choose Settings → Mode → Change to … and confirm by typing the mode's name. Changing the mode is a reset, not an edit:

SpanDock deletes this computer's setup for that mode: its data, settings, pairing and secrets, and its login item.
It restarts and asks for the mode again.

Other computers are not affected. If you change a client, pair it again afterwards. If you change a server, its clients must be paired with the new server.

On a server, turn on Settings → Open at login so it keeps running after a restart. On Linux this installs a systemd user service. With a Homebrew command-line install, you can instead run it in the background:

spandock -role=server -open=false -menubar=false   # first start: choose the mode, then Ctrl-C
brew services start spandock