Configuration reference¶
Auto-generated by scanning
crates/{backend,agent}/src/config.rs. Runscripts/docs/regen.pyto refresh.
Configuration comes from environment variables (backend, agent) or CLI flags (gateway). Settings exposed through the UI (organisation heartbeat_timeout_seconds, per-app retention overrides, etc.) live in the database and are not covered here — see the User Guide.
Quick start for a production-ready deployment:
export APP_ENV=production
export JWT_SECRET=$(openssl rand -base64 48)
export DATABASE_URL=postgresql://appcontrol:STRONG_PASS@db.internal:5432/appcontrol
export CORS_ORIGINS=https://appcontrol.example.com
export HA_MODE=true # only if running multiple backend replicas
export LOG_FORMAT=json # for SIEM ingestion
export RETENTION_ACTION_LOG_DAYS=1825 # 5 years — DORA
export RETENTION_CHECK_EVENTS_DAYS=365 # 1 year
Backend¶
Source: crates/backend/src/config.rs. 27 variables.
| Env var | Default | Allowed values | Description |
|---|---|---|---|
APP_ENV |
development |
development |
staging |
CORS_ORIGINS |
(none — unset means feature off / required in production) | https://app.example.com,https://admin.example.com |
Comma-separated list of origins permitted to call the API from a browser. Empty in production logs a warning — cross-origin browser calls will be rejected. |
DATABASE_URL |
(none — unset means feature off / required in production) | postgresql://USER:PASS@HOST:PORT/DB or sqlite:./path/to/file.db |
Postgres or SQLite connection string. Required in production (panics if unset). Default in dev: postgresql://appcontrol:appcontrol@localhost:5432/appcontrol (postgres build) or sqlite:./appcontrol.db (sqlite build). |
DB_CONNECT_TIMEOUT_SECS |
(none — unset means feature off / required in production) | seconds | Maximum time pool.acquire() waits for a free connection before returning a database error. |
DB_IDLE_TIMEOUT_SECS |
(none — unset means feature off / required in production) | seconds | Idle connections are dropped after this many seconds. |
DB_POOL_SIZE |
(none — unset means feature off / required in production) | integer ≥ 1 | Maximum number of database connections in the pool. |
HA_MODE |
(none — unset means feature off / required in production) | true |
false |
JWT_ISSUER |
appcontrol |
string | iss claim written into every issued JWT. |
JWT_SECRET |
(none — unset means feature off / required in production) | ≥32 random chars | HMAC secret for JWT signing. Required in production; panics if shorter than 32 chars or contains dev / change. Generate with openssl rand -base64 48. |
LOG_FORMAT |
text |
text |
json |
PORT |
(none — unset means feature off / required in production) | 1024–65535 | HTTP port the backend listens on. |
PUBLIC_BACKEND_URL |
(none — unset means feature off / required in production) | wss://backend.example.com/ws/gateway |
Public backend URL the frontend uses for the gateway-to-backend WebSocket. Leave unset to derive from window.location. |
PUBLIC_GATEWAY_URL |
(none — unset means feature off / required in production) | wss://gateway.example.com:4443 |
Public WSS URL the frontend embeds in agent-enrollment instructions. Leave unset to derive from window.location.host:4443. |
RATE_LIMIT_AUTH |
(none — unset means feature off / required in production) | integer | Requests per minute on auth endpoints (login, refresh) per source IP. |
RATE_LIMIT_OPERATIONS |
(none — unset means feature off / required in production) | integer | Operations (start / stop / switchover) per minute per user. |
RATE_LIMIT_READS |
(none — unset means feature off / required in production) | integer | Read requests per minute per user — applies to /apps, /components, status endpoints. |
READ_ONLY |
(none — unset means feature off / required in production) | (undocumented — add to scripts/docs/gen_configuration.py::ANNOTATIONS) |
|
RETENTION_ACTION_LOG_DAYS |
(none — unset means feature off / required in production) | days; 0 = unlimited |
Auto-prune action_log rows older than this. 0 keeps everything forever (recommended for DORA-style audit requirements — set to 1825 = 5 years if you must prune). |
RETENTION_CHECK_EVENTS_DAYS |
(none — unset means feature off / required in production) | days; 0 = unlimited |
Drop check_events partitions older than this many days. 0 keeps everything. Partitions are dropped, not deleted row-by-row. |
SEED_ADMIN_DISPLAY_NAME |
(none — unset means feature off / required in production) | string | Display name for the seeded admin. |
SEED_ADMIN_EMAIL |
(none — unset means feature off / required in production) | Email of the seeded admin user. | |
SEED_ADMIN_PASSWORD |
(none — unset means feature off / required in production) | string | Plaintext password of the seeded admin user; bcrypt-hashed before storage. Change it immediately after first login. |
SEED_ENABLED |
(none — unset means feature off / required in production) | true |
false |
SEED_ORG_NAME |
(none — unset means feature off / required in production) | string | Name of the seeded organisation. |
SEED_ORG_SLUG |
default |
lowercase alphanumeric | URL-safe slug for the seeded organisation. |
SHUTDOWN_TIMEOUT_SECS |
(none — unset means feature off / required in production) | seconds | How long the backend waits for in-flight requests to drain on SIGTERM before forcing exit. |
SQLITE_PATH |
(none — unset means feature off / required in production) | absolute or relative path | Path to the SQLite database file. Only consulted when DATABASE_URL is unset and the binary was built with the sqlite feature. |
Agent¶
Agent configuration is read from a YAML file (default location: /etc/appcontrol/agent.yaml on Unix, C:\\ProgramData\\AppControl\\agent.yaml on Windows). Every key can be overridden by an environment variable. The variables below are the env-override surface.
Source: crates/agent/src/config.rs. 12 variables.
| Env var | Default | Allowed values | Description |
|---|---|---|---|
AGENT_ID |
(none — unset means feature off / required in production) | auto |
UUID |
AGENT_MODE |
(none — unset means feature off / required in production) | active |
advisory |
DATA_DIR |
(none — unset means feature off / required in production) | directory path | Where the agent stores its buffer database, enrolment cert, and agent.id. Defaults to /var/lib/appcontrol (Unix) or C:\\ProgramData\\AppControl (Windows). |
GATEWAY_RECONNECT_SECS |
(none — unset means feature off / required in production) | seconds | Sleep between gateway-reconnect attempts. |
GATEWAY_URL |
(none — unset means feature off / required in production) | wss://gateway:4443 |
Single gateway URL. Legacy; prefer GATEWAY_URLS for failover. |
GATEWAY_URLS |
(none — unset means feature off / required in production) | wss://gw1:4443,wss://gw2:4443 |
Comma-separated list of gateway URLs for failover. The agent walks them per the failover_strategy (default ordered) and re-tries the primary every primary_retry_secs. |
PROGRAMDATA |
(none — unset means feature off / required in production) | (undocumented — add to scripts/docs/gen_configuration.py::ANNOTATIONS) |
|
TLS_CA_FILE |
(none — unset means feature off / required in production) | PEM path | CA bundle used to verify the gateway's server cert. |
TLS_CERT_FILE |
(none — unset means feature off / required in production) | PEM path | Agent's client certificate. |
TLS_ENABLED |
(none — unset means feature off / required in production) | true |
false |
TLS_INSECURE |
(none — unset means feature off / required in production) | true |
false |
TLS_KEY_FILE |
(none — unset means feature off / required in production) | PEM path | Agent's client private key. |
Gateway¶
The gateway is configured via CLI flags rather than env vars. The authoritative list is crates/gateway/src/main.rs. The common flags:
| Flag | Default | Description |
|---|---|---|
--bind |
0.0.0.0:4443 |
Address the gateway listens on for inbound agent WebSocket connections. |
--backend-url |
wss://localhost:8080/ws/gateway |
Backend endpoint the gateway dials. |
--cert |
/etc/appcontrol/gateway.crt |
Server certificate presented to agents. |
--key |
/etc/appcontrol/gateway.key |
Server private key. |
--ca |
/etc/appcontrol/ca.crt |
CA bundle used to verify agent client certs (mTLS). |
--name |
hostname | Gateway display name, surfaced in the UI. |
--rate-limit-msgs-per-sec |
200 |
Per-agent inbound message rate limit. |
Run gateway --help against the binary you ship to get the version-specific flag list.
See also¶
- Hardening checklist — every variable that matters for production security
- Production deployment — full Helm + OpenShift recipes
- High availability — the
HA_MODEvariable in context