Docker Compose

The root docker-compose.yml starts 4 core services by default. The OTEL Collector is optional.

Services

Service	Port	Default?	Purpose
`api`	127.0.0.1:8000	Yes	LangSight REST API
`dashboard`	127.0.0.1:3003	Yes	Next.js dashboard
`postgres`	127.0.0.1:5432	Yes	App state: users, projects, configs, alert rules
`clickhouse`	127.0.0.1:8123	Yes	Time-series span storage + reliability analytics
`otel-collector`	4317, 4318	No	OTLP trace receiver — enable with `--profile otel`
`redis`	6379	No	Multi-worker mode — enable with `--profile redis`

All service ports bind to 127.0.0.1 only — they are not accessible from other machines on the network by default. If you need public access, configure a reverse proxy (nginx, Caddy) in front of port 3003. Do not change the bind address directly — this bypasses the authentication layer.

Start the stack

Option A: Quickstart script (recommended)

The quickstart script generates all secrets, writes .env, and starts everything:

git clone https://github.com/LangSight/langsight
cd langsight
./scripts/quickstart.sh

The script prints your login credentials and API key when done:

──────────────────────────────────────────────────────
  LangSight is running!
──────────────────────────────────────────────────────

  Login credentials:
    Email:    [email protected]
    Password: ls-b58e870f8831cf17988c    ← randomly generated

  API Key:    ls_f487cebe9e0fbafe...      ← use this in your agent code

  Services:
    postgres     healthy
    clickhouse   healthy
    api          healthy
    dashboard    healthy
──────────────────────────────────────────────────────

Open http://localhost:3003 and log in. You’re done — skip to Send your first span.

Credentials are saved in .env. If you forget them:

grep LANGSIGHT_ADMIN .env     # login email + password
grep LANGSIGHT_API_KEYS .env  # API key for your agent

Quickstart flags

Flag	What it does
(none)	Start or resume the stack
`--redis`	Also start Redis (required for `LANGSIGHT_WORKERS > 1`)
`--reset`	Wipe all volumes + `.env` and start completely fresh
`--build`	Force-rebuild Docker images

./scripts/quickstart.sh --redis          # start with Redis
./scripts/quickstart.sh --reset          # clean slate
./scripts/quickstart.sh --reset --build  # clean slate + fresh images

Option B: Manual setup

git clone https://github.com/LangSight/langsight
cd langsight
cp .env.example .env

Edit .env and fill in the required values:

All passwords must be at least 12 characters. Generate secrets with:

python3 -c "import secrets; print(secrets.token_hex(32))"

# .env

# ── Core (required) ────────────────────────────────────────────────────────

# API key — your agents use this to send traces.
# Generate: python3 -c "import secrets; print('ls_' + secrets.token_hex(32))"
LANGSIGHT_API_KEYS=ls_your-api-key-here

# JWT signing for dashboard sessions.
# Generate: openssl rand -base64 32
AUTH_SECRET=replace-with-32-char-random-string

# Admin login — created on first startup only.
LANGSIGHT_ADMIN_EMAIL=[email protected]
LANGSIGHT_ADMIN_PASSWORD=your-secure-admin-password   # min 12 characters

# Database passwords — choose strong values.
POSTGRES_PASSWORD=your-secure-postgres-password
CLICKHOUSE_USER=langsight
CLICKHOUSE_PASSWORD=your-secure-clickhouse-password

# That's it — no OTEL tokens needed. The SDK sends traces directly to the API.

docker compose up -d
docker compose ps    # all services should show "healthy"

Open http://localhost:3003 and log in with the email and password from your .env:

grep LANGSIGHT_ADMIN .env

After login you’ll see a “Default” project. It’s empty until you instrument your first agent.

Send your first span

Your agent needs 3 environment variables:

export LANGSIGHT_URL=http://localhost:8000
export LANGSIGHT_API_KEY=ls_your-api-key      # from LANGSIGHT_API_KEYS in .env
export LANGSIGHT_PROJECT_ID=your-project-id   # copy from dashboard Settings > Project ID

Then in your Python code:

import langsight
langsight.auto_patch()   # traces LLM calls, MCP tools, LangGraph, CrewAI — all automatic

That’s it. Run your agent and traces will appear in the dashboard.

auto_patch() sends traces directly to the LangSight API — it does not use the OTEL Collector. The collector is only needed if you have existing OTEL instrumentation you want to forward.

Reverse proxy (public access)

To expose the dashboard over HTTPS, put a reverse proxy in front of port 3003. Example with Caddy:

your-host.example.com {
    reverse_proxy localhost:3003
}

Example with nginx:

