Skip to content
SpanDock

Pairing clients

A client is a developer machine that reports to your server. You connect it with a single-use pairing code, and from then on it forwards its tools' telemetry over an encrypted WireGuard tunnel (no account, no open ports). This page covers pairing, approval, managing clients and their settings from the server, and managing a headless server from a client.

Pair a client

  1. On the server: open Clients and choose Add client. Copy the pairing code. If you have satellites, SpanDock asks which server the new client connects to.
  2. On the client: install SpanDock, choose Client on the first launch, and paste the code under Settings → Server connection. Save. The client restarts and connects.
  3. On the client: open Integrations and configure your tools, as described in Getting started.

A pairing code works once. The first computer to use it becomes that client and is named after the computer. You can rename it later.

Treat a pairing code like a password: it contains the tunnel address, which includes the tunnel's encryption key. If a code leaks before it is used, revoke that client. To change the server's tunnel address entirely, use Settings → Encrypted tunnel → New address… on the server. Every client must then be paired again.

Require approval

To vet new computers before they report, turn on Settings → Require approval for new clients on the server. A newly paired client then waits on the Clients page as pending. Its machine details are visible, but it holds its telemetry in its on-disk queue until you approve it. Once approved, the queued data is sent.

Manage clients

Online clients show a pulsing green dot. Click a client to see its machine (model, processor, memory, disk, OS and uptime) and its network connection. From there you can:

  • change its settings remotely;
  • restart or update it;
  • configure its AI tools;
  • rename it;
  • re-pair it with New pairing code, which issues a fresh single-use code for the same client and keeps its settings and history;
  • revoke it, which cuts it off at once;
  • remove it.

The server as a client

The server machine is listed as a client too, so you can manage its own AI tools without running SpanDock Client next to it. Its settings are applied directly on the server. You can turn this off in Settings.

Manage client settings from the server

Choose Client defaults to set values for every client, or select some clients and choose Edit settings to set values for just those. You can manage:

  • ports;
  • the local copy of the data and its retention;
  • open at login;
  • automatic updates or a pinned version;
  • which tools to configure;
  • the MCP proxy and the model proxy;
  • the menu bar icon.

A setting you leave unset is decided on the client. A setting you set is read-only on the client. Clients apply changes within a minute and report back, and the table shows which clients are in sync. The connection details themselves can't be managed, because the client needs them to connect.

A server without a screen

On a VM or any machine you reach only through the tunnel, use the admin commands. They talk to the SpanDock server already running on that machine.

spandock -role=server -open=false -menubar=false   # first start chooses the mode
spandock admin pair my-laptop                       # a single-use pairing code for a client
spandock admin management-token my-laptop           # lets that client manage this server
spandock admin clients                              # list clients
spandock admin approve CLIENT-ID                    # approve a pending client

Manage the server from a client

A client can open the server's full dashboard over the tunnel it already has. This needs two credentials: the client's own pairing (the client must be approved) and a management token created on the server. A management token can be limited to one client. Like every token, it is stored only as a hash and shown once, and you can revoke it at any time.

On the laptop, in SpanDock → Settings:

  1. Paste the pairing code under Server connection.
  2. Paste the management token under Server management.
  3. Choose Open server dashboard. The server's dashboard opens at http://127.0.0.1:8789 on the laptop, through the encrypted tunnel.

A banner marks the page as remote management, and the server logs every remote change with the client and token name. A few actions stay on the server machine itself: resetting the mode, creating or revoking management tokens, and restarting the tunnel or changing its address.

Remote management also works when the client is connected to a satellite: the satellite passes the request to the hub, which checks both credentials itself.