Skip to main content
Go from zero to “my first trace in the Observal dashboard” in about five minutes. This assumes you have Docker running. By the end of this guide you will have:
  • The Observal CLI installed
  • An Observal server running locally
  • The CLI logged in as an admin
  • At least one MCP server instrumented
  • A live trace visible in the web UI

1. Install the CLI

No Python required. For alternative install methods, see Installation.
[!NOTE] You need Docker Engine ≥ 24.0 with Compose v2 (docker compose, not docker-compose). Homebrew’s Docker formula is outdated. Install Docker Desktop or use your distro’s upstream packages. Verify with docker version and docker compose version.

2. Start the server

That’s it. The .env.example ships with working defaults. The core services come up: Optional monitoring can be enabled with make up-prometheus or make up-observability. Prometheus listens on http://localhost:9090; Grafana listens on http://localhost:3001 when the Grafana profile is enabled. The API waits for Postgres, ClickHouse, and Redis to pass health checks before starting. Expect 15–30 seconds. Confirm it is up:
Hitting a port conflict? See Self-Hosting → Ports and volumes.

3. Log in

Prompts:
  1. Server URL: press Enter for http://localhost
  2. Login method: pick [E]mail
  3. Email / password: use one of the seeded demo accounts:
Log in as super admin for the fewest restrictions while exploring. Credentials land in ~/.observal/config.json (mode 0600). Check it worked:

4. Discover and instrument your harness

If you already have MCP servers configured in Claude Code, Kiro, Cursor, VS Code, or Copilot, first see what’s there:
Expected output lists detected harnesses, MCP servers, skills, hooks, and agents. MCP commands and remote URLs are shown exactly as configured. scan is read-only: it shows what you have without modifying anything. Install session telemetry hooks:
doctor patch installs supported session hooks and extensions. It does not rewrite MCP configuration. Restart your harness so the hook changes take effect, then begin a coding session.

5. See your first trace

Open http://localhost/traces in your browser. Start a prompt in your harness and let the session complete. Refresh to see the indexed session and its parsed events. Or use the CLI:

6. (Optional) Pull an agent

Browse what the community has published:
Install one into your harness:
This writes agent files, skills, hooks, and direct MCP configs into the right places for your harness.

What you just built

Observal indexes session transcript records into canonical events and aggregates.

Where to next