overlord/.env.example

# Overlord Configuration (Optional Overrides)
# 
# Most users don't need to create a .env file!
# The docker-compose.yml has sensible defaults.
#
# On first startup, secrets are auto-generated and persisted in ./data/save.json
# when not explicitly provided.
#
# Only create .env if you want to customize:

# ============================================
# PRODUCTION: Use pre-built image
# ============================================
# Set this to pull from registry instead of building locally
# DOCKER_IMAGE=ghcr.io/yourusername/overlord-server:latest

# ============================================
# OPTIONAL: Custom initial admin username
# ============================================
# Default is "admin" - change if you prefer a different username
# OVERLORD_USER=myadmin

# OPTIONAL: Custom initial admin password
# Default is "admin"
# OVERLORD_PASS=admin

# ============================================
# OPTIONAL: Custom port
# ============================================
# Default is 5173
# PORT=8080
# Bind address inside the server. For Linux host-network reverse-proxy deployments,
# use 127.0.0.1. Docker Desktop containers must keep this at 0.0.0.0.
# HOST=0.0.0.0

# Bind the Docker Desktop published port to this host address.
# Set 127.0.0.1 when nginx/Caddy runs on the host.
# OVERLORD_PUBLISH_HOST=127.0.0.1

# Serve HTTP internally and require a trusted reverse proxy to terminate public TLS.
# The public browser/agent URL must remain HTTPS/WSS.
# OVERLORD_TLS_OFFLOAD=true
# OVERLORD_HEALTHCHECK_URL=http://127.0.0.1:5173/health

# WebRTC TURN relay ports. Docker Desktop on Windows defaults to 40000-40040
# because Windows commonly reserves ports in the 49152+ dynamic range.
# OVERLORD_TURN_MIN_PORT=40000
# OVERLORD_TURN_MAX_PORT=40040

# ============================================
# ADVANCED: Custom JWT secret
# ============================================
# Leave empty to auto-generate and persist to save.json (recommended)
# JWT_SECRET=

# OPTIONAL: Agent authentication token
# Leave empty to auto-generate and persist to save.json
# OVERLORD_AGENT_TOKEN=

# Recommended: pin browser Origin/CSRF checks to the externally visible origin.
# This is especially important behind TLS offload or a reverse proxy.
# OVERLORD_PUBLIC_ORIGIN=https://overlord.example.com

# When forwarding headers arrive from a public-address reverse proxy, list the
# proxy's immediate IP here (comma-separated). Only loopback peers are trusted
# automatically; private container/LAN proxy addresses must also be listed.
# OVERLORD_TRUSTED_PROXY_IPS=203.0.113.10

# Legacy query-token clients remain supported. Prefer X-Agent-Token for new
# clients; set this to false once every deployed client has migrated.
# OVERLORD_ALLOW_AGENT_TOKEN_QUERY=false
# Legacy password-protected file-share links remain supported. Prefer the
# X-Download-Password header; set this to false to reject query secrets.
# OVERLORD_ALLOW_FILE_SHARE_PASSWORD_QUERY=false

# Bound unapproved identity storage if an agent token is leaked. Pending rows
# expire after seven days and are capped globally/per observed source IP.
# OVERLORD_PENDING_ENROLLMENT_TTL_HOURS=168
# OVERLORD_MAX_PENDING_ENROLLMENTS=100000
# OVERLORD_MAX_PENDING_ENROLLMENTS_PER_IP=10000
# OVERLORD_MAX_PREAUTH_SOCKETS_GLOBAL=100000
# OVERLORD_MAX_PREAUTH_SOCKETS_PER_IP=10000
# OVERLORD_MAX_ENROLLMENT_VERIFICATIONS=4096
# OVERLORD_ENROLLMENT_VERIFICATION_ATTEMPTS_PER_SECOND=100000
# OVERLORD_ENROLLMENT_VERIFICATION_ATTEMPT_BURST=200000

