Docs Reference

Environment variables

Every environment variable the SDKs, the server and a self-hosted deployment read, and where each is read.

To check an .env you already have, paste it below: any name Runback does not read is flagged, with the closest name it does.

Check an .env

Paste an .env. Only the names are read; this page sends nothing anywhere.

4 variables

1 unread.

An unread variable fails nothing. It does nothing, silently.

ReadRUNBACK_API_KEY read by the SDKs, the server and a self-hosted install
ReadRUNBACK_INGEST_URL read by the SDKs and a self-hosted install
UnreadRUNBACK_SELF_HOSTD nothing reads this. Did you mean RUNBACK_SELF_HOSTED?
ReadOTEL_EXPORTER_OTLP_TRACES_ENDPOINT read by your OpenTelemetry exporter

In your application (7)

Set where your agent runs, for the SDKs and for OpenTelemetry. On runback.dev, RUNBACK_API_KEY is the only one you need.

Variable	What it does
`GIT_SHA`	Optional. A version or commit for your agent, recorded on each run so you can tell which build produced it.
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	Standard OpenTelemetry variable: where the exporter sends traces. For Runback, `https://runback.dev/api/otel/v1/traces`.
`OTEL_EXPORTER_OTLP_TRACES_HEADERS`	Standard OpenTelemetry variable: headers sent with each export. For Runback, `authorization=Bearer` followed by your key.
`RUNBACK_API_KEY`	Your Runback key. The SDKs and the test script send runs with it; create one in Settings › Keys and access › API key. A runback.dev key starts `rb_cloud_`.
`RUNBACK_GATEWAY_TOKEN`	The token your agents present to the Runback gateway instead of the provider key, so the real key never leaves the gateway.
`RUNBACK_GATEWAY_UPSTREAM_KEY`	The provider's real authorization header (for example Bearer sk-...) that the gateway adds when it forwards a call. Only the gateway holds it.
`RUNBACK_INGEST_URL`	Where the SDKs send runs. Not needed with a runback.dev key (`rb_cloud_`), which sends to runback.dev; set it to your server's URL when you self-host.

Self-host: required (7)

A self-hosted install will not start without these. Set them in .env; Self‑host shows how to generate each.

Variable	What it does
`AUDIT_SIGNING_KEY`	The HMAC key that signs audit records, audit-log checkpoints and agent hand-off attestations. Generate it with `openssl rand -hex 32`; the verifier also reads it to check older HMAC-signed records.
`AUTHENTICATOR_PASSWORD`	The password of the database role PostgREST connects as, kept separate from `POSTGRES_PASSWORD`. Generate it with `openssl rand -hex 32`.
`CRON_SECRET`	The secret scheduled jobs present as a Bearer token. Generate it with `openssl rand -hex 32`.
`JWT_SECRET`	The secret PostgREST tokens are signed with; it also turns on database-enforced workspace isolation. Generate it with `openssl rand -hex 32`, and regenerate `SUPABASE_ANON_KEY` and `SUPABASE_SERVICE_ROLE_KEY` whenever it changes.
`NEXT_PUBLIC_APP_URL`	The exact address people open Runback at, with no trailing slash, for example `https://ai.yourcompany.com`. Sign-in links, webhook callbacks and audit links use it.
`POSTGRES_PASSWORD`	The bundled Postgres superuser's password. Never leave it blank outside development.
`SUPABASE_SERVICE_ROLE_KEY`	The service-role token the server uses for its own database access, signed with `JWT_SECRET`. Server-side only; never expose it to a browser.

Self-host: bundled database (11)

Set inside docker-compose.yml from your other values; you rarely change these.

Variable	What it does
`DATABASE_URL`	The Postgres connection string the migration runner uses.
`NEXT_PUBLIC_SUPABASE_ANON_KEY`	Set by `docker-compose.yml` from `SUPABASE_ANON_KEY`. You do not set it yourself.
`NEXT_PUBLIC_SUPABASE_URL`	Set by `docker-compose.yml` to the bundled database API (`http://proxy:8000`). You do not set it yourself.
`PGRST_DB_ANON_ROLE`	Set inside `docker-compose.yml` for the bundled PostgREST service, from your other values. You do not set it yourself.
`PGRST_DB_MAX_ROWS`	Set inside `docker-compose.yml` for the bundled PostgREST service, from your other values. You do not set it yourself.
`PGRST_DB_SCHEMAS`	Set inside `docker-compose.yml` for the bundled PostgREST service, from your other values. You do not set it yourself.
`PGRST_DB_URI`	Set inside `docker-compose.yml` for the bundled PostgREST service, from your other values. You do not set it yourself.
`PGRST_JWT_SECRET`	Set inside `docker-compose.yml` for the bundled PostgREST service, from your other values. You do not set it yourself.
`POSTGRES_DB`	The bundled Postgres database's name.
`POSTGRES_USER`	The bundled Postgres database's user.
`SUPABASE_JWT_SECRET`	Set by `docker-compose.yml` from `JWT_SECRET`, so the app can mint the per-workspace database tokens PostgREST checks. You do not set it yourself.

