Environment template

Environment template (full reference)

A long, copy-pasteable .env-style block for advanced / non-Compose setups. Only POSTGRES_PASSWORD and ADMIN_PASSWORD are required; everything else is shown commented with its default. For per-variable explanations, defaults, and validation rules, see Configuration. To get running fast, see Deployment.

Secret files: any variable resolved through read_env_or_file also accepts a <NAME>_FILE path (Docker/Compose secrets); the file contents are used verbatim (trimmed). Example: ADMIN_PASSWORD_FILE=/run/secrets/admin_password. OIDC and Home Assistant variables do not currently support _FILE (except OIDC_CLIENT_SECRET_FILE).

# ──────────────────────────────────────────────────────────────────────────────
# Vantyr server configuration (advanced template)
# Copy to .env and edit. Required: POSTGRES_PASSWORD, ADMIN_PASSWORD.
# Every value below shows its default (commented) unless required.
# ──────────────────────────────────────────────────────────────────────────────

# ─── Database ─────────────────────────────────────────────────────────────────
# Generate a strong password, e.g. openssl rand -base64 24
POSTGRES_PASSWORD=CHANGE_ME_generate_with_openssl_rand_base64_24
#POSTGRES_DB=monitor
#POSTGRES_USER=monitor
# Set DATABASE_URL directly only if NOT using the bundled compose Postgres.
# Must be a postgres:// or postgresql:// URL (validated, fail-fast).
#DATABASE_URL=postgres://monitor:monitor@localhost:5432/monitor

# ─── Admin bootstrap ──────────────────────────────────────────────────────────
# Required in release builds (creates the first user when the DB has zero users).
ADMIN_PASSWORD=CHANGE_ME_generate_with_openssl_rand_base64_24
#ADMIN_USERNAME=admin
# Legacy alias, used only if ADMIN_PASSWORD is unset.
#UI_PASSWORD=
# ⚠️ HIGH RISK: lets the dashboard run with NO users at all. Leave unset.
#ALLOW_INSECURE_DASHBOARD_OPEN=false

# ─── Listener / static / pool ─────────────────────────────────────────────────
#LISTEN_ADDR=0.0.0.0:9000
#STATIC_DIR=./static                 # Docker image sets this to /app/static
#POOL_MAX_CONNECTIONS=20             # 1–200
# Absolute base URL; used for mDNS advertisement, OIDC redirects, and deep links.
#PUBLIC_BASE_URL=https://vantyr.example.com

# ─── Security: TLS / cookies / CORS / proxy ───────────────────────────────────
# ENFORCE_HTTPS defaults to TRUE in code. Set false ONLY for localhost/LAN HTTP.
# Behind a TLS-terminating proxy that forwards X-Forwarded-Proto, set true.
#ENFORCE_HTTPS=true
# Force the session cookie Secure flag (auto-detected from TLS otherwise).
# Do NOT force true on plain HTTP - the browser will drop the cookie.
#COOKIE_SECURE=false
# Comma-separated browser origins allowed to call the API (empty = same-origin).
#CORS_ORIGINS=https://dashboard.example.com
# Comma-separated CIDRs/IPs of trusted reverse proxies (X-Forwarded-For / Proto).
# Empty trusts no proxy and keys on the direct TCP peer. Set behind nginx/Caddy/Traefik.
#TRUSTED_PROXY_CIDRS=10.0.0.0/8,172.16.0.0/12

# ─── Data retention (background prune job) ────────────────────────────────────
#RETENTION_INTERVAL_SECS=3600        # how often the prune task runs (min 60)
# Omit to keep forever; must be >= 1 when set.
#ALERT_EVENT_RETENTION_DAYS=         # also reclaims alert screenshot blobs (FK cascade)
#SOFTWARE_INVENTORY_RETENTION_DAYS=
# Append-only tables: default ON at 90 days; set 0 to keep forever.
#SCRIPT_EXECUTION_RETENTION_DAYS=90  # scheduled-script execution history
#METRICS_RETENTION_DAYS=90           # CPU/mem/disk health-history samples

# ─── Remote script execution (HIGH RISK) ──────────────────────────────────────
# ⚠️ Master kill-switch for running PowerShell/cmd on agents from the dashboard
#    (ad-hoc, scheduled, manual "run now"). Enabling = remote code on endpoints.
#ALLOW_REMOTE_SCRIPT_EXECUTION=false

# ─── Scheduler ────────────────────────────────────────────────────────────────
# IANA timezone for scheduled fire times (default UTC), e.g. Asia/Kuala_Lumpur.
#SCHEDULER_TIMEZONE=UTC

# ─── Rate limiting ────────────────────────────────────────────────────────────
# Max requests/sec per client IP across dashboard + API. 0 disables.
#API_RATE_LIMIT_PER_SECOND=0         # suggested 50–200 in production
# Minimum seconds between Wake-on-LAN packets per agent (0 disables throttle).
#WOL_MIN_INTERVAL_SECS=15

