Table of Contents
Configuration
The model is simple: flat keys.
They come from environment variables, or — for the standalone binary — from
appsettings.json next to the executable. Environment wins. setup
generates the file with everything needed, plus the optional keys as empty
placeholders. Containers just use env vars from .env and compose.
The keys that matter
| Key | Default | Purpose |
|---|---|---|
INITIAL_ADMIN_USERNAME / _PASSWORD |
— | First-boot break-glass account (_MUST_CHANGE=1 forces a reset) |
AUTH_FORCE_LOCAL |
— | 1 always shows the built-in sign-in form (lockout recovery) |
PUBLIC_SERVER_URL |
derived | Pin the public base URL for generated commands |
TRUST_PROXY |
1 |
Forwarded-header processing (0 disables) |
TRUSTED_PROXIES / TRUSTED_NETWORKS |
private ranges | Replace the default trust with an allow-list |
TRUSTED_HOSTS |
— | Host-header allow-list (from X-Forwarded-Host) |
FORWARD_LIMIT |
1 |
Chained proxies to walk back (raise for proxy-behind-proxy) |
TLS_SELF_SIGNED |
1 |
Built-in HTTPS with the managed chain (0 opts out) |
TLS_CERT_DIR |
<data>/tls |
PEM location; setting it forces file mode everywhere |
DATA_PATH |
data |
Data root — db, keys, tls at the top; NATS jetstream, resolver and secrets under data/nats |
DATABASE_PROVIDER |
sqlite |
sqlite, postgres, sqlserver |
DATABASE_PATH / DATABASE_CONNECTION_STRING |
data/db/app.db |
Storage |
NATS_URL, NATS_ACCOUNT_SIGNING_SEED, NATS_ACCOUNT_PUBLIC_KEY |
— | Messaging and credential issuing |
S3_* |
— | Bootstrap defaults for file delivery (the Settings UI overrides them) |
DEVICE_ORPHAN_AFTER_DAYS |
30 |
Orphan window |
JOB_HISTORY_LIMIT |
200 |
Newest jobs kept per device (0 disables pruning) |
LOG_DIRECTORY, LOG_RETAIN_FILES, LOG_MAX_BYTES |
— | Serilog rolling files, per role (LOG_PATH is an accepted alias) |
RATE_LIMIT_PER_MINUTE |
10 |
Enrollment/auth limit per client IP |
Log files are named after the running binary — ExecuteR-Server-<date>.log
and ExecuteR-Agent-<date>.log.
The standalone setup also writes NATS_SIDECAR=1, NATS_WS_PROXY,
NATS_MONITOR_URL, AGENT_PACKAGE_PATH, DATA_PATH and Urls. Its NATS
listeners bind to loopback by default; setup --nats-bind <ip> opens them
when an edge proxy on another host must reach NATS directly.
Outbound proxy
All outbound HTTP from the server — S3, OIDC, secrets providers, the
nats-server download — honors the system or environment proxy
(HTTP_PROXY / HTTPS_PROXY / NO_PROXY) and authenticates to it with
the process account's default credentials. No configuration needed; it
simply engages when a proxy is present.
Agents behave the same way, with a ProxyUrl override — see
Agent Deployment.
Databases
SQLite is the zero-config default.
Postgres and SQL Server are selected with DATABASE_PROVIDER plus
DATABASE_CONNECTION_STRING. Each provider carries its own migration set,
and migrations apply automatically at startup.
Authentication
Sign-in methods (Built-In, Local Windows Accounts, LDAP, OIDC) are configured under Settings › Authentication and apply on save, with no restart. Access comes from role bindings: a group bound to a role. Roles grant permissions and can be scoped to device groups.
If an identity provider locks you out, AUTH_FORCE_LOCAL=1 or the
auth-reset CLI gets you back in. See Sign-In and Access.
Secrets and S3
External vaults are configured under Settings → Secrets providers
(Infisical first; the driver interface is pluggable). They feed $Secrets
in scripts.
Settings → S3 powers $Files delivery and optional agent-package
offload. Transfers ride presigned URLs and never touch the control plane.