7
Configuration
Alphaeus Mote edited this page 2026-10-23 11:52:18 -04:00
This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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.