Environment variable reference
Loading rules and the complete self-hosted server, worker, agent, and Connector setting index.
Environment variables configure the self-hosted Infra deployment and its separately run agents. This reference covers every supported Infra deployment variable, including disabled-feature settings, secret-file alternatives, and bundle inputs.
Open the pinned release bundle on the deployment host and edit infra.env.
For Kubernetes, set the corresponding ConfigMap and Secret values in the release
manifests. Inspect effective non-secret values at
Installation settings → Configuration → Effective configuration.
Variable families
- Control plane: listeners, TLS, database pools, workers, HA, licensing, and Compose inputs.
- Access and notifications: sessions, proxy trust, bootstrap authentication, WebAuthn, SMTP, and webhook defaults.
- Persistence and key providers: local paths, object-backed artifacts, backup workers, and external root-secret resolution.
- Observability: collection intervals, retention, logging, Prometheus, and OTLP.
- Node agent and Connector: host identity, management listeners, hardware reserves, mesh, time health, and hosted grants.
Loading and precedence
Choose the configuration source for the process you are changing:
| Configuration | Which value applies |
|---|---|
| Server deployment | Values supplied in the deployment environment override the release bundle's defaults |
| Agent enrollment | Agent environment values override matching supported fields in the enrollment configuration |
| Organization policy | Console settings control organization behavior; they cannot change the deployment identity, database, or root keys |
| Bootstrap authentication | Defaults initialize a new organization; restarting with different defaults does not change an existing organization's policy |
Value syntax and validation
Omitting an optional variable selects its documented default. Omitting a required variable prevents the affected service from starting. An empty value counts as omitted unless the entry explicitly permits an empty list.
Each variable accepts the syntax defined for its type:
| Type | Accepted input |
|---|---|
| Boolean | Exactly true or false |
| Integer | Decimal notation within the entry's inclusive bounds |
| List | Comma-separated entries; surrounding whitespace is removed |
| JSON | Accepted only when the variable entry specifies JSON input |
Invalid values, conflicting secret sources, invalid field combinations, and unknown keys in a service's documented family prevent that service from starting. Values are not clamped or rounded.
Which process reads a setting
Each variable reference names its consuming service. Compose reads bundle inputs; it does not pass them to daemons as runtime settings. The CLI settings are client-only and are not read by server processes.
Secret files
Use a documented _FILE alternative where provided. A secret file must be readable
by the service identity and contain the value only; one final newline is removed.
Supplying both raw and file forms rejects startup. File paths are read at startup;
replacing a file does not imply a live reload unless its service explicitly supports one.
File-only settings, including INFRA_ENCRYPTION_KEY_FILE, TLS keys, license
material, and node identities, require a mounted file. Removing _FILE from a
setting's name does not create a raw-value alternative. Check the variable's
entry before choosing a secret source.
The setup-token path is an output location: the setup utility writes the token there. It is not a file from which a daemon reads an existing secret.
Minimal Compose input
Mount the database URL, session secret, encryption key, and license files at the paths in the example. Set the database URL to the bundle's private database or your external PostgreSQL endpoint before starting the services.
For a proxy-terminated Compose installation, configure these bundle inputs:
INFRA_RELEASE=2026.03
INFRA_PUBLIC_URL=https://infra.example.com
INFRA_DATABASE_URL_FILE=/run/secrets/infra-database-url
INFRA_SESSION_SECRET_FILE=/run/secrets/infra-session-secret
INFRA_ENCRYPTION_KEY_FILE=/run/secrets/infra-encryption-key
INFRA_LICENSE_KEY_FILE=/run/secrets/infra-license
INFRA_STATE_DIR=/var/lib/infra
INFRA_TLS_MODE=proxy
INFRA_HTTP_PUBLISHED_ADDRESS=127.0.0.1
INFRA_HTTP_PUBLISHED_PORT=8080Select the actual pinned release manifest for the installation. The private
database's own image settings are POSTGRES_DB (default infra), POSTGRES_USER
(default infra), and POSTGRES_PASSWORD_FILE (required mounted password).
Those settings initialize the bundled database; changing them does not rotate
an existing PostgreSQL account. Configure the corresponding Infra database URL
consistently.
Proxy and client-only environment
Outbound HTTP and HTTPS clients honor HTTPS_PROXY, HTTP_PROXY, and
comma-separated NO_PROXY. PostgreSQL and node mesh transports do not use these
HTTP proxy settings. Omission uses direct access.
Keep database, management, and internal storage paths outside an external proxy
when those protocols or identities require a direct path. These variables do
not configure trusted incoming forwarded headers.
The CLI uses INFRA_API_URL, INFRA_API_TOKEN, INFRA_ORGANIZATION, and
INFRA_PROJECT. They have no implicit defaults except the active CLI context.
Explicit command flags override environment values; environment values override
stored context. See CLI configuration.
Apply and recover
Restart the affected service after validating the new configuration. Inspect readiness and effective non-secret values before resuming automation. In HA, keep shared identity and encryption settings consistent across replicas.
If a change prevents startup, restore the prior deployment values and persistent secret mounts. Do not generate replacement encryption material to clear a file error; retained credentials need their original decryption keys. See configuration, upgrades, and control-plane backup.