Configuration

Configuration

Vantyr is configured entirely through environment variables (Docker Compose / .env). This page is the complete, grouped reference for every variable the server reads.

Getting started: copy .env.example to .env, set the two required secrets (POSTGRES_PASSWORD and ADMIN_PASSWORD), then docker compose up -d (see Deployment). Everything else has a safe default. For a long, copy-pasteable .env block (advanced / non-Compose), see Environment template.

Secret files (*_FILE): every variable resolved through read_env_or_file can instead be read from a file by appending _FILE and pointing it at a path (Docker/Compose secrets). The file's contents are used verbatim (trimmed). For example:

ADMIN_PASSWORD_FILE=/run/secrets/admin_password
DATABASE_URL_FILE=/run/secrets/database_url
OIDC_CLIENT_SECRET_FILE=/run/secrets/oidc_client_secret

Variables that support the _FILE variant are marked _FILE in the tables below. OIDC, Home Assistant, and the alert notification-channel variables are read with plain env::var and do not currently support _FILE.

Ground truth: validated listener/pool/retention/metrics/rate-limit settings live in server/src/config.rs (ServerConfig::from_env, fail-fast). Bootstrap admin, remote-script switch, scheduler timezone, integration token, OIDC, and mDNS are wired in server/src/main.rs, oidc.rs, and mdns_broadcast.rs. Alert notification channels are each a module under server/src/notify/ (registered in NotifyHub::from_env).

HIGH-RISK variables are flagged with ⚠️ - they relax security defaults and should stay at their defaults unless you understand the consequences.

---

Required

Variable	Default	Description	Notes
POSTGRES_PASSWORD	(required)	Postgres password; Compose builds DATABASE_URL from the POSTGRES_* vars.	Generate with openssl rand -base64 24. _FILE
ADMIN_PASSWORD	(required in release)	Bootstrap admin password for the first dashboard user (created only when the DB has zero users).	Server refuses to start in release builds without this (or UI_PASSWORD). _FILE

---

Database

Variable	Default	Description	Notes
POSTGRES_DB	monitor	Database name used by the bundled Compose Postgres.	Compose only.
POSTGRES_USER	monitor	Database user used by the bundled Compose Postgres.	Compose only.
DATABASE_URL	postgres://monitor:monitor@localhost:5432/monitor	Full PostgreSQL connection string. Must start with postgres:// or postgresql:// (validated; fail-fast).	Set directly only when not using the bundled Compose Postgres. _FILE

---

Admin bootstrap

Variable	Default	Description	Notes
ADMIN_USERNAME	admin	Username for the bootstrap admin (only when there are zero dashboard users).	_FILE
UI_PASSWORD	(unset)	Legacy alias for ADMIN_PASSWORD; used only when ADMIN_PASSWORD is unset.	Prefer ADMIN_PASSWORD for new deployments. _FILE
ALLOW_INSECURE_DASHBOARD_OPEN ⚠️	false	If true, lets the dashboard run with no users at all (no bootstrap password required).	HIGH RISK - leave unset. _FILE

After bootstrap, all users live in Postgres. Changing these vars does not reset existing users.

---

Listener / static / pool

Variable	Default	Description	Notes
LISTEN_ADDR	0.0.0.0:9000	Bind address for HTTP + WebSocket. Parsed as a socket address (fail-fast).	_FILE
STATIC_DIR	./static	Directory of the built dashboard SPA.	Docker image sets this to /app/static. _FILE
POOL_MAX_CONNECTIONS	20	SQLx connection pool size. Validated to 1–200 (fail-fast).	_FILE
PUBLIC_BASE_URL	(unset)	Absolute base URL of this server. Used for mDNS advertisement, OIDC redirects, and external deep links (e.g. Home Assistant payloads).	Use a LAN/internet-reachable host, not localhost. _FILE

---

Security · TLS / cookies / CORS / proxy

Variable	Default	Description	Notes
ENFORCE_HTTPS	true (in code)	When true, all requests except /healthz, /readyz, /metrics must arrive with X-Forwarded-Proto: https (or wss), else 426 Upgrade Required.	.env.example ships false so the plain-HTTP quick start works. Put Vantyr behind a TLS-terminating proxy that forwards X-Forwarded-Proto, then set true.
COOKIE_SECURE	(auto)	Forces the session cookie's Secure flag on. Otherwise auto-detected from TLS / X-Forwarded-Proto: https.	Don't force true on plain HTTP - the browser will drop the cookie.
CORS_ORIGINS	(empty)	Comma-separated browser origins allowed to call the API. Empty = no CORS headers emitted (same-origin only).	Set explicitly in production, e.g. https://dashboard.example.com. Enables credentialed CORS for the listed origins.
TRUSTED_PROXY_CIDRS	(empty)	Comma-separated CIDRs/IPs of reverse proxies whose X-Forwarded-For / X-Real-IP / X-Forwarded-Proto are trusted for login rate limiting and lockout. Empty trusts nobody and keys on the direct TCP peer. Invalid entries fail-fast.	Set this when behind nginx/Caddy/Traefik, e.g. 10.0.0.0/8,172.16.0.0/12. _FILE

