Configuration reference

Configuration variables

A complete reference for Probara service, frontend, agent, maintenance, and deployment environment variables, including code defaults and the variables that Docker Compose and Helm actually wire.

24 min read

On this page

How configuration is resolved

Each Go process reads environment variables directly. A code default only applies after the variable reaches the process; Docker Compose and the Helm chart expose smaller, different subsets of the complete runtime surface.

Code default: The value selected by shared/config when the process environment does not contain the variable.
Docker wiring: A variable explicitly listed beneath a service in docker-compose.yml. The root .env file is used for Compose interpolation, but it is not passed wholesale into containers.
Helm wiring: A chart value rendered into a workload environment. The chart has no general extraEnv escape hatch in the current dev state.
Local-process wiring: Defaults exported by scripts/start-local-services.sh before it launches locally built binaries.

Common service variables

Where a table row below says a variable is “not exposed” by a deployment method, it means there is no dedicated Compose declaration or Helm value for it. In Helm, any such variable can still be injected without template changes via extraEnv (all workloads) or <service>.extraEnv — see Helm values. In Compose, add it to the service environment block explicitly.

Variable	Code default / validation	Used by	Deployment notes
`HTTP_PORT`	Required integer; no code default	Every Go service	Required even for scheduler and alerter, whose operational endpoint is normally the metrics listener.
`METRICS_PORT`	Required integer; no code default	Every Go service	Hosts `/healthz`, `/readyz`, and `/metrics` for scheduler, worker, alerter, and the status service.
`LOG_LEVEL`	`info`	Every Go service	Compose and Helm set this explicitly. Use a supported structured logger level such as `debug`, `info`, `warn`, or `error`.
`POSTGRES_URL`	Empty	API, scheduler, worker, alerter, status page, CLIs	Required by API, scheduler, alerter, and status page. Optional for workers; a worker without it cannot run notification or AI-RCA side consumers.
`NATS_URL`	`nats://localhost:4222`	API, scheduler, worker, alerter, status page updates	Scheduler and worker require NATS. API and status live-update paths degrade when it is unavailable; alerter can run synchronous dispatch without it.

API authentication, sessions, and audit

Variable	Code default / validation	Docker / Helm wiring
`ADMIN_JWT_SECRET`	Required; validation only rejects an empty value. Use at least 32 random characters.	Compose ships an insecure hardcoded default and the Helm values ship a placeholder default; override both for production.
`ADMIN_ACCESS_TTL_MINUTES`	`15`; integer	Local-process script sets it. Compose and Helm rely on the code default.
`ADMIN_REFRESH_TTL_DAYS`	`30`; integer	Local-process script sets it. Compose and Helm rely on the code default.
`ADMIN_COOKIE_SECURE`	`false`; boolean	Local-process script sets `false`. Compose and Helm do not expose it; production HTTPS deployments should wire `true`.
`ADMIN_BCRYPT_COST`	`12`; integer	Not exposed by Compose or Helm. Also used by the admin creation CLI.
`AUDIT_RETENTION_DAYS`	`365`; nonnegative integer; `0` keeps records forever	Compose and Helm expose the audit-retention setting; the API owns pruning.

The access cookie is HttpOnly and SameSite=Lax. ADMIN_COOKIE_SECURE controls its Secure attribute. Access and refresh TTL values are only parsed as integers; the loader does not reject zero or negative values, so use deliberate positive settings.

Public URLs and private-location authorization

Variable	Code default / validation	Purpose and caveats
`PUBLIC_BASE_URL`	Empty; surrounding whitespace and trailing slash removed	Externally reachable API origin used in agent installers, push webhooks, and the default OIDC callback. Compose and Helm require it for normal deployment.
`PUBLIC_NATS_URL`	Empty	Broker address embedded in private-location deployment instructions. When deployment information is generated, only `tls://` and `wss://` URLs are accepted; pre-existing URL credentials are rejected.
`NATS_LOCATION_AUTH_ISSUER_SEED`	Empty	Required whenever `PUBLIC_NATS_URL` is nonempty. It must be a NATS account seed for the API-hosted authorization callout.
`WORKER_LOCATION_ID`	Empty or UUID	Pins a worker to one private location. Empty selects the default platform worker fleet.
`LOCATION_CREDENTIAL`	Empty	Required if and only if `WORKER_LOCATION_ID` is set. Generated credentials are URL-safe base64 for 32 random bytes.

