Skip to main content
Two roles use this page: customers signing up at app.tracelane.dev, and operators self-hosting Tracelane.

​
Customer browser flow

  1. Visit app.tracelane.dev/sign-in — the same route handles first-time sign-up and returning sign-in.
  2. Sign in with WorkOS Connect (Google / Microsoft / SAML).
  3. Your first sign-in creates a personal workspace (named <your-email-local-part>'s workspace). Teammates join by invitation only — a workspace owner invites them from Settings → Team — never automatically by email domain.
  4. Pick a plan (Builder $29 / Team $229 / Business $799 / Enterprise from $2,499).
  5. Generate a tenant API key (tlane_<base62>). Copy it once — we hash + store.
  6. Drop it in your env as TRACELANE_API_KEY.
  7. Make a call. The trace shows up at app.tracelane.dev/traces within a second.
You’re done. Predictive guardrails are observe-first: they flag and record findings on the trace rather than blocking the request. The dashboard surfaces what was observed and lets you pin or approve tools; it does not switch a rail into blocking.

​
Operator self-host checklist

Eight steps to running Tracelane on your own infra.
1

Reserve infra

  • Postgres 17 (Neon, RDS, or self-hosted) — tenant + user metadata and the canonical audit ledger
  • ClickHouse 24+ — span storage and the ledger’s read copy (its only home if you skip Postgres). A cold archive (the hot→cold move of aged span parts to S3-compatible object storage) is optional for a self-host: without it, spans stay on the ClickHouse disk. The hosted service tiers spans to Cloudflare R2 and meters it as cold_gb_month. The tiering ALTERs and the storage-policy precondition are documented in infra/dev/clickhouse/migrations/24_bill01_meters_blobs_tiering.sql.
  • L4 GPU pool — optional, only for the roadmap SLM-judge inference tier; not required at V1
  • Outbound network to Sigstore Rekor (rekor.sigstore.dev) — for best-effort, opt-in Rekor v2 anchoring of audit batches; universal per-run anchoring is on the roadmap
2

Set secrets

  • POLAR_ACCESS_TOKEN, POLAR_WEBHOOK_SECRET — billing (Polar.sh)
  • WORKOS_API_KEY, WORKOS_CLIENT_ID, WORKOS_WEBHOOK_SECRET — auth
  • TRACELANE_BYOK_MASTER_KEY — provider-key envelope encryption (32 bytes, base64-encoded; AES-256-GCM via ring)
  • TRACELANE_APIKEY_PEPPER — API-key hashing pepper (release builds refuse to boot without it)
  • CLICKHOUSE_URL, POSTGRES_URL — datastore endpoints. (The gateway and ingest read no object-storage variables; the optional cold archive is configured on the ClickHouse server itself — an S3 disk plus the hot_cold storage policy — not through the gateway’s environment.)
3

Apply migrations

Drizzle is canonical for the control-plane Postgres schema, but its journal (apps/web/db/migrations/meta/_journal.json) covers only migrations 0000–0008, so drizzle-kit migrate would apply those nine and stop. Apply every SQL file in apps/web/db/migrations/ in order with psql before starting the gateway:
scripts/apply-migration-pg.sh runs the same loop against a fresh database and checks that the core tables exist afterwards. The gateway does not apply migrations at boot.
4

Configure WorkOS Connect

In the WorkOS dashboard:
  • Add your domain
  • Configure SAML or OAuth providers
  • Set the redirect URI to your dashboard’s WorkOS callback — the Next.js app handles the SSO callback, not the gateway
  • Add the webhook URL https://gateway.<your-domain>/v1/webhooks/workos
  • Set the webhook events: organization.created, user.created, dsync.user.created
5

Configure Polar

Tracelane v3 pricing requires four monthly base products plus six usage meters. Create each product in the Polar.sh dashboard, with the lookup_key set on each product’s product_metadata:Annual billing is not offered yet: the checkout refuses a yearly interval and the app hides the annual action. Do not create <plan>_v1_year products — the webhook handler treats that lookup key as unknown and changes no plan (apps/web/lib/polar-webhook.ts).Seats are unlimited on every paid tier — Free is capped at one seat, and there is no per-seat product to create.Then:
  • Create the six usage meters with these names: ingest_gb, hot_gb_month, series, scan_units, cold_gb_month, eval_runs
  • Add the Tracelane webhook URL https://<your-dashboard-domain>/api/webhooks/polar
  • Subscribe to events: subscription.created, subscription.updated, subscription.active, subscription.canceled, order.created, order.paid
  • Configure the Polar-hosted customer portal — branding, allowed actions
  • Set POLAR_ACCESS_TOKEN (organization access token), POLAR_WEBHOOK_SECRET, and POLAR_EXPECTED_ORGANIZATION_ID in your env
See the pricing page for the plans, the unlimited seats and the six usage meters. Retention is tier-specific: the indexed window runs 3/30/90/180/365+ days by tier, and queryable history is 30 days on Free and 2 years on every paid tier.
6

Deploy gateway + ingest

7

Deploy dashboard + MCP server

The dashboard is a Next.js app. The MCP server is a separate Node process — run it from source (node apps/mcp/dist/index.js) for local-only use, or run the published package with npx @tracelanedev/mcp (on npm since 2026-09-07).
8

Production checklist

  • Agent-tool safety guards reviewed. They run observe-first — they record findings on the trace and do not block the request.
  • Audit log integrity confirmed (tlane verify <ledger> --tenant-pubkey <base64> returns 0). Without the trusted key it exits INCOMPLETE by design — the hash chain is checked but signatures and anchors are not. The SHA-256 hash chain and Ed25519 per-tenant signing are live; anchored batches carry a resolved Sigstore Rekor v2 inclusion proof (best-effort, opt-in), with universal per-run anchoring on the roadmap.
  • SBOM published — every tagged release carries a Cosign-signed sbom.cyclonedx.json, uploaded as a workflow artifact by CI.
  • Sigstore signing verified on release artifacts (cosign verify-blob against the .cosign.bundle beside each binary, cosign >= 3.0.6) and on the container image (cosign verify on the published image digest).
  • cargo audit and pnpm audit clean on the deployed commit.
  • Back up ClickHouse and Postgres.