Environment variables

This page lists the APP_* environment variables you may want to set that no feature page already explains. Each row was checked against the code that reads it, and each default is the fallback in that code. Variables a feature page documents (for example the APP_INGRESS_* hardening limits in Domains and ingress or the APP_PIPELINE_* settings in Pipelines) stay on those pages. Branding variables (APP_BRAND_*) are in White-labeling.

How to set these

Each process reads these variables once at startup, so a change only takes effect after a restart.

Installed with install.sh: the control plane runs as the levelrail systemd service. The unit file sets only APP_DATA_DIR, APP_HTTP_ADDR, APP_INGRESS_HTTP_ADDR and APP_INGRESS_HTTPS_ADDR itself, with plain Environment= lines and no EnvironmentFile=. Add your own with a drop-in, which survives upgrades:
sudo systemctl edit levelrail
Then add the variables under a [Service] heading and restart:
[Service] Environment=APP_UPDATE_CHECK_INTERVAL=6h Environment=APP_SLOW_REQUEST_THRESHOLD=1s
sudo systemctl restart levelrail
This is the same method Installing uses for APP_ALLOW_INSECURE_LOGIN.
Docker or Compose: pass them with -e NAME=value or an environment: block, as in the examples in Docker.
Node agent: variables marked “agent” below are read by levelrail-agent. Set them on the agent’s container or service, not on the control plane. See Docker and Node provisioning.
Command line client: variables marked “CLI” are read by levelrail-cli in the shell where you run it.

Duration values use Go duration syntax such as 30s, 5m, 1h30m. Most variables fall back to their default when the value is unset or invalid; the exceptions are called out in the tables.

Builds and build cache

The control plane builds images with BuildKit. By default each build starts from whatever cache BuildKit already holds. These variables add a shared cache on top of that. See Build node routing for dedicated build nodes.

Variable	Default	Meaning
`APP_BUILD_CACHE_DIR`	unset (no local cache backend)	Directory for BuildKit’s local cache backend. Builds import from and export to it. Control plane.
`APP_BUILD_CACHE_REGISTRY`	unset	Image reference of a registry cache (for example `registry.example.com/cache`) shared across build nodes. When set, it takes priority over the registry settings saved in the dashboard. Control plane.
`APP_BUILD_CACHE_REGISTRY_INSECURE`	unset (off)	Set to exactly `true` to allow a plain-HTTP or self-signed cache registry. Only applies when `APP_BUILD_CACHE_REGISTRY` is set. Control plane.

Git webhook (single repository mode)

These variables turn on the control plane’s own POST /webhook receiver for a single repository. They are separate from the per-app webhooks and GitHub App flow in Git integrations. The three required variables must all be set. If any is missing, the control plane still starts and logs a webhook not configured warning, and only this receiver is unavailable.

Variable	Default	Meaning
`APP_GIT_REPO_URL`	none, required	Git remote the receiver clones when a push arrives. Control plane.
`APP_WEBHOOK_SECRET`	none, required	Shared secret used to verify the `X-Hub-Signature-256` header on incoming pushes. Control plane.
`APP_IMAGE_REPO`	none, required	Image repository that built images are tagged into. Control plane.
`APP_GIT_BRANCH`	`main`	Only pushes to this branch trigger a deploy. Control plane.
`APP_SPEC_DIR`	`.` (the process working directory)	Directory searched for the app spec file. See App spec reference. Control plane.
`APP_SERVICE_NAME`	the only service in the spec	Which service from the spec to deploy. Required when the spec declares more than one service. Control plane.

GitHub App manifest

Variable	Default	Meaning
`APP_GITHUB_APP_MANIFEST_FILE`	`./github-app-manifest.yaml`	YAML file with `default_permissions` (a map) and `default_events` (a list) that a newly registered GitHub App requests. A missing file means the built-in set: `contents:read`, `metadata:read`, `repository_hooks:write`, `statuses:write`, `deployments:write`, and no events. A file that exists but cannot be parsed stops the load with an error. The relative default resolves against the process working directory, which is the data directory under the installer’s unit. Control plane.

Pipelines and OIDC

The pipeline engine’s own tuning variables are listed in Pipelines. These extra ones cover the scheduler, commit status reporting, and the OIDC token service described in Pipelines OIDC. Non-positive or unparseable values for the duration variables here fall back to the default without a warning.

Variable	Default	Meaning
`APP_PIPELINE_SCHEDULER_INTERVAL`	`30s`	How often the pipeline scheduler runs. Control plane.
`APP_GIT_STATUS_TIMEOUT`	`10s`	Time limit for each commit status post a pipeline run sends to the git forge. Control plane.
`APP_OIDC_KEY_RETIRE_GRACE`	`24h`	How long a rotated-out signing key stays published in the JWKS document before it is removed. Control plane.
`APP_OIDC_JWKS_RATE_LIMIT_PER_MINUTE`	`60`	Rate limit on the unauthenticated JWKS endpoint. Positive integer. Control plane.
`APP_OIDC_TOKEN_REQUEST_PORT`	`9095`	Port of the runtime token request endpoint, bound to the Docker bridge gateway address so only job containers can reach it. Positive integer. Control plane.