# ─── Observability / logging ──────────────────────────────────────────────────
#METRICS_ENABLED=true                # expose Prometheus metrics at /metrics
#LOG_JSON=false                      # JSON log lines (Loki/ELK) vs human-readable
#RUST_LOG=info
# ⚠️ Include internal error detail in API responses (debugging only; never prod).
#EXPOSE_INTERNAL_ERRORS=false
#NO_COLOR=                           # set to disable ANSI color in logs
#LOG_FORCE_COLOR=                    # 1/true forces ANSI even when not a TTY (Docker)

# ─── OIDC / SSO (optional) ────────────────────────────────────────────────────
# Set the four core values to enable "Sign in with SSO". See wiki: OIDC.
#OIDC_ISSUER_URL=https://idp.example.com
#OIDC_CLIENT_ID=
#OIDC_CLIENT_SECRET=                 # supports OIDC_CLIENT_SECRET_FILE
#OIDC_REDIRECT_URL=https://vantyr.example.com/api/auth/oidc/callback
#OIDC_SCOPES=openid profile email
# Map IdP group claims to Vantyr roles (optional):
#OIDC_ADMIN_GROUP=vantyr-admins
#OIDC_OPERATOR_GROUP=vantyr-operators
# Restrict provisioning to these groups (empty = any successful login provisions):
#OIDC_ALLOWED_GROUPS=vantyr-admins,vantyr-operators

# ─── Integrations / notifications (optional) ──────────────────────────────────
# Bearer token for GET /api/integration/agents/live (supports INTEGRATION_API_TOKEN_FILE).
#INTEGRATION_API_TOKEN=
#
# Alert notification channels. Each fired alert rule is delivered to every channel
# configured below. Set the vars you want and restart; Settings → "Alert
# notification channels" shows status + a "Send test" button. Secrets stay on the
# server (no _FILE variant). Full guide: wiki Notifications.

# Email (SMTP): requires SMTP_HOST, SMTP_FROM, SMTP_TO.
#SMTP_HOST=smtp.example.com
#SMTP_PORT=587                       # optional; defaults to the port for SMTP_TLS
#SMTP_FROM=Vantyr <alerts@example.com>
#SMTP_TO=ops@example.com,oncall@example.com   # comma-separated
#SMTP_USERNAME=                      # optional (omit for an unauthenticated relay)
#SMTP_PASSWORD=
#SMTP_TLS=starttls                   # starttls (default) | implicit | none
#SMTP_SUBJECT_PREFIX=[Vantyr]        # optional

# Slack / Discord / Microsoft Teams — channel webhook URLs.
#SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T000/B000/XXXX
#DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/000/XXXX
#TEAMS_WEBHOOK_URL=https://outlook.office.com/webhook/XXXX

# Telegram — bot token (@BotFather) + chat id (or @channelusername).
#TELEGRAM_BOT_TOKEN=123456:ABC-DEF
#TELEGRAM_CHAT_ID=123456789

# ntfy — full topic URL; token only for protected topics.
#NTFY_URL=https://ntfy.sh/vantyr-alerts
#NTFY_TOKEN=

# Pushover — application token + user/group key.
#PUSHOVER_TOKEN=
#PUSHOVER_USER_KEY=

# Generic webhook — POST the raw alert JSON to any endpoint.
#NOTIFY_WEBHOOK_URL=https://example.com/hooks/vantyr
#NOTIFY_WEBHOOK_AUTH_HEADER=         # "Header: value" pair, or a bare Authorization value

# Home Assistant: fire a custom event on alert-rule matches (URL + token to enable).
#HOME_ASSISTANT_URL=https://homeassistant.local:8123
#HOME_ASSISTANT_ACCESS_TOKEN=        # long-lived token (Profile → Security)
#HOME_ASSISTANT_EVENT_TYPE=vantyr_alert   # must match [a-z0-9_]+
# ⚠️ Disables TLS verification for HA requests - dev/self-signed only.
#HOME_ASSISTANT_SKIP_TLS_VERIFY=false

# ─── mDNS / LAN auto-discovery (optional) ─────────────────────────────────────
# Advertises _vantyr._tcp so agents can auto-discover the server. Requires a WSS
# URL from VANTYR_MDNS_WSS_URL or PUBLIC_BASE_URL, else advertisement is skipped.
#VANTYR_MDNS_WSS_URL=wss://vantyr.example.com/ws/agent
#VANTYR_MDNS_ADDRESSES=192.168.1.10
#VANTYR_MDNS_PORT=9000               # e.g. 443 when TLS terminates on the proxy
#VANTYR_MDNS=1                       # 0/false/off disables advertisement
#VANTYR_MDNS_DISABLE=                # 1/true disables (alternative to VANTYR_MDNS=0)

See also: Configuration · Deployment · Security · OIDC · Usage.