OIDC single sign-on

Variable	Default / validation	Description
`OIDC_ENABLED`	`false`; boolean	Enables platform-wide OIDC discovery and login.
`OIDC_ISSUER_URL`	Required when enabled	Issuer URL used for OIDC discovery.
`OIDC_CLIENT_ID`	Required when enabled	Registered OAuth/OIDC client identifier.
`OIDC_CLIENT_SECRET`	Required when enabled	Confidential client secret; store in a secret manager or Kubernetes Secret.
`OIDC_REDIRECT_URL`	Defaults to `PUBLIC_BASE_URL` + `/api/v1/auth/oidc/callback`	Must be supplied explicitly if `PUBLIC_BASE_URL` is empty.
`OIDC_SCOPES`	`openid profile email`	Whitespace-separated scopes. Add `groups` when using OIDC group mappings — many IdPs (Okta among them) only emit the groups claim when the scope is requested.
`OIDC_GROUPS_CLAIM`	`groups`	ID-token claim read for group→role mappings. The mapping rules themselves live in the database (Settings → OIDC group mappings), not in environment variables.
`OIDC_PROVIDER_LABEL`	`SSO`	Human-readable login-provider label.
`OIDC_JIT_PROVISION`	`true`; boolean	Creates a local user record for a valid first-time OIDC identity.
`OIDC_JIT_DEFAULT_ROLE`	`viewer`; one of `admin`, `editor`, `viewer`	Default tenant role for JIT users. Ignored whenever any OIDC group mappings exist — mapped roles replace the JIT defaults entirely.
`OIDC_JIT_DEFAULT_TENANT_ID`	`00000000-0000-0000-0000-000000000001`	Tenant receiving JIT users. The loader does not validate UUID syntax; verify it refers to the intended tenant.

Compose includes development-oriented Dex defaults under its optional profile. Helm exposes the platform OIDC settings and stores the client secret separately. In production, register an exact HTTPS callback and choose the least-privileged JIT role.

Encryption-at-rest keys

Variable	Format	Behavior
`PROBARA_SECRETS_KEY`	Base64 encoding of exactly 32 bytes	Version 1 key for encrypted channel, monitor, location, and AI credentials.
`PROBARA_SECRETS_KEY_V2` … `PROBARA_SECRETS_KEY_V100`	Each is base64 encoding of exactly 32 bytes	Optional rotation keys. The highest configured version encrypts new writes; older keys remain available for decryption.

Generate a 32-byte base key

openssl rand -base64 32

API queues, AI fallback, mesh, and artifacts

Variable	Code default	Use / deployment status
`ALERT_STREAM`	`ALERTS`	Loaded by the API but not used by a current API runtime path.
`ALERT_SUBJECT`	`alerts`	API alert live-update subscriber subject.
`ALERT_CONSUMER_NAME`	`api-alerts`	Loaded but not currently used.
`CHECK_JOB_STREAM`	`CHECK_JOBS`	NATS authorization permissions and job topology. Compose and Helm pass the scheduler stream to API.
`CHECK_JOB_SUBJECT`	`check.jobs`	On-demand check publication. Compose and Helm pass the scheduler/worker subject to API; keep all three aligned.
`CHECK_RESULT_SUBJECT`	`check.results`	Private-location result permission and result contract.
`AI_RCA_SUBJECT`	`ai.rca.jobs`	AI root-cause job publication; must match worker.
`MESH_PROBE_INTERVAL_SECONDS`	`30`; positive integer	Mirrors scheduler cadence so API staleness calculations agree.
`MESH_PROBE_TIMEOUT_SECONDS`	`5`; positive integer	Mirrors scheduler probe timeout.
`SYNTHETIC_BROWSER_ARTIFACTS_DIR`	OS temporary directory + `probara/synthetic-browser-artifacts`	API reads and workers write browser artifacts. Compose shares a volume; Helm currently does not.