server {
    listen 443 ssl;
    server_name your-host.example.com;

    location / {
        proxy_pass http://127.0.0.1:3003;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Never expose the FastAPI port (8000) directly. Only the dashboard (3003) should be public — it enforces authentication before forwarding to the API.

Health and readiness probes

Endpoint	Purpose
`GET /api/liveness`	Instant liveness — returns `{"status": "alive"}` with no I/O
`GET /api/readiness`	Readiness — checks storage connectivity before returning `200`

Upgrade

docker compose pull
docker compose up -d

Volumes

Data persists in named Docker volumes:

Volume	Contains
`clickhouse_data`	Span data, health history, reliability aggregations
`postgres_data`	Users, projects, server configs, alert rules, model pricing

To completely reset (destroys all data):

docker compose down -v
docker compose up -d

Environment variables reference

Required

Variable	Description
`LANGSIGHT_API_KEYS`	API key(s) for authentication. Comma-separated for multiple.
`AUTH_SECRET`	JWT signing secret (min 32 chars)
`LANGSIGHT_ADMIN_EMAIL`	Bootstrap admin email (first run only)
`LANGSIGHT_ADMIN_PASSWORD`	Bootstrap admin password (min 12 chars, first run only)
`POSTGRES_PASSWORD`	PostgreSQL password
`CLICKHOUSE_USER`	ClickHouse username
`CLICKHOUSE_PASSWORD`	ClickHouse password

Security (recommended for production)

Variable	Description
`LANGSIGHT_SECRET_KEY`	Encryption at rest for provider API keys in Postgres
`LANGSIGHT_PROXY_SECRET`	HMAC signing of dashboard → API proxy headers. Must match on both containers.
`LANGSIGHT_DASHBOARD_KEY`	Separate API key for the dashboard proxy (falls back to `LANGSIGHT_API_KEYS`)

Optional

Variable	Default	Description
`LANGSIGHT_LOG_LEVEL`	`INFO`	Log verbosity
`LANGSIGHT_CORS_ORIGINS`	`http://localhost:3003`	CORS allowed origins
`LANGSIGHT_DASHBOARD_URL`	`http://localhost:3003`	Dashboard public URL (used in invite links)
`LANGSIGHT_TRUSTED_HOSTS`	`api`	Extra trusted Host header values (comma-separated)
`LANGSIGHT_STORAGE_MODE`	`dual`	Storage backend: `postgres`, `clickhouse`, or `dual`
`LANGSIGHT_REDACT_PAYLOADS`	`false`	Set `true` to omit span payloads
`LANGSIGHT_SSE_MAX_CLIENTS`	`1000`	Max SSE connections per worker
`LANGSIGHT_MAX_CONCURRENT_TRACE_READS`	`5`	Concurrent session trace reads

Redis (optional — multi-worker mode)

Enable with docker compose --profile redis up -d:

Variable	Description
`REDIS_PASSWORD`	Redis auth password
`LANGSIGHT_REDIS_URL`	`redis://:${REDIS_PASSWORD}@redis:6379`
`LANGSIGHT_WORKERS`	Number of API workers (default: 1)

OTEL Collector (optional)

The OTEL Collector is not started by default. Most users don’t need it — langsight.auto_patch() sends traces directly to the API. Enable it only if you have existing OpenTelemetry instrumentation you want to forward:

# Add OTEL tokens to .env
OTEL_COLLECTOR_TOKEN=$(python3 -c "import secrets; print(secrets.token_hex(32))")
LANGSIGHT_OTEL_COLLECTOR_KEY=ls_your-api-key   # reuse LANGSIGHT_API_KEYS

# Start the collector alongside the main stack
docker compose --profile otel up -d

The two tokens secure the trace pipeline:

Your OTEL SDK  ──►  OTEL Collector  ──►  LangSight API
                    (OTEL_COLLECTOR_TOKEN)  (LANGSIGHT_OTEL_COLLECTOR_KEY)

Variable	Purpose
`OTEL_COLLECTOR_TOKEN`	Bearer token for inbound OTLP connections
`LANGSIGHT_OTEL_COLLECTOR_KEY`	API key the collector uses to forward traces to the API

Troubleshooting

API unhealthy — password authentication failed

Your Postgres volume was initialised with a different password than your current .env. This is the most common failure after deleting .env or running --reset without wiping volumes.

./scripts/quickstart.sh --reset

--reset wipes both the volumes and .env so they’re always in sync. Verify your admin credentials match what’s in .env:

grep LANGSIGHT_ADMIN .env

The admin user is created on first startup only. If you change the password in .env after the first run, the database still has the original password. To reset:

./scripts/quickstart.sh --reset   # wipes volumes + .env and starts fresh

Dashboard can’t reach the API (500 errors)

Check the API is healthy:

docker compose ps          # all services should show "healthy"
docker logs langsight-api  # check for startup errors

OTEL spans not arriving

Only relevant if you’re using OTEL (not auto_patch()). Verify the collector token matches:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $(grep OTEL_COLLECTOR_TOKEN .env | cut -d= -f2)"

Getting Started

CLI Reference

AI Providers

SDK & Integrations

Guides

MCP Monitoring

Agents

Reliability Features

Teams & Access

Self-Hosting

Services

Start the stack

Option A: Quickstart script (recommended)

Quickstart flags

Option B: Manual setup

Send your first span

Reverse proxy (public access)

Health and readiness probes

Upgrade

Volumes

Environment variables reference

Required

Security (recommended for production)

Optional

Redis (optional — multi-worker mode)

OTEL Collector (optional)

Troubleshooting

API unhealthy — password authentication failed

Dashboard can’t reach the API (500 errors)

OTEL spans not arriving

Getting Started

CLI Reference

AI Providers

SDK & Integrations

Guides

MCP Monitoring

Agents

Reliability Features

Teams & Access

Self-Hosting

Documentation Index

​Services

​Start the stack

​Option A: Quickstart script (recommended)

​Quickstart flags

​Option B: Manual setup

​Login

​Send your first span

​Reverse proxy (public access)

​Health and readiness probes

​Upgrade

​Volumes

​Environment variables reference

​Required

​Security (recommended for production)

​Optional

​Redis (optional — multi-worker mode)

​OTEL Collector (optional)

​Troubleshooting

​API unhealthy — password authentication failed

​”Invalid email or password” on login

​Dashboard can’t reach the API (500 errors)

​OTEL spans not arriving

Services

Start the stack

Option A: Quickstart script (recommended)

Quickstart flags

Option B: Manual setup

Login

Send your first span

Reverse proxy (public access)

Health and readiness probes

Upgrade

Volumes

Environment variables reference

Required

Security (recommended for production)

Optional

Redis (optional — multi-worker mode)

OTEL Collector (optional)

Troubleshooting

API unhealthy — password authentication failed

”Invalid email or password” on login

Dashboard can’t reach the API (500 errors)

OTEL spans not arriving