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=

# 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