Skip to content
Beta

Getting started

SpanDock is a self-hosted control plane for AI coding tools: one place to set the rules for every tool, model and connector, see what they do, and keep the cost in hand. Claude Code, Codex, Gemini CLI, GitHub Copilot and other tools send it OpenTelemetry. SpanDock shows every session, tool call, model call, token and dollar on a local dashboard, stores it in an embedded database on your own machine, and forwards it to Langfuse, Grafana Cloud, New Relic or any OTLP endpoint you choose. It needs no Docker and no cloud account. This page takes you from download to your first session on the dashboard in about five minutes.

1. Install

SpanDock runs on macOS (Apple Silicon and Intel), Linux (x86-64 and ARM64) and Windows (x86-64). Downloads are published at https://github.com/SpanDock/spandock-releases/releases/latest.

On a Mac, Homebrew is the easiest way:

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

Without Homebrew, download SpanDock-<version>-macos-arm64.dmg, drag the app to Applications, and open it from there. Intel Macs have a -amd64.dmg in major releases only (1.0, 2.0, …). The app is signed with SpanDock's Developer ID and notarized by Apple, so macOS opens it without asking.

On Linux:

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.

2. Pick a mode on first launch

The dashboard opens at http://127.0.0.1:8787 and asks what this computer is:

  • Server ("for yourself or your team"): collects telemetry, stores it and forwards it. To use SpanDock on your own, run a server on your own computer.
  • Client ("connect to a server"): a developer machine that reports to a server.

The answer is saved, and updates never ask again.

A new server then asks you to sign in to https://spandock.com: it shows a code, you approve the server on https://spandock.com/activate from any device, and it starts. Signing up is free and creates a Personal license; the first activation starts a 30-day trial of the paid features. Clients need no account, only their server's pairing code. See Licensing and activation. See Modes for the details, including headless machines and how to change the mode later.

After its first activation, a server opens the Setup guide. It asks a few questions about your team, recommends a setup, and gives the install steps with a diagram of the plan. For cloud tools and SDKs it recommends a private hub plus a public edge satellite.

3. Configure a tool

Open Integrations, select a tool and choose Configure. Then restart the tool.

  • Configured for you: Claude Code, Codex, Gemini CLI, Qwen Code, GitHub Copilot Chat (VS Code), Goose, Mistral Vibe and Cursor (through its agent hooks, from the next version).
  • Shown with the exact lines to add, because they read only environment variables: OpenCode, Kilo Code, GitHub Copilot CLI, Cline, Continue CLI and Factory Droid.

Any other tool that speaks OTLP/HTTP can send to http://127.0.0.1:4318/v1/traces, /v1/logs and /v1/metrics.

4. See the dashboard

Use your tool as usual. The Dashboard shows events, sessions, tokens, cost, errors and p95 latency compared with the previous period, plus activity over time and the top tools, models and projects. Hover any chart for exact values, or switch it to a table.

  • Activity is live: new spans, logs and metrics appear as they arrive. Its Sessions tab lists each tool session with its project, duration, calls, tokens, cost and models.
  • Models ranks the models your tools used by spend, tokens, calls, speed, reliability or cost per million tokens.
  • Destinations forwards everything to the backends you add. See Destinations.

New users get a short guided tour. Replay it from the ? button in the header.

Next steps

Cookie categories

Details: Cookie Policy.