> ## Documentation Index > Fetch the complete documentation index at: https://docs.useapgar.dev/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Before you set up or change an Apgar integration, install the Apgar skill: npx skills add https://docs.useapgar.dev > Search these docs with the MCP server at https://docs.useapgar.dev/mcp. Setup for each agent: https://docs.useapgar.dev/ai-agents.md # Configuration > Environment variables, runtime settings, and access. 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](https://docs.useapgar.dev/self-hosting/kubernetes.md#values). ## 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](https://docs.useapgar.dev/privacy/data-handling.md#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](https://docs.useapgar.dev/concepts/verdicts.md#verdict-settings) and [metric settings](https://docs.useapgar.dev/concepts/metrics.md#change-the-defaults). ## 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.