Self-host: encryption and isolation (7)

Keys that encrypt the credentials the server stores, and the token that turns on database-enforced workspace isolation.

Variable	What it does
`ALERT_SECRET_KEY`	Encrypts each alert rule's signing secret and PagerDuty or Opsgenie key. Falls back to `MODEL_KEY_SECRET`; with neither set, those alert rules cannot be created.
`MODEL_KEY_SECRET`	Encrypts the model provider keys a workspace stores in Settings › Keys and access › Model provider keys. Keep it different from `AUDIT_SIGNING_KEY`; generate it with `openssl rand -hex 32`.
`SIEM_SECRET_KEY`	Encrypts the collector token used to forward the admin audit log to Splunk or Sentinel. Needed only if you forward it; generate it with `openssl rand -hex 32`.
`SSO_SECRET_KEY`	Encrypts each workspace's single sign-on client secret. Needed only if you use single sign-on; generate it with `openssl rand -hex 32`.
`SUPABASE_ANON_KEY`	The anonymous-role token, signed with `JWT_SECRET`. Set it: without it, database-enforced workspace isolation is off and only the app's own checks separate workspaces.
`UNSUBSCRIBE_SECRET`	Signs unsubscribe links so they cannot be forged. Falls back to `AUDIT_SIGNING_KEY`.
`WORKFLOW_SECRET_KEY`	Encrypts the ServiceNow, Jira or PagerDuty credential findings are raised with. Falls back to `MODEL_KEY_SECRET`; generate it with `openssl rand -hex 32`.

Self-host: signing and evidence (6)

The keys that sign the audit record and checkpoints, and how they are timestamped.

Variable	What it does
`AUDIT_ED25519_PRIVATE_KEY`	Recommended. An Ed25519 private key (the whole PEM file) that signs audit records so anyone can verify them offline against your public key. Without it, records are signed with the HMAC key.
`AUDIT_ED25519_PRIVATE_KEY_PREVIOUS`	While you rotate the Ed25519 key, the outgoing private key, so checkpoints signed under it still verify. Clear it once they have been signed again.
`AUDIT_ED25519_PUBLIC_KEY`	Set only when the private key lives elsewhere, such as an HSM. Otherwise the public key is derived from `AUDIT_ED25519_PRIVATE_KEY` and served at `/.well-known/runback-audit-key.pem`.
`AUDIT_ED25519_PUBLIC_KEY_PREVIOUS`	While you rotate the Ed25519 key, the outgoing public key, so records signed before the rotation still verify.
`AUDIT_SIGNING_KEY_PREVIOUS`	While you rotate `AUDIT_SIGNING_KEY`, the outgoing key. Verification accepts both, so checkpoints signed under the old key still read as Intact; clear it once they have been signed again.
`RUNBACK_TSA_URLS`	Your own RFC 3161 timestamp authority, comma-separated if more than one. Unset, each audit-log checkpoint is timestamped by two public authorities, which an air-gapped network cannot reach.

Self-host: models and replay (8)

The model providers Runback itself calls (replay, evals), and where those calls go.

Variable	What it does
`ANTHROPIC_API_KEY`	The server's own Anthropic key, used only when Runback itself calls a model: live replay from a step, and eval judges.
`GROQ_API_KEY`	The server's own Groq key, used only when Runback itself calls a model: live replay from a step, and eval judges.
`OPENAI_API_KEY`	The server's own OpenAI key, used only when Runback itself calls a model: live replay from a step, and eval judges. Your agents keep their own keys.
`RUNBACK_ANTHROPIC_BASE_URL`	Send replay's Anthropic calls to an internal or proxied endpoint instead of `api.anthropic.com`.
`RUNBACK_EXTRA_REPLAY_MODELS`	Extra model ids replay may call, comma-separated, added to the built-in list.
`RUNBACK_GROQ_BASE_URL`	Send replay's Groq calls to an internal or proxied endpoint instead of `api.groq.com`.
`RUNBACK_OPENAI_BASE_URL`	Send replay's OpenAI calls to your own OpenAI-compatible endpoint (vLLM, Ollama, LiteLLM, Azure OpenAI) instead of `api.openai.com`, for example `http://vllm.internal:8000/v1`.
`RUNBACK_REPLAY_MODELS`	The model ids replay may call, comma-separated, replacing the built-in list. Read from the environment only, so a request can never extend it.

