Skip to content
SpanDock

Getting started

SpanDock is a self-hosted observability hub for AI coding tools. 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 (or the -amd64 file for an Intel Mac), drag the app to Applications, and clear the download quarantine flag once:

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

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: one always-on machine that collects telemetry from everyone, stores it and forwards it.
  • Client: a developer machine that reports to a server.
  • Standalone: one machine on its own. Choose this to try SpanDock by yourself.

The answer is saved, and updates never ask again. See Modes for the details, including headless machines and how to change the mode later.

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 and Mistral Vibe.
  • 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.

5. Add your license key

Every install needs a license. A Free license is created for you when you sign up on https://spandock.com.

  1. Sign in at https://spandock.com/dashboard and open Licenses.
  2. Choose Copy key. The key starts with sdkey_..
  3. In SpanDock, open Settings → License on your server (hub) or standalone install and paste the key.

Clients and satellites don't need a key of their own; they get the license state from their hub. See Licensing and activation.

Next steps