Global AI fallback variable	Default / validation	Notes
`LLM_PROVIDER`	`openai_compat`	Accepted runtime providers: `openai_compat` and `openai`.
`LLM_BASE_URL`	Empty	Base endpoint for an OpenAI-compatible provider.
`LLM_API_KEY`	Empty	Provider secret.
`LLM_MODEL`	Empty	Required when a base URL is configured.
`LLM_JSON_MODE`	Empty	Product settings support empty/off, `json_object`, and `json_schema`.
`LLM_MAX_TOKENS`	`1024`; positive integer	Maximum response tokens.
`LLM_TIMEOUT_SECONDS`	`60`; positive integer	Provider request timeout.

These LLM values are an optional global fallback. Tenant-specific AI settings stored in PostgreSQL take precedence. Compose and Helm do not currently inject the fallback variables into API or worker pods. The API derives an AIAnalysisEnabled flag from LLM_BASE_URL, but that flag has no present runtime use.

Scheduler and result-ingest variables

Variable	Code default / validation	Compose / Helm notes
`SCHEDULE_INTERVAL_SECONDS`	`2`; positive integer	Compose and Helm override to `5`.
`SCHEDULER_BATCH_SIZE`	`500`; positive integer	Not exposed by Compose or Helm.
`CHECK_JOB_STREAM`	`CHECK_JOBS`	Compose and Helm override to `check-jobs`.
`CHECK_JOB_SUBJECT`	`check.jobs`	Compose and Helm override to `check.job`.
`CHECK_RESULT_STREAM`	`CHECK_RESULTS`	Not exposed by Compose or Helm.
`CHECK_RESULT_SUBJECT`	`check.results`	Not exposed by Compose or Helm.
`RESULT_INGEST_CONSUMER_NAME`	`result-ingest`	Not exposed by Compose or Helm.
`RESULT_INGEST_CONCURRENCY`	`10`; positive integer	Not exposed by Compose or Helm.
`RESULT_INGEST_ENABLED`	`true`; boolean	Not exposed by Compose or Helm. `false` means worker results are published but not persisted.
`CHECK_JOB_LEGACY_CONSUMERS`	`check-workers,worker`	Comma-separated old filterless durable consumers deleted at scheduler startup.
`RETENTION_CLEANUP_ENABLED`	`true`; boolean	Exposed by Compose and Helm.
`RETENTION_CLEANUP_HOUR_UTC`	`2`; integer 0–23	Exposed by Compose and Helm.
`RETENTION_CLEANUP_BATCH_SIZE`	`5000`; positive integer	Exposed by Compose and Helm.
`RETENTION_CLEANUP_MAX_ROWS_PER_RUN`	`200000`; positive integer	Exposed by Compose and Helm.
`MONITOR_PURGE_ENABLED`	`true`; boolean	Not exposed by Compose or Helm.
`MONITOR_PURGE_INTERVAL_SECONDS`	`30`; positive integer	Not exposed by Compose or Helm.
`MONITOR_PURGE_BATCH_SIZE`	`5000`; positive integer	Not exposed by Compose or Helm.
`MONITOR_PURGE_MAX_ROWS_PER_RUN`	`200000`; positive integer	Not exposed by Compose or Helm.
`MESH_ENABLED`	`true`; boolean	Not exposed by Compose or Helm.
`MESH_PROBE_INTERVAL_SECONDS`	`30`; positive integer	Not exposed by Compose or Helm.
`MESH_PROBE_TIMEOUT_SECONDS`	`5`; positive integer	Not exposed by Compose or Helm.
`MESH_FAILURE_THRESHOLD`	`3`; positive integer	Not exposed by Compose or Helm.
`MESH_SCHEDULE_BATCH_SIZE`	`500`; positive integer	Not exposed by Compose or Helm.

Worker execution and network-policy variables

