Install on a fleet

This page covers rolling SpanDock Client out to many company computers: pre-register them, enrol each one straight to its server with nobody at the keyboard, choose what people see, lock them to the server, and protect SpanDock and its watchdog from being removed. Unattended enrolment, the lock and protection need version 0.57 or later on the server and the computers.

What you need

A running server, signed in to https://spandock.com. See Getting started, or Deploy in the cloud for a machine without a screen.
A plan that covers the number of computers. The Personal plan covers 3 clients. Standard, Premium and Enterprise have no client limit. The server checks the limit when you make pairing codes, and the server's own machine doesn't count.
A way to run a command on each computer, as the person who uses it: your device management tool (MDM), a script, or the person. SpanDock keeps its settings and login items in that person's own account, so don't run it as the system or administrator account.

1. Pre-register people and computers

Add people, and the computers they'll use, before anything is installed. Open People & computers → People and choose Import… to upload a CSV, or add them one at a time with Add person and Expect a computer.

The CSV has a header row. email or external_id is required; every other column is optional:

email,name,team,title,tags,groups,external_id,status,computer_name,serial,hostname,os_user,platform
maya@example.com,Maya Chen,Platform,Staff engineer,eu,eng-all;platform,E1001,active,Maya's MacBook,C02XYZ123,maya-mbp,maya,macos

Commas or semicolons separate the columns, and the file is UTF-8. Several tags or groups in one cell are separated by ;. A file has at most 10,000 rows and 5 MB.
A preview shows what each row does, and why a row is skipped. Rows match existing people by email, else by external ID, so importing the same file twice changes nothing.
A row with computer columns adds an expected computer. When a computer pairs, it is matched by the pairing code made for it, else by a hostname or OS user that only one expected computer has. It is then assigned to that person and named. Matching never approves a computer.

On the server's command line, the same import:

spandock admin people import people.csv            # the preview; nothing changes
spandock admin people import people.csv -apply     # import it
spandock admin expected add -person maya@example.com -hostname maya-mbp

2. Make an install code, or one pairing code per computer

One install code for the whole fleet (Standard and up)

An install code enrols many computers: one code in one MDM package. Make it on the server under People & computers → People → Install codes, or:

spandock admin install-codes create      # see --help for the name, expiry and limit on uses
spandock admin install-codes list
spandock admin install-codes revoke <id>

It works until it expires (1 to 90 days, 30 by default), reaches its limit on uses (optional), or you revoke it. Only its hash is kept on the server, and it's shown once.
It can make the computers it enrols Headless, and on Enterprise Locked to this server (step 5).
Each computer is matched to its person as below: by its own pairing code, then its serial number, then the person's email, then its hostname, then its OS user. Enrolling never approves a computer by itself: approval works as in step 6.
Making install codes needs an administrator, on the hub's own dashboard.

Or one pairing code per computer

In People & computers → People, choose Make N pairing codes to make a single-use code for each computer that is still waiting. You get a CSV to hand out, or to push to each computer with your MDM. This needs an administrator, on the hub's own dashboard (not through remote management).

Or, on the server:

spandock admin expected codes -all -out codes.csv   # a single-use pairing code per waiting computer

The file has the columns email, computer_name, pairing_code and expires_at. You can make up to 1,000 codes at a time.

Each code works once. By default it stops working after 7 days unused. Change that under Settings → Clients → Pairing codes work for (1 to 90 days).
Treat the file like a list of passwords: a pairing code contains the server's tunnel address and its encryption key. Delete the file once the codes are used. See Pairing clients.

3. Install the app and start it once

Use the install method for each operating system, then start SpanDock once in client mode with the flags that skip the first-launch screens:

-role=client chooses client mode, so the setup page doesn't ask.
-accept-eula accepts the End User License Agreement, which setup otherwise asks for on screen. You can set SPANDOCK_ACCEPT_EULA=1 instead.
-open=false doesn't open the dashboard.
-menubar=false shows no menu bar or tray icon for this run.

-role is needed only on the first start. A later start with a -role that disagrees with the saved mode refuses to start.

macOS

With Homebrew:

brew install --cask spandock/spandock/spandock
/Applications/SpanDock.app/Contents/MacOS/SpanDock -role=client -accept-eula -open=false -menubar=false

