Configuration

Apgar reads environment variables with the prefix APGAR_ at startup. Settings that change at runtime live in the database and are edited in Settings. In the Compose stack, set them in .env next to the Compose file and apply a change with docker compose up -d; docker compose restart does not read .env again. Compose sets the APGAR_CLICKHOUSE_ variables itself, so values for them in .env have no effect. To use another ClickHouse server, set them in docker-compose.override.yml. With the Helm chart, set them under env in the values, and take secrets from a Secret with envFrom. Apply a change with helm upgrade. The chart sets the APGAR_CLICKHOUSE_ variables, APGAR_SECRET_KEY, APGAR_ADMIN_TOKEN, APGAR_PUBLIC_URL, and APGAR_TRUSTED_PROXY_HOPS from its own values, so set those there and not under env. See Kubernetes.

Required

Variable	Rule
`APGAR_SECRET_KEY`	At least 32 characters. Encrypts connection secrets, signs session cookies, and keys the tool argument hash
`APGAR_ADMIN_TOKEN`	At least 16 characters. Signs in to the UI and authorizes API calls

A process with a missing or short value prints the reason and exits with code 2.

Environment variables

Variable	Default	Notes
`APGAR_CLICKHOUSE_URL`	`http://localhost:8123`	ClickHouse HTTP interface. `https` uses a secure connection
`APGAR_CLICKHOUSE_USER`	`apgar`
`APGAR_CLICKHOUSE_PASSWORD`	empty	Compose reads `CLICKHOUSE_PASSWORD` from `.env` and passes it on. The Helm chart reads it from its Secret
`APGAR_CLICKHOUSE_DATABASE`	`apgar`	Created by `apgar migrate` when missing
`APGAR_CLICKHOUSE_CA_CERT`	unset	Path to the CA certificate that signs the server certificate of an `https` URL, for a private CA
`APGAR_CLICKHOUSE_VERIFY`	`true`	`false` turns off certificate verification. Use it only for a test
`APGAR_SECRET_KEY_PREVIOUS`	unset	The previous secret key during a rotation. See Keys
`APGAR_PUBLIC_URL`	`http://localhost:8080`	Address of the UI as people open it. Used in message links and the exporter snippet. Do not point it at the API port
`APGAR_COOKIE_SECURE`	`false`	Always mark the session cookie `Secure`
`APGAR_TRUSTED_PROXY_HOPS`	`1`	Proxies in front of the API that append to `X-Forwarded-For`, counting the UI’s nginx. The login rate limit reads the address the outermost of them added. Set `2` behind a reverse proxy. `0` ignores the header
`APGAR_API_HOST`	unset	Unset listens on every IPv4 and IPv6 address, or on IPv4 alone where the host has no IPv6
`APGAR_API_PORT`	`8000`
`APGAR_LOG_LEVEL`	`INFO`
`APGAR_MAX_BODY_BYTES`	`33554432`	Largest ingest body. Larger requests get 413
`APGAR_LATE_SPAN_DAYS`	`7`	Spans that started longer ago are late and excluded from evaluations. At least 1
`APGAR_TELEMETRY`	`1`	An integer. `0` turns off the anonymous usage report
`APGAR_TELEMETRY_ENDPOINT`	`https://us.i.posthog.com/i/v0/e/`	URL that receives the usage report
`APGAR_ALLOW_INSECURE_SLACK`	`false`	Development only. Allows Slack URLs outside `https://hooks.slack.com/`

Worker

Variable	Default	Notes
`APGAR_WORKER_INSTANCE_ID`	random	Written into the worker heartbeat. The Helm chart sets the pod name and uid
`APGAR_WORKER_METRICS_PORT`	`8001`	Prometheus endpoint of the worker
`APGAR_WORKER_METRICS_URL`	unset	Read by the API. When set, the API includes the worker’s turn, assembly, and rollup metrics in its own `/metrics`. Compose sets it. The Helm chart does not, and Prometheus scrapes the worker directly
`APGAR_ASSEMBLY_QUIET_SECONDS`	`60`	A trace becomes a turn after this long without new spans, once its span without a parent has arrived
`APGAR_ASSEMBLY_MAX_AGE_SECONDS`	`600`	or once this long has passed since its first span arrived
`APGAR_ASSEMBLY_INTERVAL_SECONDS`	`5`
`APGAR_ROLLUP_INTERVAL_SECONDS`	`300`	Updates release turn counts and last seen times
`APGAR_VERDICT_EARLY_INTERVAL_SECONDS`	`300`	Evaluation interval in the first 2 hours of a release
`APGAR_VERDICT_INTERVAL_SECONDS`	`900`	Evaluation interval after that
`APGAR_REQUESTS_INTERVAL_SECONDS`	`5`	Poll interval for work queued from the UI
`APGAR_LANGFUSE_SYNC_INTERVAL_SECONDS`	`60`
`APGAR_EVALUATOR_PROCESSES`	Available CPUs minus 1, at least 1	Processes for the bootstrap. A container counts at most its CPU limit, rounded up
`APGAR_BOOTSTRAP_RESAMPLES`	`10000`	Resamples per evaluation
`APGAR_BOOTSTRAP_CHUNK`	`256`	Resamples per batch

Runtime settings

Retention

Settings, General controls how long data is kept, in days:

Setting	Default	Range	Covers
`trace_data_days`	90	21 to 3650	Spans, turns, and tool calls
`verdict_history_days`	400	`trace_data_days` to 3650	Evaluations and notifications

The minimum of 21 days covers the 7 day baseline before a release, up to 7 days of monitoring, and 7 more days of conversation history. Verdict history cannot be shorter than trace data, because it is the record that remains after traces are deleted. Release rows and release events are never deleted by retention. A release whose traces have left retention cannot be evaluated again. A daily job applies the values.

Other settings

General: turn the usage report on or off. APGAR_TELEMETRY=0 wins over this toggle. One Save applies it together with the retention values.
Agents: per agent verdict rules and metric settings.

Access

The UI signs in with APGAR_ADMIN_TOKEN and keeps a session cookie, apgar_session, for 24 hours. The cookie is HttpOnly and SameSite=Strict, and Secure when APGAR_COOKIE_SECURE is true or the request arrives with X-Forwarded-Proto: https. Ten failed sign ins from one address within a minute return 429 until the minute has passed. The API under /api/v1 serves the UI. It is not a stable public interface. It accepts the session cookie or Authorization: Bearer APGAR_ADMIN_TOKEN. A request authorized by the cookie that is not GET or HEAD must also carry X-Apgar-Request: 1, which the UI adds; a bearer token needs no extra header. Ingest tokens work only on /v1/traces. Rotating APGAR_SECRET_KEY signs out every session. The admin token is independent of the secret key; change it by setting a new value and restarting.

Get started

Send traces

Concepts

Notifications

Self hosting

Data and privacy

Configuration

Required

Environment variables

Worker

Runtime settings

Retention

Other settings

Access

​Required

​Environment variables

​Worker

​Runtime settings

​Retention

​Other settings

​Access

Required

Environment variables

Worker

Runtime settings

Retention

Other settings

Access