Skip to content

Configuration reference

Auto-generated by scanning crates/{backend,agent}/src/config.rs. Run scripts/docs/regen.py to 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 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