All configuration is done through environment variables, defined in your .env.prod file. This page documents every variable.
Variable Default Required Description POSTGRES_USERbreezePostgreSQL username POSTGRES_PASSWORD— Yes PostgreSQL password POSTGRES_DBbreezeDatabase name POSTGRES_PORT5432PostgreSQL port DATABASE_URL— Auto Full connection string (constructed from above in Docker)
Variable Default Required Description REDIS_URLredis://localhost:6379Redis connection URL REDIS_PORT6379Redis port
Variable Default Required Description JWT_SECRET— Yes JWT signing key (min 32 chars). Generate: openssl rand -base64 64 JWT_EXPIRES_IN15mAccess token lifetime REFRESH_TOKEN_EXPIRES_IN7dRefresh token lifetime AGENT_ENROLLMENT_SECRET— Yes Shared secret for agent enrollment. Generate: openssl rand -hex 32 APP_ENCRYPTION_KEY— Yes AES encryption key for sensitive data at rest MFA_ENCRYPTION_KEY— Yes Encryption key for MFA secrets ENROLLMENT_KEY_PEPPER— Yes HMAC pepper for enrollment key hashing MFA_RECOVERY_CODE_PEPPER— Yes HMAC pepper for recovery code hashing ENROLLMENT_KEY_DEFAULT_TTL_MINUTES60Default enrollment key expiry SESSION_SECRET— Yes Express session signing secret SESSION_MAX_AGE86400000Session max age in ms (24h)
Variable Default Required Description NODE_ENVproductionEnvironment mode API_PORT3001API server port WEB_PORT4321Web dashboard port PUBLIC_API_URL— Full public API URL. Leave empty for Docker deployments — the web app uses relative URLs through Caddy. BREEZE_DOMAIN— Yes (prod) Domain for Caddy TLS provisioning ACME_EMAIL— Yes (prod) Email for Let’s Encrypt certificate notifications CORS_ALLOWED_ORIGINS— Comma-separated allowed CORS origins TRUST_PROXY_HEADERSfalseSet true when behind a reverse proxy DASHBOARD_URL— URL for links in emails PUBLIC_APP_URL— Public-facing app URL
Variable Default Description EMAIL_PROVIDERautoProvider: auto, resend, smtp, or mailgun RESEND_API_KEY— Resend API key EMAIL_FROM[email protected] Sender address SMTP_HOST— SMTP server hostname SMTP_PORT587SMTP port SMTP_USER— SMTP username SMTP_PASS— SMTP password SMTP_FROM[email protected] SMTP-specific sender address SMTP_SECUREfalseUse TLS for SMTP MAILGUN_API_KEY— Mailgun API key MAILGUN_DOMAIN— Mailgun sending domain MAILGUN_BASE_URLhttps://api.mailgun.netMailgun API base URL MAILGUN_FROM[email protected] Mailgun-specific sender address
Variable Default Description TWILIO_ACCOUNT_SID— Twilio Account SID TWILIO_AUTH_TOKEN— Twilio Auth Token TWILIO_VERIFY_SERVICE_SID— Twilio Verify service SID (for SMS MFA) TWILIO_MESSAGING_SERVICE_SID— Twilio Messaging Service SID (for alert SMS) TWILIO_PHONE_NUMBER— Twilio phone number for outbound SMS
Variable Default Description BINARY_SOURCElocalDownload source: local (serve from disk, optional S3) or github (redirect to GitHub Releases) AGENT_BINARY_DIR./agent/binLocal directory containing agent binaries VIEWER_BINARY_DIR./viewer/binLocal directory containing viewer installers HELPER_BINARY_DIR/data/binaries/helperLocal directory containing helper binaries BINARY_VERSION_FILE— Path to VERSION file for local mode DB registration (set automatically in Docker Compose) BINARY_VERSION— Release tag for GitHub redirect mode (falls back to BREEZE_VERSION, then latest)
See Binary Distribution for details on local vs GitHub mode and S3 offloading.
Variable Default Description S3_ENDPOINT— S3-compatible endpoint (MinIO, R2, AWS). Uses path-style addressing. S3_ACCESS_KEY— Access key S3_SECRET_KEY— Secret key S3_BUCKET— Bucket name S3_REGIONus-east-1Bucket region S3_PRESIGN_TTL900Presigned URL expiration in seconds (15 min) MINIO_API_PORT9000MinIO API port (Docker only) MINIO_CONSOLE_PORT9001MinIO web console port (Docker only)
The Breeze stack includes a coturn TURN server for WebRTC relay. Without TURN, remote desktop connections fail when either peer is behind symmetric NAT or a restrictive firewall.
Variable Default Required Description TURN_HOST— Yes (prod) Public IP or hostname of the TURN server. Must be reachable by agents and viewers. TURN_PORT3478TURN listening port (UDP and TCP) TURN_SECRET— Yes (prod) Shared secret for TURN credential generation. Generate: openssl rand -hex 32 TURN_REALMbreeze.localTURN authentication realm
Variable Default Description METRICS_SCRAPE_TOKEN— Bearer token for /metrics/scrape METRICS_INCLUDE_ORG_IDfalseInclude org IDs in Prometheus labels METRICS_SCRAPE_IP_ALLOWLIST— Restrict metrics scraping by IP LOG_LEVELinfoLog verbosity: debug, info, warn, error LOG_JSONtrueStructured JSON logging GRAFANA_ADMIN_USERadminGrafana admin username GRAFANA_ADMIN_PASSWORD— Grafana admin password GRAFANA_PORT3000Grafana web UI port (monitoring stack) GRAFANA_ROOT_URLhttp://localhost:3000Grafana public root URL (monitoring stack) PROMETHEUS_PORT9090Prometheus web UI port (monitoring stack) ALERTMANAGER_PORT9093Alertmanager web UI port (monitoring stack) LOKI_PORT3100Loki log aggregation API port (monitoring stack)
Variable Default Description SENTRY_DSN— Sentry DSN for error tracking SENTRY_ENVIRONMENTproductionSentry environment tag SENTRY_RELEASE— Sentry release tag (e.g. git SHA) SENTRY_TRACES_SAMPLE_RATE0.1Sentry performance trace sample rate (0.0-1.0)
Variable Default Description RATE_LIMIT_WINDOW_MS60000Sliding window duration (ms) RATE_LIMIT_MAX_REQUESTS100Max requests per window
Variable Default Description TRANSFER_STORAGE_PATH./data/transfersFile transfer storage directory MAX_TRANSFER_SIZE_MB100Max file transfer size MAX_ACTIVE_TRANSFERS_PER_ORG20Concurrent transfer limit per org MAX_ACTIVE_TRANSFERS_PER_USER10Concurrent transfer limit per user MAX_ACTIVE_REMOTE_SESSIONS_PER_ORG10Concurrent remote sessions per org MAX_ACTIVE_REMOTE_SESSIONS_PER_USER5Concurrent remote sessions per user PATCH_REPORT_STORAGE_PATH./data/patch-reportsPatch compliance report storage
Variable Default Description ENABLE_REGISTRATIONtrueAllow new user registration ENABLE_2FAtrueEnable two-factor authentication ENABLE_API_DOCSfalseEnable Swagger API documentation ENABLE_API_DOCS_UIfalseEnable interactive Swagger UI (requires ENABLE_API_DOCS=true) USE_AGENT_SDK— Use Claude Agent SDK for AI chat PORTAL_STATE_BACKENDmemoryPortal state backend: memory or redis (auto redis in production)
Variable Default Description MCP_SSE_RATE_LIMIT_PER_MINUTE30SSE connection rate limit per API key MCP_MESSAGE_RATE_LIMIT_PER_MINUTE120Message rate limit per API key MCP_MAX_SSE_SESSIONS_PER_KEY5Max concurrent SSE sessions per API key MCP_REQUIRE_EXECUTE_ADMINfalseRequire ai:execute_admin scope for Tier 3 tools MCP_EXECUTE_TOOL_ALLOWLIST— Comma-separated allowed Tier 3 tools (empty = deny all)
Variable Default Description CLOUDFLARE_API_TOKEN— Cloudflare API token with Client Certificates permission CLOUDFLARE_ZONE_ID— Cloudflare zone ID for your domain
Variable Default Description C2C_M365_CLIENT_ID— Azure AD app (client) ID for multi-tenant M365 backup. When set with the secret below, enables one-click admin consent flow for connecting Microsoft 365 backups. C2C_M365_CLIENT_SECRET— Azure AD app client secret for multi-tenant M365 backup
These variables are optional. When unset, the C2C connection wizard falls back to manual credential entry (Client ID, Secret, Tenant ID). Setting both enables a streamlined “Grant Access” button that redirects to Microsoft’s admin consent flow.
Variable Default Description BREEZE_VERSIONlatestBreeze release tag for Docker images (e.g. 0.50.0). Also used by GitHub redirect mode for agent binary downloads. DOCKER_PLATFORMlinux/amd64Container platform. GHCR images are amd64 only. On Apple Silicon, use docker-compose.override.yml.local-build to build native arm64 images instead. REDIS_MAXMEMORY256mbMaximum memory Redis is allowed to use. Redis runs with noeviction policy so BullMQ jobs are never silently dropped.
Variable Default Description ANTHROPIC_API_KEY— Anthropic API key for AI assistant (BYOK)