Without Homebrew, copy SpanDock.app from the DMG (SpanDock-<version>-macos-arm64.dmg for Apple Silicon, -amd64.dmg for Intel) to /Applications, then clear the quarantine flag once so macOS doesn't block the first launch:

xattr -dr com.apple.quarantine /Applications/SpanDock.app

SpanDock isn't signed with an Apple Developer ID yet, which is why this step is needed. The Homebrew cask clears the flag itself.

Windows

Unzip spandock-windows-amd64.zip and run:

.\spandock.exe -role=client -accept-eula -open=false -menubar=false

Linux

With Homebrew:

brew install spandock/spandock/spandock
spandock -role=client -accept-eula -open=false -menubar=false

Or from the tarball (spandock-linux-arm64.tar.gz on ARM):

curl -fLO https://github.com/SpanDock/spandock-releases/releases/latest/download/spandock-linux-amd64.tar.gz
tar -xzf spandock-linux-amd64.tar.gz
./spandock -role=client -accept-eula -open=false -menubar=false

Keep the binary in a folder its user can write to, such as ~/.local/bin, so it can update itself. The one-line install script is for servers, not clients.

There are no .pkg, MSI or deb installers yet.

4. Enrol each computer

Enrol each computer with no window, as the person who uses it, with the install code or its own pairing code:

spandock client enroll -code-file /path/to/code.txt -email maya@example.com -accept-eula

The code can also come from standard input (-code-file -) or the environment variable SPANDOCK_PAIRING_CODE. It's never printed, and there's deliberately no flag for it, so it stays out of the process list.
-email (or SPANDOCK_PERSON_EMAIL) matches the computer to its person; the computer's serial number is sent too. -headless makes it start headless.
While SpanDock runs, the command asks it to pair, and it restarts to connect. Otherwise it saves the pairing for the next start.

Or start SpanDock the first time with the code in its environment. A first start with a code shows no onboarding window:

SPANDOCK_PAIRING_CODE='sdinstall1:…' SPANDOCK_PERSON_EMAIL=maya@example.com SPANDOCK_ACCEPT_EULA=1 spandock -headless

If the server can't be reached, SpanDock starts anyway and tries again in the background (after 1, 2, 4 and up to 15 minutes), then restarts to connect. A code the server refuses (expired, revoked, used up, or a plan without install codes) isn't tried again. An older server doesn't take install codes: the computer says the server needs updating first.

To pair by hand instead, open http://127.0.0.1:8787 on the computer, go to Settings → Server connection, paste its code and save.

5. Choose what people see

The server manages each client's settings. Open Computers → Client defaults to set values for every client, or select some computers and choose Edit settings. A computer applies them after it pairs and first syncs with the server, within a minute. Until then it runs as it was started in step 3. Older versions ignore the settings below.

Run in the background: Headless

Turn on Headless (under Advanced). It is in every plan. On a headless client:

there is no menu bar or tray icon, so there is no Quit item;
the dashboard never opens by itself;
the local dashboard shows only a "Managed by your organization" page: the server's name, the connection, and the notices the person must see;
local changes are refused. The person can't change the mode, pair again with another code, change settings, or restart SpanDock from its dashboard.

What still works on a headless client:

telemetry from the AI tools, guardrails, and the MCP and model proxies;
the person's own choices: whether to share their prompts (when you let them choose), acknowledging the privacy notice and the EULA, their own accounts (MCP gateway sign-in and just-in-time access), and deleting their own Token Saver dry-run report;
checks that change nothing, such as checking for an update.

The prompt-sharing and privacy notices also come as operating system notifications, at most once per change, or once a day while they wait for the person. Turning Headless on or off restarts SpanDock once when the menu bar icon has to go or come back. The server's own machine ignores it.

Headless doesn't stop a person from removing SpanDock's login items in their own account, or deleting the app: see step 9.

A first start is already headless when the install code or the client defaults say so, or with -headless (or SPANDOCK_HEADLESS=1): no menu bar icon and no window, before the first settings sync.

Leave Headless off and set these under The person's view instead:

Menu bar icon: show or hide it.
Open at login: add SpanDock to the person's login items, so it starts when they sign in. It isn't on by default, so turn it on for a fleet.
Notices shown to the person: turn off kinds of notices that aren't required: updates, connection, guardrail events, suggestions, and tips. Required notices are always shown: prompt sharing, the privacy notice, the EULA, guardrail messages in the AI tools, and "update required".