# Generous defaults avoid dropping frames in large fleets; lower these if the
# server operator wants explicit memory/backpressure limits.
# OVERLORD_THUMBNAIL_PENDING_MAX_COUNT=512
# OVERLORD_THUMBNAIL_PENDING_MAX_BYTES=536870912
# OVERLORD_THUMBNAIL_QUEUE_MAX=512
# OVERLORD_THUMBNAIL_CACHE_MAX_BYTES=1073741824
# OVERLORD_THUMBNAIL_REQUEST_MAX=4096
# OVERLORD_THUMBNAIL_WAITER_ID_MAX=4096
# OVERLORD_THUMBNAIL_WAITER_MAX=8192

# Notification screenshot storage is bounded transactionally. Byte values are
# raw bytes. Uncomment to impose lower operator-selected retention limits.
# OVERLORD_NOTIFICATION_SCREENSHOT_CLIENT_MAX_COUNT=10000
# OVERLORD_NOTIFICATION_SCREENSHOT_CLIENT_MAX_BYTES=1073741824
# OVERLORD_NOTIFICATION_SCREENSHOT_GLOBAL_MAX_COUNT=100000
# OVERLORD_NOTIFICATION_SCREENSHOT_GLOBAL_MAX_BYTES=17179869184

# Notification metadata history is also bounded per client and fleet-wide.
# Oldest rows and linked screenshots are pruned atomically at these limits.
# OVERLORD_NOTIFICATION_HISTORY_CLIENT_MAX_COUNT=100000
# OVERLORD_NOTIFICATION_HISTORY_CLIENT_MAX_BYTES=1073741824
# OVERLORD_NOTIFICATION_HISTORY_GLOBAL_MAX_COUNT=1000000
# OVERLORD_NOTIFICATION_HISTORY_GLOBAL_MAX_BYTES=17179869184

# Chat-plugin fleet retention quotas. These prevent many approved client
# identities from multiplying the built-in per-client message/attachment caps.
# OVERLORD_CHAT_PLUGIN_GLOBAL_MAX_MESSAGES=1000000
# OVERLORD_CHAT_PLUGIN_GLOBAL_MAX_MESSAGE_BYTES=17179869184
# OVERLORD_CHAT_PLUGIN_GLOBAL_MAX_ATTACHMENT_BYTES=17179869184

# Fleet-wide archived keylog quotas supplement the built-in per-client cap.
# Oldest rows and their full-text-search entries are pruned first.
# OVERLORD_INPUT_ARCHIVE_GLOBAL_MAX_FILES=1000000
# OVERLORD_INPUT_ARCHIVE_GLOBAL_MAX_BYTES=68719476736

# Audit retention is opt-in. Uncomment either setting to prune old history.
# OVERLORD_AUDIT_RETENTION_DAYS=90
# OVERLORD_AUDIT_MAX_ROWS=250000

# Web Push subscriptions are capped per account and server-wide. When an
# account reaches its cap, registering a new browser replaces its oldest entry.
# Delivery uses small batches so a large installation cannot create an
# unbounded number of simultaneous outbound requests.
# OVERLORD_MAX_PUSH_SUBSCRIPTIONS_PER_USER=10
# OVERLORD_MAX_PUSH_SUBSCRIPTIONS=10000
# OVERLORD_PUSH_SUBSCRIPTION_RATE_LIMIT_MAX=20
# OVERLORD_PUSH_SUBSCRIPTION_RATE_LIMIT_WINDOW_SECONDS=60
# OVERLORD_PUSH_SUBSCRIPTION_RATE_LIMIT_LOCKOUT_SECONDS=60
# OVERLORD_WEB_PUSH_DELIVERY_CONCURRENCY=8
# OVERLORD_WEB_PUSH_DELIVERY_BATCH_SIZE=100

# OPTIONAL: Solana publisher RPC request limits (per signed-in user)
# OVERLORD_SOL_PUBLISH_RATE_LIMIT_MAX=3
# OVERLORD_SOL_PUBLISH_RATE_LIMIT_WINDOW_SECONDS=300
# OVERLORD_SOL_PUBLISH_RATE_LIMIT_LOCKOUT_SECONDS=300
# OVERLORD_SOL_BALANCE_RATE_LIMIT_MAX=12
# OVERLORD_SOL_BALANCE_RATE_LIMIT_WINDOW_SECONDS=60
# OVERLORD_SOL_BALANCE_RATE_LIMIT_LOCKOUT_SECONDS=60