See Security for the full hardening checklist.

---

Data retention (background prune job)

The retention task periodically prunes auxiliary tables. Per-agent / global telemetry retention is configured in the dashboard, not here.

Variable	Default	Description	Notes
RETENTION_INTERVAL_SECS	3600	How often the prune task runs (seconds). Minimum 60 (fail-fast).	_FILE
ALERT_EVENT_RETENTION_DAYS	(unset = keep forever)	Delete alert_rule_events older than N days. Also reclaims alert screenshot blobs via FK cascade. Must be ≥ 1 when set.	_FILE
SOFTWARE_INVENTORY_RETENTION_DAYS	(unset = keep forever)	Delete agent_software rows by captured_at older than N days. Must be ≥ 1 when set.	_FILE
SCRIPT_EXECUTION_RETENTION_DAYS	90	Delete scheduled_script_executions rows older than N days. This append-only table prunes by default; set 0 to keep forever. Must be ≥ 0.	_FILE
METRICS_RETENTION_DAYS	90	Delete agent_metrics (CPU/mem/disk health history, ~1 sample/min/agent) older than N days. Append-only; set 0 to keep forever. Must be ≥ 0.	_FILE

---

Remote script execution

Variable	Default	Description	Notes
ALLOW_REMOTE_SCRIPT_EXECUTION ⚠️	false	Master kill-switch for running PowerShell/cmd on agents from the dashboard (ad-hoc runs, scheduled scripts, manual "run now").	HIGH RISK - enabling allows remote code execution on every connected endpoint. Default off. _FILE

---

Scheduler

Variable	Default	Description	Notes
SCHEDULER_TIMEZONE	UTC	IANA timezone for evaluating scheduled-script / app-block / internet-block fire times, e.g. Asia/Kuala_Lumpur. Parsed with chrono-tz; falls back to UTC if unparseable.	_FILE

---

Rate limiting

Variable	Default	Description	Notes
API_RATE_LIMIT_PER_SECOND	0 (off)	Max requests/second per client IP across dashboard + API. 0 disables.	Suggested 50–200 in production. _FILE
WOL_MIN_INTERVAL_SECS	15	Minimum seconds between Wake-on-LAN packets per agent. 0 disables the throttle.

Per-IP keying for rate limiting respects TRUSTED_PROXY_CIDRS (see Security above).

---

Observability / logging

Variable	Default	Description	Notes
METRICS_ENABLED	true	Expose Prometheus metrics at GET /metrics.	Endpoint is exempt from ENFORCE_HTTPS. _FILE
LOG_JSON	false	Emit logs as JSON lines (Loki/ELK). false = compact human-readable.	_FILE
RUST_LOG	info	tracing-subscriber log filter, e.g. info,vantyr_server=debug.
EXPOSE_INTERNAL_ERRORS ⚠️	false	If true, JSON 500 responses include internal error detail.	HIGH RISK - debugging only; never in production.
NO_COLOR	(unset)	If set, disables ANSI color in logs.
LOG_FORCE_COLOR	(unset)	1/true forces ANSI color even when stderr is not a TTY (e.g. Docker).

Health endpoints: /healthz, /readyz, /metrics - all exempt from ENFORCE_HTTPS.

---

OIDC / SSO (optional)

Set the four core values to enable "Sign in with SSO" (Authorization Code flow). See OIDC for IdP setup. These read with plain env::var (OIDC_CLIENT_SECRET additionally supports _FILE).

Variable	Default	Description	Notes
OIDC_ISSUER_URL	(unset)	IdP issuer URL (discovery base). Required to enable OIDC.
OIDC_CLIENT_ID	(unset)	OAuth client ID. Required.
OIDC_CLIENT_SECRET	(unset)	OAuth client secret. Required.	_FILE
OIDC_REDIRECT_URL	(unset)	Callback URL, e.g. https://vantyr.example.com/api/auth/oidc/callback. Required.
OIDC_SCOPES	openid profile email	Space-separated scopes requested.
OIDC_ADMIN_GROUP	(unset)	IdP group claim that maps a login to the admin role.
OIDC_OPERATOR_GROUP	(unset)	IdP group claim that maps a login to the operator role.
OIDC_ALLOWED_GROUPS	(unset = open provisioning)	Comma/space-separated groups. When set, a login is provisioned only if the token's groups intersect this set.	Empty means any successful IdP login creates a local user.

---

Integrations / notifications (optional)

Variable	Default	Description	Notes
INTEGRATION_API_TOKEN	(unset)	Bearer token enabling GET /api/integration/agents/live (Authorization: Bearer <token>) for your own scripts/tools.	_FILE