Variable	Code default / validation	Notes
`WORKER_CONCURRENCY`	`10`; positive integer	Concurrent check-job handlers.
`NATS_CONSUMER_NAME`	`check-workers`	Compose and Helm override to `worker` for the default fleet.
`CHECK_JOB_STREAM`	`CHECK_JOBS`	Must match scheduler.
`CHECK_JOB_SUBJECT`	`check.jobs`	Must match scheduler and API.
`CHECK_RESULT_STREAM`	`CHECK_RESULTS`	Result work-queue stream.
`CHECK_RESULT_SUBJECT`	`check.results`	Result publication subject.
`MAX_HTTP_TIMEOUT_SECONDS`	`30`; integer	Loaded but currently unused outside the configuration object.
`MAX_BODY_SIZE_BYTES`	`1048576`; positive integer	Maximum HTTP response body accepted by the worker.
`HTTP_BLOCK_PRIVATE_IPS`	`false`; boolean	When enabled, blocks private, loopback, link-local, and reserved destinations across networked check types.
`HTTP_ALLOWED_CIDRS`	Empty; comma-separated CIDRs	Narrow exceptions to the block policy. Any invalid CIDR fails startup.
`CHROME_BIN`	Autodetect common Chromium/Chrome names	Override the browser executable. The worker image sets `/usr/bin/chromium-browser`.
`SIP_LOCALHOST_AS_HOST_GATEWAY`	`false`	Truthy values are `1`, `true`, `yes`, and `on`. Compose/local set it for host-gateway development.

Worker AI and asynchronous notifications

Variable	Code default	Notes
`AI_RCA_STREAM`	`AI_RCA`	AI root-cause work-queue stream.
`AI_RCA_SUBJECT`	`ai.rca.jobs`	Must match API.
`AI_RCA_CONSUMER_NAME`	`ai-rca-workers`	Durable AI consumer.
`NOTIFICATIONS_ENABLED`	`false`	Starts the worker notification consumer only when PostgreSQL is also configured.
`NOTIFICATIONS_STREAM`	`NOTIFICATIONS`	Async notification work queue.
`NOTIFICATIONS_SUBJECT_GLOB`	`alerts.dispatch.>`	Subject filter shared with alerter.
`NOTIFICATIONS_CONSUMER_NAME`	`notifications-worker`	Durable dispatch consumer.

The worker uses the same LLM_* and SMTP_* variables documented on this page. Compose wires neither AI, notification, nor SMTP variables into the worker. Helm wires SMTP_* through its smtp values block; AI and notification-mode variables still require extraEnv.

Alerter and SMTP variables

Variable	Code default / validation	Description
`ALERT_STREAM`	`ALERTS`	Alert-event stream.
`ALERT_SUBJECT`	`alerts`	Alert-event subject.
`ALERT_EVAL_INTERVAL_SECONDS`	`30`; positive integer	Current alert-lifecycle evaluation cadence.
`ALERTER_LATENCY_ANOMALY_ENABLED`	`true`; boolean	Enables latency-anomaly evaluation.
`ALERT_REMINDER_INTERVAL_SECONDS`	`3600`; positive integer	Legacy variable used only by the retired alert-evaluation path; current reminders use each tenant’s `alert_reminder_seconds` setting.
`ALERT_GROUP_WINDOW_SECONDS`	`60`; positive integer	Legacy grouping-window variable used only by the retired alert-evaluation path; currently unused.
`ALERT_GROUP_MAX_CHILDREN`	`5`; positive integer	Legacy grouped-child limit used only by the retired alert-evaluation path; currently unused. Current lifecycle handling uses group rollup.
`ALERT_EMAIL_TO`	Empty	Comma-separated fallback recipients for built-in email.
`ALERTER_ASYNC_DISPATCH`	`false`; boolean	Publishes channel dispatch jobs to NATS instead of sending synchronously.
`NOTIFICATIONS_STREAM`	`NOTIFICATIONS`	Must match worker.
`NOTIFICATIONS_SUBJECT_GLOB`	`alerts.dispatch.>`	Must match worker.

The SMTP_* variables are read identically by three services, and each one needs them for a different reason: the alerter delivers alert email from its evaluation loop, the worker delivers it when asynchronous dispatch is enabled, and the API serves POST /api/v1/alert-channels/{id}/test, which runs the same email plugin in-process. An install that sets SMTP only on the alerter delivers alerts correctly but fails every email channel test with mailer not configured. The Helm smtp values block renders the variables into all three at once; set it there rather than in a single service's extraEnv.