Self-host: email (4)

How Runback sends sign-in links, invitations and alerts.

Variable	What it does
`LEAD_NOTIFY_FROM`	The sender address on the email Runback sends, for example `Runback <hello@your-domain>`.Default: `Runback <onboarding@resend.dev>`
`RESEND_API_KEY`	A Resend key for sign-in links and alert email. Without it the server runs, but sends no email.
`RUNBACK_SMTP_URL`	Send email through your own SMTP relay, for example `smtp://user:pass@relay.internal:587`. Wins over `RESEND_API_KEY` when both are set.
`SUPPORT_EMAIL`	The reply-to address shown in email to your users.Default: `hello@runback.dev`

Self-host: operational alerts (7)

How the server tells you about its own faults.

Variable	What it does
`OPS_ALERT_CHANNEL`	How `OPS_ALERT_TARGET` is delivered: `webhook` (the default), `slack`, `teams`, `pagerduty` or `opsgenie`.
`OPS_ALERT_EMAIL`	Where the server emails its own new production faults. Needs `RESEND_API_KEY` or `RUNBACK_SMTP_URL`.
`OPS_ALERT_ROUTING_KEY`	The PagerDuty routing key or Opsgenie API key for operational alerts.
`OPS_ALERT_SIGNING_SECRET`	The secret that signs operational alert webhooks, the same way workspace alerts are signed.
`OPS_ALERT_TARGET`	Where the server pages you when audit-log signing falls more than two minutes behind: a webhook, Slack or Teams URL, or a PagerDuty or Opsgenie host. Unset, the page goes to `OPS_ALERT_WEBHOOK`.
`OPS_ALERT_WEBHOOK`	Where the server posts its own operational alerts, such as an error digest. Optional.
`SLACK_WEBHOOK_URL`	Optional. A Slack webhook the server posts to when its shared rate-limit store is unavailable.

Self-host: licence, network and demo (8)

Your licence, which private addresses the server may reach, and demo mode.

Variable	What it does
`RUNBACK_ALLOW_PRIVATE_TARGETS`	Whether alert webhooks, SIEM collectors and single sign-on may reach private network addresses. Allowed by default when self-hosted; set `false` to refuse them.
`RUNBACK_DEMO_EMAILS`	Accounts that are always simulated and loaded with sample data at sign-in, comma-separated, even on a real install.Default: `demo@runback.dev`
`RUNBACK_DEMO_MODE`	Set to `1` to make the whole install a demo: replay and evals return simulated results and never call a model. Leave it empty for real use.
`RUNBACK_LICENSE`	Your Enterprise licence token. Leave it empty for the free Community plan.
`RUNBACK_SELF_HOSTED`	Set to `1` by `docker-compose.yml` on every self-hosted install. Never set it on a hosted deployment.
`RUNBACK_SHOWCASE`	Shows one workspace's runs on the public demo pages without signing in. Defaults to `RUNBACK_DEMO_MODE`.
`RUNBACK_SHOWCASE_ORG`	The one workspace whose runs may be shown without signing in, on the public demo pages. Leave it unset on a private deployment.
`SMOKE_TEST_KEY`	An existing key the self-host smoke-test script reuses instead of creating one.

Self-host: billing (7)

Optional: the in-app upgrade flow.

Variable	What it does
`LEMONSQUEEZY_API_KEY`	Optional billing: your Lemon Squeezy key, so the in-app upgrade takes payment. Unset, upgrading links to a conversation instead.
`LEMONSQUEEZY_STORE_ID`	Optional billing: your Lemon Squeezy store, for the in-app upgrade flow.
`LEMONSQUEEZY_VARIANT_GROWTH`	Optional billing: the Lemon Squeezy product variant for the Growth plan.
`LEMONSQUEEZY_VARIANT_PRO`	Optional billing: the Lemon Squeezy product variant for the Pro plan.
`LEMONSQUEEZY_VARIANT_SCALE`	Optional billing: the Lemon Squeezy product variant for the Scale plan.
`LEMONSQUEEZY_VARIANT_STARTER`	Optional billing: the Lemon Squeezy product variant for the Starter plan.
`LEMONSQUEEZY_WEBHOOK_SECRET`	Optional billing: verifies Lemon Squeezy's webhooks.