# ============================================
# OPTIONAL: OIDC / SSO login
# ============================================
# Generic OIDC works with providers such as Authentik, Authelia, Keycloak, Zitadel, and Dex.
# Configure your provider callback/redirect URI as:
#   https://YOUR_OVERLORD_HOST/api/oidc/callback
# Keep local username/password login enabled as a fallback.
# OVERLORD_OIDC_ENABLED=true
# OVERLORD_OIDC_LABEL=Sign in with SSO
# OVERLORD_OIDC_ISSUER=https://auth.example.com/application/o/overlord/
# OVERLORD_OIDC_CLIENT_ID=overlord
# OVERLORD_OIDC_CLIENT_SECRET=change-me
# OVERLORD_OIDC_REDIRECT_URI=https://overlord.example.com/api/oidc/callback
# OVERLORD_OIDC_DEFAULT_ROLE=viewer
# OVERLORD_OIDC_ALLOWED_DOMAINS=example.com
# OVERLORD_OIDC_ADMIN_GROUPS=overlord-admins
# OVERLORD_OIDC_OPERATOR_GROUPS=overlord-operators
# OVERLORD_OIDC_VIEWER_GROUPS=overlord-viewers

# ============================================
# OPTIONAL: Login screen branding
# ============================================
# Use a logo URL, or leave it empty and set a Font Awesome icon class.
# Logo URLs may be absolute http(s) URLs or root-relative paths such as /assets/logo.png.
# OVERLORD_LOGIN_BRAND_NAME=Acme SOC
# OVERLORD_NAV_BRAND_NAME=Acme Console
# OVERLORD_BRAND_ACCENT_COLOR=#14b8a6
# OVERLORD_LOGIN_TITLE=Welcome to Acme Overlord
# OVERLORD_LOGIN_SUBTITLE=Sign in with your Acme identity
# OVERLORD_LOGIN_LOGO_URL=/assets/acme-logo.png
# OVERLORD_LOGIN_LOGO_ALT=Acme logo
# OVERLORD_NAV_LOGO_URL=/assets/acme-nav-logo.png
# OVERLORD_NAV_LOGO_ALT=Acme logo
# OVERLORD_LOGIN_HERO_IMAGE_URL=/assets/acme-login.jpg
# OVERLORD_LOGIN_HERO_IMAGE_ALT=Acme operations center
# OVERLORD_LOGIN_FOOTER_TEXT=Authorized Acme access only
# OVERLORD_LOGIN_SUPPORT_TEXT=Need access help?
# OVERLORD_LOGIN_SUPPORT_URL=https://help.example.com
# OVERLORD_LOGIN_ICON_CLASS=fa-solid fa-shield-halved

# ============================================
# ADVANCED: Custom TLS certificates
# ============================================
# Leave as defaults to use auto-generated self-signed certs
# OVERLORD_TLS_CERT=/custom/path/server.crt
# OVERLORD_TLS_KEY=/custom/path/server.key

# ============================================
# ADVANCED: Reverse proxy / domain deployments
# ============================================
# If Overlord sits behind a reverse proxy (nginx, Caddy, Cloudflare, Traefik, Render,
# etc.), the server otherwise sees the proxy's IP for every agent connection — the
# dashboard, audit log, and IP bans all end up showing the proxy/Docker bridge IP
# (commonly 172.x.x.x) instead of the real client. Set this to true ONLY when a
# trusted reverse proxy is in front of Overlord; otherwise agents could spoof
# their IP by sending their own X-Forwarded-For header. Auto-enabled when
# OVERLORD_TLS_OFFLOAD=true. Honors X-Forwarded-For, X-Real-IP, CF-Connecting-IP.
# OVERLORD_TRUST_PROXY=true

# Agent builder settings (only needed if building agents)
# TARGETS=windows/amd64,windows/386,windows/arm64,linux/amd64,linux/arm64,linux/arm/v7,darwin/amd64,darwin/arm64
# GO_BUILD_FLAGS=-trimpath
# LDFLAGS=-s -w