Install a server and pair your team's computers: server, satellite and client

This guide is for anyone setting up SpanDock for a team for the first time. It explains the three roles a computer can take, then walks through installing a server, activating it, configuring a first AI tool and pairing your team's computers. At the end it covers when a second server, a satellite, is worth adding.

The three roles

SpanDock is one app that runs in one of several modes. You choose the mode once, on first launch, and SpanDock remembers it across restarts and updates.

Role	Runs on	What it does
SpanDock Server (the hub)	One always-on machine	Collects telemetry from its own tools and every paired client, stores it, and forwards it to your destinations
SpanDock Satellite	Extra always-on machines	Joins the hub to spread clients and delivery across machines; sends every record to the hub for storage
SpanDock Client	Each developer machine	Receives telemetry from local tools and forwards it to its server over an encrypted tunnel

Just you? Run a server on your own computer. There is no separate single-user mode: a server on your own machine is how one person uses SpanDock.

A client has its own identity and sees only its own data. The server administrator sees everything. If the server can't be reached, a client queues uploads on disk and sends them when the connection returns.

Prerequisites

• A machine for the server that stays on: a workstation, a small server or a VM. SpanDock runs on macOS (Apple Silicon and Intel), Linux (x86-64 and ARM64) and Windows (x86-64).
• A https://spandock.com account to activate the server. Signing up is free and creates a Personal license.
• The developer computers you want to pair.

Step 1: install

The getting started guide lists every download. On a Mac, Homebrew is the easiest route:

brew install --cask spandock/spandock/spandock
open -a SpanDock

On Linux, download and run the archive:

curl -fLO https://github.com/SpanDock/spandock-releases/releases/latest/download/spandock-linux-amd64.tar.gz
tar -xzf spandock-linux-amd64.tar.gz
./spandock

On Windows, unzip spandock-windows-amd64.zip and run spandock.exe. Every file is listed with its SHA-256 in checksums.txt next to the downloads, if you want to verify it.

Step 2: choose Server on first launch

The dashboard opens at http://127.0.0.1:8787 and asks what this computer is. Choose Server. Until you choose, SpanDock runs only the setup page: no receiver, no database and no tunnel.

A machine with no screen, such as a VM, can choose the mode on the command line instead. The -accept-eula flag accepts the End User License Agreement, which setup otherwise asks for on screen:

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

Step 3: sign in to activate the server

Every server signs in once to https://spandock.com. There is no key to paste and no way to skip it.

1. SpanDock shows a code and opens https://spandock.com/activate.
2. Sign in on any device and check that the machine shown is yours.
3. Choose the license for this server and Approve. The server starts within a few seconds.

A headless server prints the link and the code on its first start and waits until you approve it. The first activation starts a 30-day trial that includes everything in Premium and some Enterprise features; after it, the server runs on its license's plan, Personal unless you choose a paid one. Licensing and activation has the details.

After activation, the Setup guide asks a few questions about your team and recommends a setup.

Step 4: configure a tool

Open Integrations, select a tool and choose Configure, then restart the tool. Claude Code, Codex, Gemini CLI, Qwen Code, GitHub Copilot Chat (VS Code), Goose and Mistral Vibe are configured for you. For tools that read only environment variables, such as OpenCode or Cline, SpanDock shows the exact lines to add.

Use the tool as usual, then open the Dashboard: sessions, tokens, cost and errors appear as they arrive.

Step 5: pair your team's computers

1. On the server: open Clients, choose Add client, and copy the pairing code.
2. On the developer's computer: install SpanDock, choose Client on first launch, and paste the code under Settings → Server connection. Save. The client restarts and connects.
3. On the client: open Integrations and configure its tools.

Clients need no account, only the pairing code. A code works once: the first computer to use it becomes that client. Treat a code like a password, because it contains the tunnel address and its encryption key. If one leaks before it is used, revoke that client.

Require approval

To vet new computers before they report, turn on Settings → Require approval for new clients. A newly paired client then waits on the Clients page as pending, holding its telemetry in its on-disk queue until you approve it.

Manage clients from the server

Click a client to see its machine and connection. From there you can change its settings, restart or update it, configure its AI tools, rename it, re-pair it with a new code, revoke it or remove it. Client defaults sets values for every client at once; a value you set is read-only on the client, and clients apply changes within a minute.

Verify it works

• On Clients, each paired computer shows a pulsing green dot when it is online.
• On Activity, the Sessions tab lists the client's tool sessions.

When to add a satellite

One server is enough for most teams. Satellites are extra servers that join the hub when you want to spread client connections and delivery across machines. Satellites are on the Premium and Enterprise plans, and in the trial.

• Clients fail over by themselves. Each client has an assigned primary server and an ordered fallback list. When its server stops answering, it moves to another without losing data.
• The hub keeps settings and history. Satellites forward to your destinations themselves and send every record to the hub for storage. Settings are edited on the hub only.
• Adding one: on the hub, open Settings → Scaling → Add server and copy the join code, which works once, for 30 minutes. On the new machine, choose Join it as a satellite on first launch and paste it.

The Cluster page shows how many batches satellites are holding for the hub. A backlog that keeps growing is the signal that you have outgrown one hub.

Troubleshooting

• The server won't finish setup. A new server can't finish until it is activated. Use Settings → License → Sign in to activate.
• A client doesn't appear. Check that its pairing code wasn't already used, and whether approval is required and the client is waiting on Clients.
• A satellite goes offline after a reboot. A satellite started by hand in a terminal stops with that session. Install it as a service, as Satellites and failover describes.

Next steps

• Forward telemetry to the tools you already use: Destinations.
• Put the model proxy and budgets in front of model spend: Model proxy and budgets.
• Give every computer one governed MCP server: the MCP gateway.