SMTP variable	Code default	Important behavior
`SMTP_HOST`	Empty	Required for usable built-in email delivery.
`SMTP_PORT`	`587`	Integer port.
`SMTP_USERNAME`	Empty	Optional SMTP authentication username.
`SMTP_PASSWORD`	Empty	SMTP authentication secret.
`SMTP_FROM`	`SMTP_USERNAME` when empty	Required effective sender address.
`SMTP_FROM_NAME`	`Probara Alerts`	Display name on the From header. The envelope sender stays `SMTP_FROM`.
`SMTP_USE_TLS`	`true`; boolean	`true` selects direct implicit TLS, not STARTTLS. Verify the provider and port pairing.
`APP_BASE_URL`	Empty	Public origin of the operator UI. Adds an "open the monitor" button to alert email; omitted when unset. Read by the same three services.

Status-page and live-update variables

Variable	Code default / validation	Description
`STATUS_PAGE_BASE_URL`	Empty	Public origin of the status service. Supplies the deep link in visitor push notifications; when empty, the notification opens the page via the service worker scope rather than a guessed host.
`STATUS_PAGE_API_BASE_URL`	Empty	Enables the status service’s restricted API reverse proxy.
`STATUS_PAGE_READ_TIMEOUT_SECONDS`	`15`	Invalid or nonpositive input silently falls back to 15 seconds.
`STATUS_PAGE_WRITE_TIMEOUT_SECONDS`	`60`	Invalid or nonpositive input silently falls back to 60 seconds.
`STATUS_PAGE_CACHE_TTL`	`10s` Go duration	Invalid or nonpositive input falls back to 10 seconds.
`STATUS_PAGE_PREVIEW_SECRET`	Empty	HMAC secret shared with API for one-hour preview tokens. With no secret, preview verification is not enforced.
`STATUSPAGE_UPDATES_SUBJECT`	`statuspage.updates`	Core NATS live-invalidation subject shared by API, scheduler, and status service. Also wakes the push sender early; delivery does not depend on it.
`STATUS_PAGE_VAPID_PUBLIC_KEY`	Empty	VAPID application server key for visitor notifications. Published inside every rendered page, so it is not a secret. Generate with `go run ./cmd/admin/gen_vapid_keys`.
`STATUS_PAGE_VAPID_PRIVATE_KEY`	Empty	Signs the push JWT. A credential. Notifications are disabled unless both key halves are set; never generate per process, because replicas would disagree and a restart would invalidate every subscription.
`STATUS_PAGE_VAPID_SUBJECT`	Empty	`mailto:` or `https:` operator contact for the VAPID `sub` claim. Some push services reject a missing or malformed value.
`STATUS_PAGE_PUSH_ENDPOINT_ALLOWLIST`	Google, Mozilla, Microsoft, Apple push hosts	Comma-separated host suffixes a stored push endpoint may use. This is an SSRF control; `*` disables it for a self-hosted push service.
`STATUS_PAGE_PUSH_MAX_SUBSCRIPTIONS_PER_PAGE`	`10000`	Cap on stored subscriptions per status page. Invalid or nonpositive input falls back to the default.
`STATUS_PAGE_TRUSTED_PROXY`	`false`	Honor `X-Forwarded-For` when rate-limiting push subscribes. Off by default because the header is client-settable.

The restricted proxy permits GET under /api/v1/monitors and PATCH under /api/v1/status-pages/…; it is not a general API proxy. Helm currently wires only basic status values and the status base URL, not the API proxy, cache, preview, timeout, or update-subject variables.

Frontend variables

Variable	Default	Runtime behavior
`API_PROXY_TARGET`	`http://localhost:8080`	Server-side destination for `/api` and downloadable agent-binary proxy routes.
`NEXT_PUBLIC_API_URL`	`/api`	Browser API base. Compiled into the Next.js client bundle.
`NEXT_PUBLIC_STATUS_PAGE_URL`	Empty	Status-page link origin; falls back to the current/relative origin or localhost during local use. Compiled into the client bundle.
`NEXT_PUBLIC_DEBUG_INGEST_URL`	Empty	Developer-only debug timing sink. If set, monitor IDs and browser timing events are sent to it.
`NODE_ENV`	Docker image sets `production`	Next.js runtime mode.
`PORT`	Docker image sets `3000`	Next.js listener port.
`HOSTNAME`	Docker image sets `0.0.0.0`	Next.js bind address.

