Configuration reference

Every Lookspan setting can be passed as a CLI flag or an environment variable. Flags win when both are set. An empty default means the feature is off until you set it.

Provider API keys (--openai-key / --anthropic-key / LOOKSPAN_*_API_KEY) are held in memory only — never written to the database or logged. They power Replay and LLM-as-judge and are read on demand.

Server

Flag	Env var	Default	What it does
-p, --port <port>	LOOKSPAN_PORT	3100	Port the ingest API + dashboard listen on.
--host <host>	LOOKSPAN_HOST	127.0.0.1	Address to bind. Use 0.0.0.0 to expose on your LAN; non-loopback binds require --token / LOOKSPAN_TOKEN (see Security).
--db <path|url>	LOOKSPAN_DB	~/.lookspan/lookspan.db	SQLite file (created if missing) or a Postgres connection string (postgres://…). See Postgres.
--retention <dur>	LOOKSPAN_RETENTION	(none)	Prune traces older than <dur> (7d, 24h, 30m). Runs on startup, then at most hourly.
--token <token>	LOOKSPAN_TOKEN	(none)	Require Authorization: Bearer <token> (or the dashboard cookie) on /api/* and /v1/* (/api/health is exempt).
--pricing <file>	LOOKSPAN_PRICING	(built-in table)	Load a custom model pricing table (JSON).
--open	—	false	Open the dashboard in your browser on startup.
—	LOOKSPAN_DASHBOARD_DIR	(auto-detected)	Override the path to the built dashboard assets.

Replay & LLM-as-judge

These only matter if you use Replay / judge. Without a key those endpoints return a clear “no key configured” error and the rest of Lookspan works unchanged.

Flag	Env var	Default	What it does
--openai-key <k>	LOOKSPAN_OPENAI_API_KEY	(none)	OpenAI key for replaying prompts and judging outputs.
--anthropic-key <k>	LOOKSPAN_ANTHROPIC_API_KEY	(none)	Anthropic key for the same.
—	LOOKSPAN_INFERENCE_TIMEOUT_MS	60000	Per-call timeout for replay/judge requests. A hung upstream is aborted.
—	LOOKSPAN_INFERENCE_MAX_RETRIES	1	Provider SDK retries on a failed/timed-out call.

Alerts

See Alerts for the full guide.

Flag	Env var	Default	Fires when…
--alert-error	LOOKSPAN_ALERT_ERROR	off	a trace ends in error.
--alert-cost <usd>	LOOKSPAN_ALERT_COST	off	a trace costs more than <usd>.
--alert-tokens <n>	LOOKSPAN_ALERT_TOKENS	off	a trace exceeds <n> total tokens.
--alert-duration <ms>	LOOKSPAN_ALERT_DURATION	off	a trace takes longer than <ms>.

Examples

# Default: localhost, no auth
npx lookspan

# Keep 14 days of history, require a token, alert on failures and pricey runs
LOOKSPAN_RETENTION=14d LOOKSPAN_TOKEN=secret \
  npx lookspan --alert-error --alert-cost 1.00

# Enable Replay & judge with a tighter 20s provider timeout
LOOKSPAN_OPENAI_API_KEY=sk-… LOOKSPAN_INFERENCE_TIMEOUT_MS=20000 \
  npx lookspan

Postgres

Lookspan is SQLite-first — the default, zero-config store is a single file at ~/.lookspan/lookspan.db, and that is the right choice for the local-first, single-process use case Lookspan is built for.

For teams who want a shared, server-backed store, the storage layer is driver-selectable: pass a Postgres connection string as the database target and Lookspan uses the Postgres driver instead. The driver is chosen automatically from the value — anything starting with postgres:// or postgresql:// selects Postgres; everything else is treated as a SQLite path.

# Flag
npx lookspan --db postgres://lookspan:secret@db.internal:5432/lookspan

# …or env var (equivalent)
LOOKSPAN_DB=postgresql://lookspan:secret@db.internal:5432/lookspan npx lookspan

# Run migrations against Postgres without starting the server
LOOKSPAN_DB=postgres://lookspan:secret@db.internal:5432/lookspan npm run migrate

Both drivers implement the same repository interfaces, schema and migrations (currently v1–v7) for the supported repository operations. The external driver uses a real PostgreSQL server; the API contract is shared, while backend-specific SQL and operational characteristics remain the driver’s responsibility. The connection string selects the driver and is parsed for logging, with the password redacted in startup output.

The Postgres driver connects to the configured external server through a worker-backed pg client. The synchronous repository interface is preserved, while transactions use the same PostgreSQL connection and real server-side BEGIN/COMMIT/ROLLBACK semantics. Data survives Lookspan restarts under the server’s own durability and backup policy.

The in-memory pg-mem dialect harness is internal to the repository tests; production postgres:// traffic never uses it.

To stay on SQLite, do nothing — it remains the default.