Scheduling and background intervals

Each of these sets how often a background loop wakes to check for work. Five-field cron only goes down to one minute, so the one-minute defaults are as short as the two cron-driven schedulers can usefully go.

Variable	Default	Meaning
`APP_BACKUP_SCHEDULER_INTERVAL`	`1m`	How often the database backup scheduler checks for backups whose cron schedule is due. See Backups and storage. Control plane.
`APP_SCHEDULED_TASK_SCHEDULER_INTERVAL`	`1m`	How often the scheduler checks for scheduled tasks that are due. Control plane.
`APP_DEPLOY_APPROVAL_SWEEP_INTERVAL`	`5m`	How often pending deploy approvals are checked against their 24 hour expiry. See Chat deploy approvals. Control plane.
`APP_RESOURCE_RECOMMENDATION_LOOKBACK`	`168h` (7 days)	History window used when computing app resource recommendations. Control plane.

For the invalid-value behavior of the first three, see the note at the end of this page.

Control plane off-box backups

These tune the scheduled off-box copy of the control plane’s own state and its restore drills, described in Control plane backup and Disaster recovery. Values that are unset, unparseable, or not greater than zero use the default. Control plane.

Variable	Default	Meaning
`APP_CONTROL_PLANE_OFFBOX_RETAIN_WEEKLY`	`4`	Number of weekly backups kept. Positive integer.
`APP_CONTROL_PLANE_OFFBOX_RETAIN_MONTHLY`	`6`	Number of monthly backups kept. Positive integer.

Point-in-time restore

Variable	Default	Meaning
`APP_PITR_WAL_SEGMENT_BYTES`	`16777216` (16 MiB)	WAL segment size, in bytes, that the restore path assumes when it maps a base backup’s start position to a segment. Set it only if the Postgres server was initialized with a non-default WAL segment size. Positive integer. Control plane. See Managing databases.

Log archive

The archiver’s other settings are on Log archive. These two bound how much one run does. Positive values only; anything else uses the default. Control plane.

Variable	Default	Meaning
`APP_LOG_ARCHIVE_MAX_WINDOWS_PER_RUN`	`24`	Maximum number of one-hour windows archived in a single scheduled run. Integer.
`APP_LOG_ARCHIVE_MAX_BACKFILL`	`24h`	How far back a run may reach when it catches up on missed windows. Duration.

Data export

How these are used is on Data export. Positive values only; anything else uses the default. Control plane.

Variable	Default	Meaning
`APP_EXPORT_ALLOW_PRIVATE_NETWORKS`	`false`	Let export destinations resolve to private, loopback or link-local addresses, for a Loki or collector on the same host or network. Boolean.
`APP_EXPORT_RESYNC`	`15s`	How often running exporters are reconciled with the configured destinations. Duration.
`APP_EXPORT_QUEUE_LINES`	`10000`	In-memory queue length per log destination. The oldest entries are dropped and counted when it is full. Integer.
`APP_EXPORT_BATCH_LINES`	`200`	Maximum entries per delivered batch. Integer.
`APP_EXPORT_BATCH_BYTES`	`1048576`	Approximate maximum batch size in bytes. Integer.
`APP_EXPORT_FLUSH_INTERVAL`	`2s`	How long a partial batch waits for more entries. Duration.
`APP_EXPORT_MAX_ATTEMPTS`	`4`	Delivery attempts per batch before it is dropped (audit batches are held instead). Integer.
`APP_EXPORT_BACKOFF_BASE`	`500ms`	First retry delay, doubled per attempt with jitter. Duration.
`APP_EXPORT_BACKOFF_MAX`	`15s`	Upper bound for the retry delay. Duration.
`APP_EXPORT_BREAKER_FAILURES`	`5`	Consecutive failed batches that open a destination’s circuit breaker. Integer.
`APP_EXPORT_BREAKER_COOLDOWN`	`60s`	How long an open breaker waits before one trial batch. Duration.
`APP_EXPORT_SEND_TIMEOUT`	`10s`	Timeout of one delivery request. Duration.
`APP_EXPORT_STATUS_INTERVAL`	`5s`	How often delivery counters are saved. Duration.
`APP_EXPORT_AUDIT_INTERVAL`	`10s`	How often the audit log is polled for new rows. Duration.
`APP_EXPORT_AUDIT_BATCH`	`500`	Audit rows per batch and per page of a download. Integer.
`APP_EXPORT_AUDIT_MAX_ROWS`	`1000000`	Maximum rows in one audit log download. Integer.
`APP_EXPORT_METRICS_INTERVAL`	`60s`	Default OTLP metrics push interval. Duration.

Ingress

The edge hardening limits are in Domains and ingress. These two are not listed there. Control plane.