Alert notification channels

When an alert rule fires, the match is delivered to every configured channel below. Set the variables for the channels you want and restart the server; Settings → Alert notification channels shows live status and a Send test button. Secrets stay on the server (no _FILE support). For per-channel setup walkthroughs see Notifications.

Email (SMTP) - requires SMTP_HOST + SMTP_FROM + SMTP_TO.

Variable	Default	Description
SMTP_HOST	(unset)	SMTP server hostname. Required to enable email.
SMTP_FROM	(unset)	Sender, e.g. Vantyr <alerts@example.com>. Required.
SMTP_TO	(unset)	Comma-separated recipients. Required.
SMTP_PORT	(per TLS mode)	Defaults to 587 (starttls), 465 (implicit), or 25 (none).
SMTP_USERNAME	(unset)	Omit for an unauthenticated relay.
SMTP_PASSWORD	(unset)	App password / SMTP credential.
SMTP_TLS	starttls	starttls · implicit · none (plaintext - avoid).
SMTP_SUBJECT_PREFIX	(unset)	Optional prefix prepended to every subject.

Webhook-style channels - each enabled by setting its URL/token(s).

Variable	Default	Description
SLACK_WEBHOOK_URL	(unset)	Slack Incoming Webhook URL.
DISCORD_WEBHOOK_URL	(unset)	Discord channel Webhook URL.
TEAMS_WEBHOOK_URL	(unset)	Microsoft Teams Incoming Webhook / Workflow URL.
TELEGRAM_BOT_TOKEN	(unset)	Telegram bot token (@BotFather). Needs TELEGRAM_CHAT_ID.
TELEGRAM_CHAT_ID	(unset)	Target chat id, or @channelusername.
NTFY_URL	(unset)	Full ntfy topic URL, e.g. https://ntfy.sh/vantyr-alerts.
NTFY_TOKEN	(unset)	ntfy access token (protected topics only).
PUSHOVER_TOKEN	(unset)	Pushover application token. Needs PUSHOVER_USER_KEY.
PUSHOVER_USER_KEY	(unset)	Pushover user/group key.
NOTIFY_WEBHOOK_URL	(unset)	Generic endpoint; receives the raw alert JSON.
NOTIFY_WEBHOOK_AUTH_HEADER	(unset)	Header: value pair, or a bare Authorization value.

Home Assistant - fires a custom event for HA automations. Full guide: Home Assistant.

Variable	Default	Description	Notes
HOME_ASSISTANT_URL	(unset)	Home Assistant base URL, e.g. https://homeassistant.local:8123. Setting URL + token enables firing an HA event on alert-rule matches.
HOME_ASSISTANT_ACCESS_TOKEN	(unset)	Long-lived access token (HA Profile → Security).
HOME_ASSISTANT_EVENT_TYPE	vantyr_alert	Event type fired into HA on alert matches. Must match [a-z0-9_]+.
HOME_ASSISTANT_SKIP_TLS_VERIFY ⚠️	false	If true, disables TLS certificate verification for HA requests.	HIGH RISK - only for self-signed HA in dev.

Deep links in notifications (a tappable link to the agent's Activity timeline) require PUBLIC_BASE_URL to be set.

---

mDNS / LAN auto-discovery (optional)

By default the server advertises _vantyr._tcp on the LAN so agents can auto-discover it, as long as a WSS URL can be resolved (from VANTYR_MDNS_WSS_URL or PUBLIC_BASE_URL). Without either, advertisement is skipped (warning logged).

Variable	Default	Description	Notes
VANTYR_MDNS_WSS_URL	(derived)	Explicit wss://host:port/ws/agent advertised in the mDNS TXT record. Must start with wss://.	If unset, derived from PUBLIC_BASE_URL.
VANTYR_MDNS_ADDRESSES	(auto)	Comma-separated IPs for the mDNS A/AAAA records, e.g. 192.168.1.10.	Override when auto-detection picks the wrong NIC.
VANTYR_MDNS_PORT	(listen port)	Advertised SRV port; set to e.g. 443 when TLS terminates on the proxy.
VANTYR_MDNS	on	Set to 0/false/off/no to disable mDNS advertisement.
VANTYR_MDNS_DISABLE	(unset)	Set to 1/true to disable mDNS advertisement (alternative to VANTYR_MDNS=0).

---

Docker Compose notes

The committed docker-compose.yml uses host networking (network_mode: host) for the server and does not map 9000 via ports:. No TLS/reverse-proxy example ships - for anything beyond localhost/trusted LAN, front Vantyr with Caddy/nginx/Traefik (forwarding X-Forwarded-Proto) and set ENFORCE_HTTPS=true, PUBLIC_BASE_URL=https://…, and VANTYR_MDNS_PORT=443. See Deployment.

See also: Environment template · Security · OIDC · Usage.