This guide gets you from zero to a trace appearing in the dashboard in about five minutes. It assumes you have Docker installed and an OpenAI API key handy.

1. Start the self-hosted stack

git clone https://github.com/scopecall/scopecall.git
cd scopecall

# Generate the two required secrets (one-time setup).
cp infra/.env.example infra/.env
echo "AUTH_SECRET=$(openssl rand -hex 32)"      >> infra/.env
echo "INTERNAL_API_KEY=$(openssl rand -hex 32)" >> infra/.env

# Bring up the stack.
docker compose -f infra/docker-compose.yml up -d

Wait ~30 seconds for everything to be healthy:

docker compose -f infra/docker-compose.yml ps

You should see clickhouse, postgres, redpanda, redis, ingest, processor, api, and dashboard all reporting healthy or running.

2. Create your admin account

Open http://localhost:3000/setup and create the first org + admin user. This page only works once — after the first user exists, it redirects to the login screen.

3. Generate an API key

In the dashboard, go to Settings → API Keys → Generate key. Copy the sc_live_... value immediately — ScopeCall only stores a hash, so the dashboard can't show it to you again.

4. Instrument your app

Pick your stack. Both SDKs ship the same wire format, so the dashboard sees identical traces regardless of which one you use.

TypeScript

npm install @scopecall/scopecall-js

import { init } from "@scopecall/scopecall-js";
import OpenAI from "openai";

const sdk = init({
  apiKey: process.env.SCOPECALL_API_KEY!,
  endpoint: "http://localhost:8080/v1/ingest",
});

const openai = new OpenAI();
sdk.instrument(openai);

const response = await openai.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Hello, ScopeCall." }],
});

Python

pip install "scopecall-py[openai]"

import os
import scopecall
from openai import OpenAI

sdk = scopecall.init(
    api_key=os.environ["SCOPECALL_API_KEY"],
    endpoint="http://localhost:8080/v1/ingest",
)

client = sdk.instrument(OpenAI())

with sdk.trace("hello-world", feature_name="demo"):
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Hello, ScopeCall."}],
    )

sdk.flush()

5. See your trace

Open http://localhost:3000/dashboard/traces. Your call appears within a few seconds, with:

The exact prompt and response
Token counts (input / output / cached)
Server-recomputed cost (USD, accurate to the provider's current pricing)
Latency including time-to-first-token for streaming
The feature_name you set on the trace (demo in the Python example)

Next steps

Add a workflow span — wrap multiple LLM calls in sdk.trace("...") to see them chained in the trace tree.
Tag prompt versions — pass promptVersion: "v3" to surface per-version cost / latency / error rate in the Prompts page.
Browse the TypeScript SDK reference or Python SDK reference.
Read the Self-hosting guide before running this in production.