Variable	Default	Meaning
`APP_INGRESS_RETRY_INTERVAL`	`250ms`	Pause between retries when a proxied backend cannot be reached during the `APP_INGRESS_RETRY_WINDOW`. A negative or unparseable value is a startup error, not a silent fallback.
`APP_INGRESS_SOCKET_ACTIVATION`	`auto`	Controls use of sockets inherited from systemd. `auto` uses them if present. `true` (also `1`, `on`) makes missing inherited sockets a startup error. `false` (also `0`, `off`) ignores them. See Surviving a control plane restart.

Certificates and request thresholds

Variable	Default	Meaning
`APP_CERT_EXPIRY_WARNING_WINDOW`	`336h` (14 days)	How close to expiry a certificate must be before it counts as expiring, for both the certificate expiry alert rules and the API. Control plane.
`APP_SLOW_REQUEST_THRESHOLD`	`500ms`	API requests slower than this are logged at Warn level, with a `breakdown` field naming the slowest phases (for example `telemetry_latest=1.2s`). Control plane.
`APP_CRITICAL_REQUEST_THRESHOLD`	`2s`	API requests slower than this are logged at Error level. Control plane.
`APP_DASHBOARD_CACHE_TTL`	`5s`	How long the dashboard’s aggregate reads (app and node resource usage, apps metrics, system status, doctor) are reused between requests. `0` disables the cache. Control plane.
`APP_DASHBOARD_CACHE_STALE`	`1m`	How long past the TTL a cached aggregate may still be served while one background refresh runs. Control plane.

For all of these, a value that does not parse logs a warning and uses the default. For the two request thresholds, zero or a negative duration also means the default.

Doctor and diagnosis

These tune levelrail-cli doctor and the structured diagnosis of failed deploys. See Troubleshooting and Deploy failures.

Variable	Default	Meaning
`APP_DOCTOR_DISK_WARNING_BYTES`	`1073741824` (1 GiB)	Free disk space below which the `disk_space` check warns. Integer bytes. Control plane.
`APP_DOCTOR_MASTER_KEY_ROTATION_WARN_DAYS`	`365`	Age of the master key, in whole days, after which doctor suggests rotating it. See Master key rotation. Control plane.
`APP_DOCTOR_NETWORK_TIMEOUT`	`5s`	Shared time limit for the network checks in the doctor endpoint. Control plane.
`APP_PROXY_VERIFY_TIMEOUT`	`8s`	Time limit for each managed proxy route check (TLS handshake and request through the proxy) and for the DNS checks of the proxy setup checklist. Control plane.
`APP_DOCTOR_PUBLIC_IP_ENDPOINT`	`https://api.ipify.org`	URL that returns the caller’s public IP as plain text, used by the `public_ip` doctor check and by deploy preflight. Control plane.
`APP_DIAGNOSE_PROBE_TIMEOUT`	`4s`	Time limit for each live probe (container state and container logs) when diagnosing an app. Zero or invalid values use the default. Control plane.
`APP_ATTENTION_COPY_FAILURE_DAYS`	`14`	Days a failed data copy stays in the attention feed before it drops to history. Positive integer. Control plane.
`APP_ATTENTION_DIAGNOSE_LIMIT`	`10`	Maximum number of distinct apps `levelrail-cli attention` asks the control plane to diagnose when it marks items as fixable. Integer, `0` skips diagnosis. CLI.

Updates

Variable	Default	Meaning
`APP_UPDATE_CHECK_INTERVAL`	`1h`	How often the control plane checks the configured release channel for a newer version. Control plane.

SSH node provisioning

Variable	Default	Meaning
`APP_SSH_NODE_PROVISION_TIMEOUT`	`10m`	Time limit for installing the agent over SSH, and how long the control plane waits for the new node to enroll before reporting the provision as failed. Zero or invalid values use the default. Control plane. See Node provisioning.

Mesh networking

Variable	Default	Meaning
`APP_MESH_KEY_FILE`	`levelrail-agent-mesh.key` in the same directory as the agent identity file	Path where the agent stores its WireGuard private key. Only used when `APP_MESH_ENABLED=1`. Agent. See Network topology.

Behavior to know about

Scheduler intervals are not range checked. APP_BACKUP_SCHEDULER_INTERVAL, APP_SCHEDULED_TASK_SCHEDULER_INTERVAL, APP_UPDATE_CHECK_INTERVAL and APP_DEPLOY_APPROVAL_SWEEP_INTERVAL use any value that parses as a Go duration, including zero or a negative one. Only an unparseable value falls back to the default. Use a positive duration.
Ingress variables fail closed. Unlike most settings on this page, an invalid APP_INGRESS_* hardening value is returned as an error at startup rather than ignored.

​How to set these

​Builds and build cache

​Git webhook (single repository mode)

​GitHub App manifest

​Pipelines and OIDC

​Scheduling and background intervals

​Control plane off-box backups

​Point-in-time restore

​Log archive

​Data export

​Ingress

​Certificates and request thresholds

​Doctor and diagnosis

​Updates

​SSH node provisioning

​Mesh networking

​Behavior to know about