Open at login and Notices shown to the person apply to headless clients too. A setting you leave unset is decided on the computer; a setting you set is read-only there.

Lock to this server (Enterprise)

Turn on Lock to this server in the client defaults, per computer, or as an install code's option. On a locked computer, with or without its window:

the person can't change the mode, reset SpanDock, pair it with another code, or change the sidekick's settings: these are refused and hidden;
the menu bar has no Quit item, and the sidekick starts SpanDock again even after someone quits it.

Only the server turns the lock off. Someone who can delete SpanDock's files or the app still can, and the server then tells its admins (Settings → Notifications):

A computer locked to its server was reset, when the same computer (by serial number, or hostname and OS user) enrols again;
A computer locked to its server stopped reporting, when one hasn't reported for 24 hours (change the hours there).

6. Require approval for new clients

Turn on Settings → Clients → Require approval for new clients on the server. A computer that uses a pairing code then waits on the Computers page until you approve it, and keeps its telemetry on the computer until then. Matching a computer to an expected one never approves it.

Approve computers on the Computers page (one at a time, or Approve all), or on the server:

spandock admin clients               # list clients
spandock admin approve CLIENT-ID     # approve a pending client

7. Check the fleet

The Computers page lists every computer, with tabs for Online, Needs approval, Offline, Out of sync (settings not applied yet), Low memory or disk and Revoked.

A computer that hasn't paired yet shows when its pairing code expires, or that it has expired. Make a new code for it in step 2.
Headless computers carry a Headless badge.
Click a computer to see its machine, its connection and its settings.

8. The sidekick keeps it running

Every SpanDock installs a small watchdog, the sidekick, on its first start. It restarts SpanDock when it stops or stops answering, at most 3 times an hour. After that it stops trying and says so under the bell. Settings → Sidekick shows what it sees, and turns it or its actions off; on a headless or locked client the person can't change it.

A clean quit (from the menu bar, a stop signal, an update or a restart) is left alone, unless the computer is locked to its server (step 5).

9. Protect SpanDock and the sidekick

By default SpanDock and its sidekick start from login items in the person's own account, so the person can remove them. An administrator can install machine-wide login items instead, which a person without administrator rights can't remove or turn off. Run this once per client computer, as root or from an administrator prompt, for example from your MDM's script after it installs SpanDock:

sudo /Applications/SpanDock.app/Contents/MacOS/SpanDock system install   # macOS
sudo /usr/local/bin/spandock system install                                         # Linux

On Windows, run spandock.exe system install from PowerShell opened with Run as administrator.

Where SpanDock must be: somewhere only administrators can change, because the login item runs it for every user: /Applications on macOS, a root-owned folder such as /usr/local/bin on Linux, C:\Program Files\SpanDock\ on Windows. Otherwise the command refuses and says where to put it.
Updates: SpanDock then can't update itself without an administrator. Update it with your MDM, and run system install again after each update. Running it again changes nothing that's current; -dry-run shows what it would do.
In SpanDock: Open at login stays on and the sidekick can't be switched off. The server's Computers page shows Protected next to the computer's name.
macOS: also deploy a managed login items profile, so System Settings shows the items as managed with no switch. spandock system profile -out login-items.mobileconfig writes an example for your MDM to sign and deliver (macOS 13 or later).
Check a computer: spandock system status, which needs no administrator, for example as an MDM check.
Remove it: spandock system uninstall -all-users removes the machine-wide items and every user's own SpanDock login items, and prints each step. Add -remove-data to also delete every user's SpanDock settings and data. It leaves the app itself.

It runs on every plan. On Enterprise, the server's bell also says when someone switched a protected computer's login items off and SpanDock turned them back on.

What it doesn't stop. A local administrator can always remove software: protection means a person without administrator rights can't. Someone with a terminal can still stop SpanDock for their current session or disable its items in their own account. SpanDock turns a disabled item back on within 5 minutes while it runs, and the sidekick restarts it when it stops unexpectedly. On Windows the sidekick is a login item, not a service.

Coming next

These are planned, not available yet:

Signed installers (.pkg, MSI, deb and rpm) and managed preferences for MDMs, so the install code and the options come from the MDM profile.