Collector agent settings

The host agent is probara-collector, an OpenTelemetry Collector distribution started as probara-collector --config <path>. Its generated configuration contains no secrets; credentials are supplied through the environment (systemd EnvironmentFile, launchd runner script, or the Windows service registry Environment value).

Environment variable	Default	Description
`PROBARA_API_KEY`	None; required	Tenant write-scope API key sent as the `Authorization: Bearer` header.
`PROBARA_AGENT_ID`	None; required	Agent monitor identifier sent as the `X-Probara-Agent-Id` header.

Maintenance, build, and test variables

Variable	Default / requirement	Command or scope
`MIGRATIONS_PATH`	`./migrations`	`go run ./cmd/migrate`; local workflow supplies `./shared/db/migrations`.
`ADMIN_USERNAME`	Required	`go run ./cmd/admin` administrator upsert.
`ADMIN_PASSWORD`	Required	`go run ./cmd/admin`; do not expose in shell history in production.
`BOOTSTRAP_DB_USER`	`probara`	`scripts/bootstrap-local-db.sh`.
`OCB_VERSION`	`v0.159.0`	`scripts/build-collector.sh`; pinned OpenTelemetry Collector Builder version, must match `collector/manifest.yaml`.
`BUILD_DIR`	`./static/collector`	Output directory for downloadable collector binaries and `checksums.txt`.
`GHCR_OWNER`	Falls back to `GITHUB_REPOSITORY_OWNER`; then required	Helm OCI publication.
`GITHUB_REPOSITORY_OWNER`	GitHub Actions context or shell value	Fallback owner used by Helm OCI publication when `GHCR_OWNER` is empty.
`GHCR_HELM_REPO`	`oci://ghcr.io/<owner>/charts`	Helm OCI destination.
`SEMANTIC_RELEASE_TOKEN`	Required GitHub Actions secret for release workflow	Used as semantic-release, GHCR/Helm registry, `GH_TOKEN`, and `GITHUB_TOKEN` credential. Scope it to the repository/packages required by the workflow.
`API`	`http://localhost:8080`	`scripts/verify-auth.sh`.
`ADMIN_USER`	`admin`	Authentication verification helper.
`ADMIN_PASS`	`change-me`	Authentication verification helper only; never a production default.
`VERIFY_SSO`	`0`	Enable SSO checks in the auth verification helper.
`API_URL`	`http://localhost:8080`	Dependency-graph seed helper.
`TENANT_ID`	Auto-select first tenant when supported	Seed/test helpers.
`API_KEY`	Placeholder in `scripts/test-group-creation.sh`	Test helper credential only; never use a production key in a disposable script shell history.
`WRITE_PREVIEW`	Empty	Test-only flag that writes rendered status preview HTML.

GitHub’s PR_TITLE, PR_BODY, TARGET_BRANCH, GITHUB_OUTPUT, and GITHUB_STEP_SUMMARY variables are workflow-internal inputs for release-preview classification, not product runtime configuration. Docker build workflow values such as REGISTRY and IMAGE_PREFIX are likewise CI-owned defaults.

Deployment wiring summary

Area	Docker Compose	Helm chart
Core ports, DB, NATS, log level	Wired	Wired through values and generated connection URLs
Admin JWT and public API URL	Required interpolation	Required chart validation
OIDC	Development Dex-oriented variables wired	Primary OIDC values and client Secret wired
Encryption keyring	Not wired	Base key wired to API/worker/alerter, but not scheduler; rotation keys not exposed
AI fallback	Not wired	Not wired
SMTP	Not wired	`smtp` values block wired to API, worker, and alerter
Notification dispatch mode	Not wired	Not wired
Scheduler result ingest	Code defaults only	Code defaults only
Scheduler purge and mesh	Code defaults only	Code defaults only
Worker result stream and AI/notification queues	Code defaults only	Code defaults only
Status cache, proxy, preview, timeout, update subject	Preview only; most defaults	Not wired
Browser artifact sharing	Shared volume	No shared volume
Arbitrary extra environment	Requires editing Compose	No `extraEnv`; requires chart template change