.env.example

# ============================================
# Breeze RMM - Environment Configuration
# ============================================
# Copy this file to .env and update values for your environment
# NEVER commit the .env file to version control

# --------------------------------------------
# Database Configuration
# --------------------------------------------
POSTGRES_USER=breeze
POSTGRES_PASSWORD=breeze_secure_password_change_me
POSTGRES_DB=breeze
POSTGRES_PORT=5432

# Administrator/system URL. Required for migrations and role setup; request
# handlers do not use this connection in production.
#
# Under the bundled root docker-compose.yml this value never reaches the API:
# compose rebuilds DATABASE_URL as ...@postgres:5432 inside the api container
# from POSTGRES_USER/POSTGRES_PASSWORD/POSTGRES_DB. It is read only by host-side
# tooling (pnpm db:studio, db:check-drift, scripts/backup.sh) — which also needs
# the Postgres port published, and the bundled compose does NOT publish it. So
# the localhost value below is inert under Compose rather than "correct": leave
# it alone, and note it does not track the POSTGRES_* values you set above.
DATABASE_URL=postgresql://breeze:breeze_secure_password_change_me@localhost:5432/breeze
# Exact unprivileged request-pool URL, for direct (non-Compose) API deployments
# and the production deploy Compose only.
#
# LEAVE THIS EMPTY for the bundled root docker-compose.yml. Unlike DATABASE_URL
# — which compose rebuilds as ...@postgres:5432 inside the api container — this
# value is passed straight through (`${DATABASE_URL_APP:-}`), so a localhost URL
# makes the request pool dial the api container's OWN loopback and the API
# crashes at first-boot seed with ECONNREFUSED 127.0.0.1:5432. Left empty, the
# API derives breeze_app@postgres from the container's own DATABASE_URL (given
# POSTGRES_PASSWORD or BREEZE_APP_DB_PASSWORD, which the bundled compose
# requires anyway).
#
# If you do set it, point it at a host the api container can actually reach
# (never localhost/127.0.0.1/::1 while running under Compose). Every startup
# probes the effective request connection and refuses SUPERUSER or BYPASSRLS
# roles, in every environment.
DATABASE_URL_APP=
# Example for a direct (non-Compose) deployment, pointing at a host the API
# can actually reach:
#   DATABASE_URL_APP=postgresql://breeze_app:password@db.example.com:5432/breeze
# Optional: override the breeze_app password. Without DATABASE_URL_APP, Breeze
# derives a breeze_app URL from DATABASE_URL using this value, then
# POSTGRES_PASSWORD as fallback. AUTO_MIGRATE=false skips migrations only; the
# effective request role is still verified at startup.
# BREEZE_APP_DB_PASSWORD=

# --------------------------------------------
# Redis Configuration (BullMQ Job Queue)
# --------------------------------------------
REDIS_PASSWORD=generate-a-random-secret-for-production
REDIS_URL=redis://:${REDIS_PASSWORD}@localhost:6379
REDIS_PORT=6379

# Readiness results are cached and dependency probes are bounded. Values are
# clamped so cache TTL + probe timeout never exceeds the supported 10s
# failure/recovery visibility threshold.
READINESS_CACHE_TTL_MS=5000
READINESS_PROBE_TIMEOUT_MS=3000
# BullMQ concurrency of the offline-detector mark worker (integer 1-20; code
# default 5). Raise only on exact-candidate evidence — the product default
# does not change with this knob.
# OFFLINE_DETECTOR_WORKER_CONCURRENCY=5

# --------------------------------------------
# Authentication & Security
# --------------------------------------------
# CRITICAL: Generate strong secrets for production
# Use: openssl rand -base64 64
JWT_SECRET=your-super-secret-jwt-key-change-in-production-must-be-at-least-32-chars
# Required dedicated HMAC key for opaque partner export cursors (do not reuse JWT_SECRET).
# Generate with: openssl rand -base64 32
# Keep the same protected value on every API instance and include it in secret-store backups.
PARTNER_API_CURSOR_SIGNING_KEY=replace-with-base64-encoded-32-byte-random-key
# Access-token (15m) and refresh-token (7d) lifetimes are fixed in code
# (apps/api/src/services/jwt.ts) — short-lived access tokens backed by
# refresh-token rotation. They are intentionally not env-configurable.

# Durable browser-auth transition enforcement is mandatory. Terminal logout
# preparation remains a separate rollout switch.
AUTH_BROWSER_TERMINAL_PREPARATION_ENABLED=false

# Optional: zero-downtime JWT signing key rotation via `kid` header.
# JSON map of kid → secret string (each ≥32 chars).
# Example: {"2026-05":"<long-random>","2026-08":"<another-long-random>"}
# When set, JWT_SECRET is kept as a verify-only fallback for tokens minted
# before the keyring was deployed (those carry no `kid` header).
JWT_SIGNING_KEYRING=
# Required when JWT_SIGNING_KEYRING is set: which kid signs new tokens.
JWT_ACTIVE_KID=

# Auth/portal cookie policy (optional overrides)
# Valid SameSite values: Lax, Strict, None
# If SameSite=None is used, cookies are automatically marked Secure and require HTTPS.
# If using Lax/Strict in development, ensure browser app and API share the same site
# (for example, both use localhost rather than mixing localhost and an IP/hostname).
# COOKIE_SAME_SITE=Lax
# AUTH_COOKIE_SAME_SITE=Lax
# PORTAL_COOKIE_SAME_SITE=Lax
# Optional force-secure overrides for Lax/Strict cookies:
# COOKIE_FORCE_SECURE=false
# AUTH_COOKIE_FORCE_SECURE=false
# PORTAL_COOKIE_FORCE_SECURE=false

# Refresh-token rotation leeway, in seconds (#1107). Within this window after a
# refresh token is legitimately rotated, replaying the just-rotated token is
# treated as a benign concurrent race (multi-tab / heartbeat / page reload mid-
# refresh) instead of a reuse attack, so the browser is not logged out on a hard
# refresh. The replayed token still cannot mint anything. Set to 0 to restore
# strict, no-leeway reuse-detection. Default: 15.
# REFRESH_ROTATION_GRACE_SECONDS=15

# Agent enrollment secret (for device registration)
# Use: openssl rand -hex 32
# In production, agents must provide this during enrollment:
#   breeze-agent enroll <enrollment-key> --server https://your-server --enrollment-secret <AGENT_ENROLLMENT_SECRET>
# Or set: BREEZE_AGENT_ENROLLMENT_SECRET=<AGENT_ENROLLMENT_SECRET>
# Production startup rejects placeholder or short values when this is set.
# Use at least 32 random characters, for example: openssl rand -base64 32
AGENT_ENROLLMENT_SECRET=your-enrollment-secret-change-in-production
# Per-source-IP limit on agent enrollment (POST /api/v1/agents/enroll). Default:
# 10 per 60 seconds. Machines behind one NAT address share a single bucket, so
# raise this before rolling out a site with more than ~10 machines at once.
# AGENT_ENROLL_RATE_LIMIT=10
# AGENT_ENROLL_RATE_WINDOW_SECONDS=60

# Initial admin for a production database with no users. Leave blank after the
# bootstrap admin has logged in and completed setup. The API never logs this
# password. Generate a one-time value when needed:
#   BREEZE_BOOTSTRAP_ADMIN_PASSWORD="$(openssl rand -base64 32)"
BREEZE_BOOTSTRAP_ADMIN_EMAIL=
BREEZE_BOOTSTRAP_ADMIN_PASSWORD=
# BREEZE_BOOTSTRAP_ADMIN_NAME=Owner Admin

# --------------------------------------------
# Customer Microsoft 365 Graph-read onboarding (optional, OFF)
# --------------------------------------------
# The private executor is deliberately NOT deployed by this generic Compose
# stack. Run its separately released digest-pinned image in an environment
# that supplies managed/workload identity, private authenticated ingress, and
# controlled HTTPS egress to Key Vault, Microsoft identity, and Graph. Never
# expose it through Caddy or configure a plaintext executor URL.
# The identity-capable runtime must pin the executor image by digest and apply
# equivalents of: --read-only --cap-drop=ALL --security-opt=no-new-privileges
# --tmpfs /tmp:rw,noexec,nosuid,size=64m. Do not publish its container port.
# Image form: ghcr.io/lanternops/breeze/m365-graph-read-executor@sha256:<digest>
M365_CUSTOMER_GRAPH_READ_ONBOARDING_ENABLED=false
# Literal * or comma-separated Breeze organization UUIDs; leave empty while off.
M365_CUSTOMER_GRAPH_READ_ONBOARDING_ORG_IDS=
M365_CUSTOMER_GRAPH_READ_CLIENT_ID=
M365_CUSTOMER_GRAPH_READ_CALLBACK_URL=
M365_CUSTOMER_GRAPH_READ_CREDENTIAL_VERSION=
# akv://vault-host/m365-customer-graph-read/<32-lowercase-hex-version>
M365_CUSTOMER_GRAPH_READ_VAULT_REF=
# Required to be private HTTPS when enabled.
M365_GRAPH_READ_EXECUTOR_URL=
M365_GRAPH_READ_EXECUTOR_AUDIENCE=m365-graph-read-executor
M365_GRAPH_READ_EXECUTOR_SIGNING_KID=
# Host path to the API's Ed25519 private signing JWK. Standalone Compose cannot
# apply secret uid/gid/mode: provision the source with numeric owner 1001:1001 and mode 0400.
# It is mounted read-only at /run/secrets/m365_graph_read_executor_signing_private_jwk.
# The separately deployed executor receives only the matching PUBLIC JWK.
# Example when enabling: /path/to/m365-graph-read-api-signing-private.jwk
M365_GRAPH_READ_EXECUTOR_SIGNING_PRIVATE_JWK_SOURCE_FILE=
# Independent of M365_CUSTOMER_GRAPH_READ_ONBOARDING_ENABLED above; gates the
# six m365_query_* AI tools instead of connection onboarding. Enabling it
# still requires every executor descriptor above (it forces full executor
# config validation at boot).
M365_GRAPH_READ_TOOLS_ENABLED=false
# Literal * or comma-separated Breeze organization UUIDs; required when the
# flag above is enabled, leave empty while off.
M365_GRAPH_READ_TOOLS_ORG_IDS=

# ---- Microsoft 365 tenant sync (posture snapshots) ----------------------
# Gates EVERY sync entry point: the 60s ticker, consent seeding, and the
# on-demand sync route. Default false. Turning it on is the only rollout
# step — the ticker seeds state rows for existing executable connections
# itself, staggered over the first hour.
M365_TENANT_SYNC_ENABLED=false
# Per-API-instance concurrency for the sync-domain job.
M365_SYNC_CONCURRENCY=4
# Ticker backpressure ceiling (waiting+prioritized+delayed+active).
M365_SYNC_MAX_BACKLOG=500
# Rows claimed per 60s tick. This is the capacity dial: BATCH x 1440 slots
# per day should run at <= 50% utilisation (spec §5.9).
M365_SYNC_TICK_BATCH=200

# --------------------------------------------
# Customer Microsoft 365 Graph-actions (write) executor (optional, OFF)
# --------------------------------------------
# Same isolation model as the Graph-read executor above: this private executor
# is deliberately NOT deployed by this generic Compose stack. Run its
# separately released digest-pinned image in an environment that supplies
# managed/workload identity, private authenticated ingress, and controlled
# HTTPS egress to Key Vault, Microsoft identity, and Graph. Never expose it
# through Caddy or configure a plaintext executor URL.
# The identity-capable runtime must pin the executor image by digest and apply
# equivalents of: --read-only --cap-drop=ALL --security-opt=no-new-privileges
# --tmpfs /tmp:rw,noexec,nosuid,size=64m. Do not publish its container port.
# Image form: ghcr.io/lanternops/breeze/m365-graph-actions-executor@sha256:<digest>
# Onboarding the org-facing consent connection ("Customer Graph Actions" card).
# Independent of M365_GRAPH_ACTIONS_TOOLS_ENABLED below (that one gates the AI
# tools/headless execution instead) — enabling EITHER one forces full executor
# descriptor validation at boot, which in production also requires PUBLIC_URL,
# PUBLIC_APP_URL, or PUBLIC_API_URL to be set (used to derive the consent
# callback origin; boot refuses to start without one of them).
M365_CUSTOMER_GRAPH_ACTIONS_ONBOARDING_ENABLED=false
# Literal * or comma-separated Breeze organization UUIDs; required when the
# flag above is enabled, leave empty while off.
M365_CUSTOMER_GRAPH_ACTIONS_ONBOARDING_ORG_IDS=
# Gates the M365 write-action AI tools (mailbox rules, password reset, etc.)
# and headless release-worker execution of approved action_intents.
# Disabled by default. Enabling it also requires APP_ENCRYPTION_KEY_ID (see
# Server Configuration below) — without it, boot refuses to start, because the
# m365_reset_password reveal-secret path seals its temp credential with
# AAD-bound v3 ciphertext.
M365_GRAPH_ACTIONS_TOOLS_ENABLED=false
# Literal * or comma-separated Breeze organization UUIDs; leave empty while off.
M365_GRAPH_ACTIONS_TOOLS_ORG_IDS=
M365_CUSTOMER_GRAPH_ACTIONS_CLIENT_ID=
M365_CUSTOMER_GRAPH_ACTIONS_CREDENTIAL_VERSION=
# akv://vault-host/m365-customer-graph-actions/<32-lowercase-hex-version>
M365_CUSTOMER_GRAPH_ACTIONS_VAULT_REF=
# Required to be private HTTPS when enabled.
M365_GRAPH_ACTIONS_EXECUTOR_URL=
M365_GRAPH_ACTIONS_EXECUTOR_AUDIENCE=m365-graph-actions-executor
M365_GRAPH_ACTIONS_EXECUTOR_SIGNING_KID=
# Host path to the API's Ed25519 private signing JWK. Standalone Compose cannot
# apply secret uid/gid/mode: provision the source with numeric owner 1001:1001 and mode 0400.
# It is mounted read-only at /run/secrets/m365_graph_actions_executor_signing_private_jwk.
# The separately deployed executor receives only the matching PUBLIC JWK, plus
# its OWN M365_CUSTOMER_GRAPH_ACTIONS_CALLBACK_URL, which must byte-match the
# origin above + /api/v1/m365/actions-consent/callback (mismatch fails the
# identity-verification leg with identity_token_invalid). See
# docs/deploy/m365-customer-graph-actions-executor.md for the full executor env.
M365_GRAPH_ACTIONS_EXECUTOR_SIGNING_PRIVATE_JWK_SOURCE_FILE=

# M365 communications-delegated (per-USER axis; dark by default)
M365_COMMS_ONBOARDING_ENABLED=false
M365_COMMS_ONBOARDING_USER_IDS=
M365_COMMS_TOOLS_ENABLED=false
M365_COMMS_TOOLS_USER_IDS=
M365_COMMS_CLIENT_ID=
M365_COMMS_EXECUTOR_URL=https://comms-executor.internal/
M365_COMMS_EXECUTOR_AUDIENCE=m365-communications-executor
M365_COMMS_EXECUTOR_SIGNING_KID=
M365_COMMS_EXECUTOR_SIGNING_PRIVATE_JWK_FILE=/run/secrets/m365-comms-executor-signing.jwk

# --------------------------------------------
# Server Configuration
# --------------------------------------------
NODE_ENV=production
API_PORT=3001
WEB_PORT=4321

# Public URL for the API. Docker defaults this to https://${BREEZE_DOMAIN} for
# generated agent installers and shareable links. Override it only when agents
# must use a different externally reachable API URL.
# For cookie auth with SameSite=Lax/Strict, this must use the same site as the browser page URL.
PUBLIC_API_URL=
# Network Proxy dedicated tunnel origin (optional). Unset keeps path mode.
# Must be a DIFFERENT registrable domain from the app, e.g.
# TUNNEL_ORIGIN_TEMPLATE=https://{id}.us.tunnel.example.net
# TUNNEL_FRAME_ANCESTOR defaults to PUBLIC_APP_URL's origin.
# TUNNEL_ORIGIN_TEMPLATE=
# TUNNEL_FRAME_ANCESTOR=
# Legacy API URL fallback used by installer/share-link generation when PUBLIC_API_URL is unset.
API_URL=

# Customer portal (apps/portal) — served under a base path on the main domain
# (default /portal) via the Caddy carve-out, so it needs no dedicated hostname/cert.
# PORTAL_BASE_PATH is baked into the portal image at build time; keep it in sync
# with the Caddyfile carve-out (docker/Caddyfile.prod) and the build-arg.
PORTAL_BASE_PATH=/portal
# Public origin for portal links in outbound email (e.g. quote accept links).
# Defaults to https://${BREEZE_DOMAIN}/portal; falls back to PUBLIC_APP_URL if unset.
PUBLIC_PORTAL_URL=

# --------------------------------------------
# Production Deploy
# --------------------------------------------
# Domain and ACME config used by Caddy and deploy scripts
# Use "localhost" for local testing (Caddy generates a self-signed TLS cert;
# your browser will show a certificate warning — accept it to proceed).
# For production, set to your actual domain.
BREEZE_DOMAIN=localhost
ACME_EMAIL=admin@yourdomain.com
# Uncomment (value must be the literal `local_certs`) when BREEZE_DOMAIN is a domain
# Let's Encrypt cannot reach — internal-only DNS, or ports 80/443 closed to the
# internet — so Caddy issues from its internal CA instead of failing the ACME order
# and then aborting the TLS handshake (browsers show ERR_SSL_PROTOCOL_ERROR, not a
# clickable cert warning). Trust the root on each client to silence the warning:
#   docker compose exec caddy cat /data/caddy/pki/authorities/local/root.crt
# Leave empty for any internet-reachable deployment. Not needed for "localhost".
#CADDY_LOCAL_CERTS=local_certs

# --------------------------------------------
# Object Storage (S3/R2/MinIO)
# --------------------------------------------
# S3 is "soft-enabled" by the presence of S3_BUCKET. When S3_BUCKET is set in
# production, S3_ACCESS_KEY and S3_SECRET_KEY are REQUIRED — the API refuses to
# boot otherwise (Task 26 / audit H-3). Without this gate, the first upload
# request 5xxs at runtime instead of failing fast at startup.
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
S3_BUCKET=breeze
S3_REGION=us-east-1
# Presigned URL expiration (seconds). Default: 900 (15 minutes)
# S3_PRESIGN_TTL=900

# MinIO Console (when using local MinIO)
MINIO_API_PORT=9000
MINIO_CONSOLE_PORT=9001

# --------------------------------------------
# Email Configuration
# --------------------------------------------
# Required for password reset and notifications.
# EMAIL_PROVIDER:
#   - auto (default): use Resend, then SMTP, then Mailgun when configured
#   - resend: require RESEND_API_KEY + EMAIL_FROM
#   - smtp: require SMTP_HOST + SMTP_FROM (EMAIL_FROM can be used as fallback)
#   - mailgun: require MAILGUN_API_KEY + MAILGUN_DOMAIN (MAILGUN_FROM or EMAIL_FROM)
#
# In production (Task 26 / audit H-3): when EMAIL_PROVIDER explicitly selects a
# backend (resend/smtp/mailgun), the API refuses to boot if the corresponding
# secret is missing. 'auto' and unset stay in best-effort mode (no boot gate).
EMAIL_PROVIDER=auto
RESEND_API_KEY=
EMAIL_FROM=noreply@breeze.local
SMTP_HOST=
SMTP_PORT=587
SMTP_USER=
SMTP_PASS=
SMTP_FROM=noreply@breeze.local
SMTP_SECURE=false
MAILGUN_API_KEY=
MAILGUN_DOMAIN=
MAILGUN_BASE_URL=https://api.mailgun.net
MAILGUN_FROM=noreply@breeze.local

# Transport deadlines (#3905). Both are optional; the defaults below apply when
# unset. A malformed value is REJECTED at startup (the API reports email as not
# configured) rather than silently falling back — a transport with no bound is
# how a stalled mail server used to hold a send for ten minutes.
#
# SMTP_TIMEOUT_MS   connection + greeting + socket deadline for the SMTP
#                   transport. This is an INACTIVITY timeout, so it does not cap
#                   how long a large PDF attachment may take to upload.
# MAILGUN_TIMEOUT_MS whole-request deadline for the Mailgun API call. Larger,
#                   because it DOES include the multipart attachment upload.
# Range for both: 1000-600000 ms.
SMTP_TIMEOUT_MS=30000
MAILGUN_TIMEOUT_MS=120000

# --------------------------------------------
# Custom sender addresses / partner sending domains (optional)
# --------------------------------------------
# OFF by default. With EMAIL_DOMAINS_PROVIDER unset nothing changes: the
# settings tab is hidden, the routes 404, the worker is not registered, and
# every email is sent exactly as before. Upgrading never requires any of these.
#
# EMAIL_DOMAINS_PROVIDER picks HOW a sending domain is proven:
#   - unset  : feature off (default).
#   - static : you attest that this instance's mail relay may send as the
#              domains you list below. Use this on SMTP or Mailgun, where there
#              is no domain API for Breeze to check. SPF/DKIM for those domains
#              are YOUR mail setup; Breeze cannot verify them. A domain becomes
#              usable once a test send from it is accepted by the relay.
#   - resend : Breeze creates the domain in your Resend account and shows the
#              DKIM/SPF records to publish. Needs a full_access key — a
#              sending-only key cannot manage domains.
#   - fake   : deterministic test double. Refused in production.
#
# NOTE: this is the domain Breeze SENDS AS, which is not TICKETS_INBOUND_DOMAIN
# (what Breeze RECEIVES on) and not MAILGUN_DOMAIN.
EMAIL_DOMAINS_PROVIDER=
# `static` only. Comma-separated `domain` or `domain:partner-slug`. An unbound
# entry may be claimed by any partner on this instance, which is right for a
# single-partner install.
EMAIL_DOMAINS_STATIC_ALLOWED=
# `resend` only. full_access key of the account that holds partner domains. One
# account for both lanes is fine self-hosted; the trade-off is that partner
# domains then share your platform mail's sending reputation.
EMAIL_DOMAINS_RESEND_API_KEY=
# Optional sending_access key of the same account, so the send path never holds
# the management key. Falls back to EMAIL_DOMAINS_RESEND_API_KEY.
EMAIL_DOMAINS_RESEND_SENDING_KEY=
# Resend region for newly created domains: us-east-1, eu-west-1, sa-east-1, ap-northeast-1.
EMAIL_DOMAINS_REGION=us-east-1
# Sending domains one partner may hold.
EMAIL_DOMAINS_MAX_PER_PARTNER=3
# Partner-lane messages per partner per UTC day. 0 = unlimited (the self-hosted
# default). Over the cap a message goes out from EMAIL_FROM as it would today.
EMAIL_DOMAINS_DAILY_SEND_CAP=0
# Comma-separated partner ids. Empty means every eligible partner.
EMAIL_DOMAINS_PARTNER_ALLOWLIST=
# Extra domains nobody on this instance may add, comma-separated.
EMAIL_DOMAINS_DENYLIST=
# Delivery-webhook signing secret. Unset leaves the endpoint inert.
EMAIL_DOMAINS_WEBHOOK_SECRET=
# Automatic suspension of a partner's sending domains on poor deliverability.
# ON by default on hosted (0.08 / 50 / 3). OFF on a self-hosted instance until
# you UNCOMMENT at least one of the three — then the two you leave commented use
# the defaults shown. They ship commented out on purpose: any non-empty value
# reads as "the operator configured this" and turns auto-suspension on, so a
# copied example file must not quietly start suspending your only sending
# domain. Unsuspending is always manual (platform admin).
# 7-day bounce rate above this fraction suspends every domain of the partner.
# EMAIL_DOMAINS_AUTOSUSPEND_BOUNCE_RATE=0.08
# ...but only once the 7-day window holds at least this many messages.
# EMAIL_DOMAINS_AUTOSUSPEND_MIN_MESSAGES=50
# Spam complaints in 7 days that suspend regardless of the rate.
# EMAIL_DOMAINS_AUTOSUSPEND_COMPLAINTS=3

# --------------------------------------------
# Inbound Email-to-Ticket (native inbound address, via Mailgun)
# --------------------------------------------
# Optional. Powers the partner inbound address shown on Settings → Ticketing →
# Inbound email. Leave both unset to run without a native inbound address (the
# card will report that the platform inbound domain isn't configured); the
# Microsoft 365 shared-mailbox path below is independent of these.
#
# TICKETS_INBOUND_DOMAIN is the domain inbound ticket addresses live on — it is
# the domain Breeze RECEIVES on, and is NOT the same setting as MAILGUN_DOMAIN
# (which is what Breeze SENDS from), even when both name the same domain.
#
# MAILGUN_INBOUND_SIGNING_KEY is Mailgun's HTTP webhook SIGNING key (not
# MAILGUN_API_KEY). The inbound webhook is unauthenticated by design and relies
# solely on this HMAC, so while it is unset every delivery is rejected with 401.
#
# Also required, on the Mailgun side: add the domain as a RECEIVING domain,
# publish its MX records, and create a route forwarding to
#   https://<PUBLIC_URL>/api/v1/webhooks/tickets/email-inbound
# See https://docs.breezermm.com/deploy/environment/#inbound-email-to-ticket-mailgun
TICKETS_INBOUND_DOMAIN=
MAILGUN_INBOUND_SIGNING_KEY=
#
# INBOUND_QUEUE_MAX_PER_SEC caps how many inbound email jobs are PROCESSED per
# second across all senders (flood backpressure). Over-rate jobs are delayed by
# BullMQ, never dropped. Default 20/s; raise it for a high-volume tenant, lower it
# to slow a burst. Bounds the RATE of ticket creation, not the total.
INBOUND_QUEUE_MAX_PER_SEC=20

# --------------------------------------------
# Twilio Configuration (SMS MFA + SMS Alert Notifications)
# --------------------------------------------
TWILIO_ACCOUNT_SID=
TWILIO_AUTH_TOKEN=
TWILIO_VERIFY_SERVICE_SID=
TWILIO_MESSAGING_SERVICE_SID=
TWILIO_PHONE_NUMBER=

# --------------------------------------------
# AI Brain (BYOK - Bring Your Own Key)
# --------------------------------------------
# Optional: Provide your Anthropic API key to enable the AI assistant
ANTHROPIC_API_KEY=

# Self-hosted only: point the AI Agent at any Anthropic-compatible
# /v1/messages backend (local vLLM 0.23+, a LiteLLM gateway, etc.) while
# keeping full tool-use and the guardrails stack. Must be an http(s) URL.
# Fail-closed: honored ONLY when IS_HOSTED is explicitly false/0/no/off. If
# IS_HOSTED is true, unset, or invalid, the API boot-refuses this var and
# strips it from the AI subprocess (the platform must never route AI traffic to
# a third-party endpoint). Set ANTHROPIC_AUTH_TOKEN to the backend's bearer
# token instead of ANTHROPIC_API_KEY. With a LiteLLM gateway, alias
# claude-sonnet-5-5 → your backend model and leave ANTHROPIC_MODEL unset (the
# gateway must accept or drop adaptive thinking + effort, e.g. LiteLLM
# drop_params); for a raw vLLM endpoint, set ANTHROPIC_MODEL to the served model
# id (an unrecognised id is sent thinking disabled, as before). Note: an
# unrecognized model id is cost-tracked at Opus-tier DEFAULT_PRICING, not $0.
# IS_HOSTED=false
# ANTHROPIC_BASE_URL=http://localhost:8000
# ANTHROPIC_AUTH_TOKEN=
# ANTHROPIC_MODEL=
# AI chat tool loading: auto (default) uses tool search on the Anthropic API and
# sends every tool on a custom ANTHROPIC_BASE_URL / BYO provider; on = also use
# tool search through a gateway that forwards tool_reference blocks; off = always
# send every tool.
# AI_TOOL_SEARCH=auto

# --------------------------------------------
# Hardware Warranty Lookups (optional)
# --------------------------------------------
# The warranty worker looks each physical device's serial number up against its
# manufacturer so the device page and warranty-expiry alerts have real dates.
# Every vendor is OFF until configured; unconfigured vendors simply leave their
# devices at status "unknown". Apple coverage is reported by the macOS agent and
# needs nothing here.
#
# Dell — official TechDirect Warranty API. Register at https://techdirect.dell.com
# (API → Warranty), create an app, and paste its OAuth client credentials.
DELL_CLIENT_ID=
DELL_CLIENT_SECRET=
# Lenovo — either or both:
#   LENOVO_API_KEY: ClientID for Lenovo's official Warranty API
#     (supportapi.lenovo.com, issued through a Lenovo partner manager).
#   LENOVO_WARRANTY_ENABLED=true: no credential; uses the JSON endpoint behind
#     Lenovo's public warranty-lookup page. Undocumented by Lenovo, so it may
#     stop working without notice — hence opt-in. When both are set the
#     official API is authoritative and the public endpoint is only a fallback.
LENOVO_API_KEY=
LENOVO_WARRANTY_ENABLED=

# --------------------------------------------
# Agent control-plane migration
# --------------------------------------------
# Backup control-plane URL pushed to ALL agents via heartbeat (#2288).
# Agents fail over to it automatically (and permanently, keeping the old URL
# as rollback) after ~10 consecutive failed heartbeats to the primary.
# Must be https:// (http:// allowed only for localhost). Malformed values
# refuse to boot. Leave unset to clear any previously-pushed backup.
# Remember: also map this var in the api service `environment:` block of your
# docker-compose.yml — a value in .env alone is not interpolated.
# Migration playbook: docs/deploy/agent-server-url-migration.md
# AGENT_BACKUP_SERVER_URL=https://your-new-domain.example.com

# --------------------------------------------
# Bare-metal recovery media
# --------------------------------------------
# Scratch directory recovery bundle/ISO builds use for their working
# directory (a 45-65MB helper binary plus a tarball or ISO, per build). The
# api and worker containers mount /tmp as a 64MB tmpfs, so leaving this
# unset and building under the OS temp dir fails with ENOSPC (issue: D7).
# docker-compose.yml / deploy/docker-compose.prod.yml already default this
# to a `recovery-work` directory under the persistent api_data volume
# (/data/recovery-work) — override only if you want it somewhere else on
# durable storage. Already mapped in the api/worker `environment:` blocks;
# a value here alone would otherwise be silently inert.
# RECOVERY_MEDIA_WORK_DIR=/data/recovery-work
# Backup GC per-object grace in ms (default 48h). Lab/test knob only - never lower it on a real deployment.
# BACKUP_GC_GRACE_MS=
# Backup storage reclamation (D18). All optional, in ms; production enforces a floor on each.
# Already mapped in the api `environment:` block - a value here alone would otherwise be inert.
# BACKUP_BASE_LEASE_MS=604800000            # 7 d  - how long a dispatched job may publish against its pinned base (floor 2 h; the helper stops publishing 1 h before the deadline, so <= 1 h fails every backup)
# BACKUP_PUBLISH_MARGIN_MS=3600000          # 1 h  - safety margin before lease expiry at which the helper refuses to publish (floor 5 min)
# BACKUP_RESTORE_PIN_LINGER_MS=604800000    # 7 d  - how long a finished restore keeps its snapshot pinned (floor 1 h)
# BACKUP_GC_ORPHAN_MANIFEST_MAX_AGE_MS=777600000  # 9 d - age after which a manifest with no database row is reclaimed
# BACKUP_GC_MANIFESTLESS_PREFIX_MAX_AGE_MS=777600000  # 9 d - age after which an unfinished upload (prefix with no manifest) is reclaimed

# --------------------------------------------
# Breeze AI for Office (Excel add-in)
# --------------------------------------------
# Entra application (client) ID of the multi-tenant add-in app registration.
# Leave empty to disable the /client-ai surface entirely.
CLIENT_AI_ENTRA_CLIENT_ID=

# --------------------------------------------
# Encryption & Security Keys
# --------------------------------------------
# CRITICAL: Generate unique keys for production
# Use: openssl rand -hex 32
APP_ENCRYPTION_KEY=generate-a-random-hex-string-for-production
# Key id enabling AAD-bound v3 ciphertext (vs v1 with no AAD binding).
# Required for integration credential sealing; boot WARNS when unset (it does not
# refuse). Integration provider credentials
# (/integrations/{communication,monitoring,ticketing,psa}) are sealed with v3
# ciphertext bound to the provider, organization and field path and fail closed
# on v1, so saving one returns 503 until this is set. Everything else keeps
# working, so an existing install without it stays up.
# Required outright (boot refuses), in any environment, once
# M365_GRAPH_ACTIONS_TOOLS_ENABLED=true —
# the m365_reset_password reveal-secret path seals its temp credential with v3
# ciphertext and fails closed on v1 — and when BREEZE_ROLE is "api" or "worker".
# Any [A-Za-z0-9._-]+ identifier; changing it does not itself rotate
# APP_ENCRYPTION_KEY. scripts/guided-setup.sh generates key-YYYYMMDD on first
# run and never overwrites an existing value; set it by hand if you install
# without the guided script. To rotate, see docs/operations/SECRET_ROTATION.md.
APP_ENCRYPTION_KEY_ID=
MFA_ENCRYPTION_KEY=generate-a-random-hex-string-for-production
# Production startup rejects placeholder or short values when this is set.
# Leave unset to fall back to APP_ENCRYPTION_KEY, or set at least 32 random characters.
ENROLLMENT_KEY_PEPPER=generate-a-random-hex-string-for-production
MFA_RECOVERY_CODE_PEPPER=generate-a-random-hex-string-for-production
# Required in production for both BINARY_SOURCE=github and BINARY_SOURCE=local.
# - github: verifies installer fallback assets against the signed release manifest.
# - local:  anchors per-deployment update manifests; without a trust root, agents
#           accept unsigned manifests, defeating the agent-update trust chain.
# Comma-separate multiple raw base64 Ed25519 public keys during release-manifest
# signing key rotation.
# The value below is the trust anchor for the official Breeze GitHub releases.
# It is a PUBLIC key (also embedded in the agent and CI), so it is safe to ship.
# Leave it as-is unless you build and sign your own binaries.
RELEASE_ARTIFACT_MANIFEST_PUBLIC_KEYS=yzx8ftmcls6uBetFC5SYnZhBo+cbur3IX50TbBthTso=
# Default TTL (minutes) for newly created enrollment keys when expiresAt is not provided.
# 43200 = 30 days: downloaded installers are expected to keep working after being
# staged through deployment tooling, not just on the day of download.
ENROLLMENT_KEY_DEFAULT_TTL_MINUTES=43200
# Fresh TTL (minutes) given to a "child" enrollment key minted at installer-download,
# installer-link, or short-code redemption time. Measured from mint time, independent
# of the parent key's remaining lifetime.
CHILD_ENROLLMENT_KEY_TTL_MINUTES=43200
# Base TTL (minutes) for a freshly-issued installer bootstrap token when no explicit
# ttlMinutes is supplied. The token's own expiry -- not the parent enrollment key's --
# governs how long an installer has to complete enrollment.
# 10080 = 7 days (default). Maximum 43200 (30 days); a larger value is clamped to it,
# with a warning at API startup.
# Tokens already issued keep the expiry they were issued with.
INSTALLER_BOOTSTRAP_TOKEN_TTL_MINUTES=10080
# Minimum remaining lifetime (seconds) a parent enrollment key must have to be used as
# an installer source. Guards against building an installer from a parent that expires
# before the download reaches the target machine.
INSTALLER_PARENT_MIN_REMAINING_SECONDS=60
# Set to false to disable the daily sweep that purges expired enrollment keys.
ENROLLMENT_KEY_CLEANUP_ENABLED=true
# Grace period (days past expiry) before an expired enrollment key is purged by the
# daily sweep.
ENROLLMENT_KEY_PURGE_AFTER_DAYS=7
# Maximum TTL (minutes) a Partner API caller may request for an enrollment key.
# Applies to both ttlMinutes and expiresAt. May only NARROW the built-in
# 365-day ceiling, never widen it. Leave unset for that 365-day ceiling; the
# example below is a 7-day operator cap.
PARTNER_API_ENROLLMENT_KEY_MAX_TTL_MINUTES=10080
# Dedicated per-service-principal mint limit per hour. Default: 10.
PARTNER_API_ENROLLMENT_KEY_WRITE_RATE_LIMIT=10
# Partner-wide mint limit per hour, charged alongside the per-principal bucket.
# A partner admin can create service principals, so a per-principal limit alone
# is multiplied by however many they create. Default: 100.
PARTNER_API_ENROLLMENT_KEY_WRITE_PARTNER_RATE_LIMIT=100
# Hourly ceiling for Partner API TICKET writes (POST/PATCH under
# /partner-api/tickets) per service principal + key, in its own bucket so a
# PSA/ITSM mirror never spends the 120/hour provisioning write budget. Always
# capped by the key's own rate limit. Default: 1200.
PARTNER_API_TICKET_WRITE_RATE_LIMIT_PER_HOUR=1200
# Partner-wide ceiling for the same writes, charged after the per-principal
# bucket. A partner admin can create service principals, so a per-principal
# limit alone is multiplied by however many they create. Default: 6000.
PARTNER_API_TICKET_WRITE_PARTNER_RATE_LIMIT_PER_HOUR=6000
# Daily sweep that reaps X-Idempotency-Key claims of Partner API ticket writes
# once they are older than the retry window. Set to false to disable.
PARTNER_API_IDEMPOTENCY_RETENTION_ENABLED=true
# Days a ticket-write idempotency claim is kept; a retry with an old key after
# this window is a fresh request. Default: 7.
PARTNER_API_IDEMPOTENCY_RETENTION_DAYS=7
# Ticket migration windows (#8313): the time box an admin may give one import,
# in days (a longer migration opens a new window). Default: 14.
MIGRATION_WINDOW_MAX_DAYS=14
# Import writes per hour a new window gets when the admin sets none, and the
# most an admin may set. The floor is 600. Defaults: 6000 and 20000.
MIGRATION_WINDOW_DEFAULT_WRITES_PER_HOUR=6000
MIGRATION_WINDOW_MAX_WRITES_PER_HOUR=20000

# --------------------------------------------
# CORS Configuration
# --------------------------------------------
# Comma-separated list of allowed origins for CORS.
# Include scheme + hostname + port (for example, http://localhost:4321).
# In production, default localhost origins are excluded unless CORS_INCLUDE_DEFAULT_ORIGINS=true.
CORS_ALLOWED_ORIGINS=https://app.yourdomain.com
# CORS_INCLUDE_DEFAULT_ORIGINS=true  # Uncomment to re-include localhost origins in production

# --------------------------------------------
# Portal State Backend
# --------------------------------------------
# Set to 'redis' for production deployments. Defaults to in-memory for development.
# In production (NODE_ENV=production), Redis is used automatically.
# PORTAL_STATE_BACKEND=redis

# --------------------------------------------
# MCP Server Configuration
# --------------------------------------------
# Rate limits for MCP API endpoints (per API key, per minute)
# MCP_SSE_RATE_LIMIT_PER_MINUTE=30
# MCP_MESSAGE_RATE_LIMIT_PER_MINUTE=120
# Max concurrent SSE sessions per API key (defense-in-depth against leaked keys)
# MCP_MAX_SSE_SESSIONS_PER_KEY=5
# tools/list: 0/unset = single page; set to e.g. 50 once every connected client honours nextCursor.
# MCP_TOOLS_LIST_PAGE_SIZE=0
# Optional hardening: require `ai:execute_admin` scope (in addition to `ai:execute`) for Tier 3 tools in production
# MCP_REQUIRE_EXECUTE_ADMIN=true
# Comma-separated list of tool names allowed for Tier 3+ (destructive/sensitive) operations in production.
# Empty or unset = deny all. Use '*' to allow all (not recommended).
# Tier 3 includes: computer_control, take_screenshot, analyze_screen, execute_command,
# security_scan, s1_isolate_device, network_discovery, apply_cis_remediation, and others.
# Screen-capture tools (take_screenshot, analyze_screen) are Tier 3 because screen
# contents may include credentials, customer data, or other sensitive output.
# MCP_EXECUTE_TOOL_ALLOWLIST=run-script,restart-service
# Operator opt-in (default: nobody). Comma-separated principals allowed to run Tier 3 tools over
# MCP WITHOUT interactive approval: `api_key:<api key id>`, `oauth_client_user:<OAuth client_id>/<user id>`
# or `partner_sp:<partner service principal id>`.
# Only removes the MCP_APPROVAL_REQUIRED deny for those principals; ai:execute, ai:execute_admin,
# the allowlist above, RBAC, the Tier 3 execution ledger and audit logging still apply. Tier 4,
# tenant (BYO MCP) and bootstrap tools stay approval-only. For trusted unattended agents only.
# MCP_UNATTENDED_TIER3_PRINCIPALS=

# --------------------------------------------
# WebRTC / Remote Desktop (TURN Server)
# --------------------------------------------
# Required for remote desktop to work across NATs and firewalls.
# TURN_HOST must be the public IP of the TURN server (not a domain behind Cloudflare).
# If Breeze runs behind Cloudflare Tunnel, deploy TURN on a separate VPS
# and point TURN_HOST to that VPS's public IP. See docs: /deploy/turn-server/
# Use: openssl rand -hex 32 to generate TURN_SECRET
#
# Leave these blank if you are not using remote desktop — the stack starts fine
# without them. Only the opt-in `turn` profile needs TURN_SECRET, and coturn
# refuses to start on an empty one rather than running as an open relay.
TURN_HOST=
TURN_PORT=3478
TURN_SECRET=
TURN_REALM=breeze.local
TURN_CREDENTIAL_TTL_SECONDS=600
TURN_MAX_BPS=5000000
#
# TURN over TLS (turns: on 5349) — optional, off by default.
# Needed for clients on networks that block UDP or allow only a short list of
# TCP ports. Leave both unset to keep plain turn: on 3478 only.
#
# TURN_TLS_DIR: host directory holding `cert.pem` + `privkey.pem`, bind-mounted
#   read-only into the bundled coturn at /etc/coturn/tls. coturn drops to uid
#   65534 (`nobody`), so the pair must be readable by that uid — Caddy writes
#   its certificate `0600 root`, so copy it to a staging directory at 0640
#   rather than mounting Caddy's directory. coturn reads the certificate once at
#   startup and never reloads it: restart (or SIGHUP) coturn on every renewal,
#   or TURNS breaks silently ~60 days in.
# TURN_TLS_HOST: the hostname ON the certificate. The API advertises
#   `turns:${TURN_TLS_HOST}:${TURN_TLS_PORT}?transport=tcp` only when this is
#   set — TURN_HOST is a bare IP and would fail certificate validation.
# TURN_TLS_PORT: defaults to 5349.
# TURN_TLS_DIR=/opt/breeze/coturn-tls
# TURN_TLS_HOST=turn.your-domain.example.com
# TURN_TLS_PORT=5349
# Enable the TURN profile so coturn starts with `docker compose up -d`:
# COMPOSE_PROFILES=turn

# --------------------------------------------
# Storage & Remote Sessions
# --------------------------------------------
# Caps to prevent remote session resource exhaustion (set to 0 to disable)
MAX_ACTIVE_REMOTE_SESSIONS_PER_ORG=10
MAX_ACTIVE_REMOTE_SESSIONS_PER_USER=5
PATCH_REPORT_STORAGE_PATH=./data/patch-reports
# Days a generated patch compliance report file is kept before it is removed (minimum 1).
PATCH_REPORT_RETENTION_DAYS=30

# --------------------------------------------
# Monitoring & Metrics
# --------------------------------------------
METRICS_SCRAPE_TOKEN=generate-a-random-token-for-production
# Redact org IDs from Prometheus labels in production by default (set to true to include).
METRICS_INCLUDE_ORG_ID=false
# Optional: restrict /metrics/scrape by trusted client IP(s).
# Note: this needs a trusted client IP — see TRUST_PROXY_HEADERS below (on by
# default for the bundled stack; off means this matches the proxy, not clients).
METRICS_SCRAPE_IP_ALLOWLIST=
# Grafana credentials (used by docker-compose monitoring stack)
GRAFANA_ADMIN_USER=admin
GRAFANA_ADMIN_PASSWORD=changeme

# Event-loop lag monitor. On by default; these are tuning knobs, not requirements.
# It is what makes a stalled main thread visible as a stall instead of as a
# misleading Postgres "write CONNECT_TIMEOUT". Disabling it downgrades every
# CONNECT_TIMEOUT diagnosis to "unknown".
# EVENT_LOOP_MONITOR_INTERVAL_MS=1000
# EVENT_LOOP_STARVATION_WARN_MS=1000
# EVENT_LOOP_MONITOR_DISABLED=

# Agent admission control. When the API's event loop or its database pool falls
# behind, refuse low-priority agent telemetry with 503 + Retry-After before it
# costs anything, and pace agent WebSocket reconnects. Heartbeats and recovery
# traffic are never refused. observe (default) only measures and counts;
# enforce refuses; off disables it.
# BREEZE_ADMISSION_MODE=observe
# BREEZE_ADMISSION_LAG_MS=100,250,600
# BREEZE_ADMISSION_DB_WAIT_MS=75,200,600
# BREEZE_ADMISSION_EMERGENCY_MS=1000
# BREEZE_ADMISSION_BULK_MAX_IN_FLIGHT=15
# BREEZE_ADMISSION_WS_RATE_PER_SEC=10
# BREEZE_ADMISSION_WS_BURST=20
# BREEZE_ADMISSION_WS_MAX_SETUPS=8

# Database pool-health watchdog. On by default; these are tuning knobs.
# postgres.js can leave a pooled connection permanently unable to reconnect once
# its socket dies with a buffered write, producing a storm of "write
# CONNECT_TIMEOUT" errors against a database that is perfectly healthy. The pool
# cannot self-heal — only an API restart recovers it. When the CONNECT_TIMEOUT
# rate breaches the threshold below, the watchdog opens ONE brand-new connection
# to the same database to tell the two cases apart: if that succeeds the pool is
# at fault, if it fails too the database is. Exposed as breeze_db_pool_health and
# breeze_db_connect_timeout_rate_per_min on /metrics.
# DB_POOL_HEALTH_INTERVAL_MS=60000
# DB_POOL_HEALTH_WINDOW_MS=300000
# DB_POOL_HEALTH_MIN_TIMEOUTS=10
# DB_POOL_HEALTH_PROBE_TIMEOUT_MS=5000
# DB_POOL_HEALTH_CAPTURE_THROTTLE_MS=900000
# DB_POOL_HEALTH_DISABLED=

# Redis memory watchdog (#6452). On by default; these are tuning knobs.
# Redis runs `noeviction` by contract — a full instance fails writes loudly
# instead of silently evicting data — but nothing observed memory before this,
# so the first signal was a failed login or a stuck queue. Polls `INFO memory`
# on an interval and warns (console + Sentry, throttled) once used_memory
# crosses the ratio below, so REDIS_MAXMEMORY can be raised (or the instance
# force-recreated) ahead of an incident. Exposed as breeze_redis_used_memory_bytes,
# breeze_redis_maxmemory_bytes and breeze_redis_memory_used_ratio on /metrics.
# REDIS_MEMORY_MONITOR_INTERVAL_MS=60000
# REDIS_MEMORY_WARN_RATIO=0.8
# REDIS_MEMORY_CAPTURE_THROTTLE_MS=900000
# REDIS_MEMORY_MONITOR_DISABLED=

# --- #6048: wedged GUC-prologue connections -------------------------------
# A pooled connection can get stuck mid-way through the RLS GUC prologue with
# the backend in state=active / wait_event=ClientRead. No server-side timeout
# reaches that state (it is not executing, and it is not idle-in-transaction)
# and no postgres.js timer reaches it either (they only recycle connections
# that return to the idle pool), so the slot is lost for the life of the
# process. Both prod regions lost one for three days on 2026-09-13.
#
# Client-side deadline on the single set_config statement (all seven GUCs)
# ONLY — the caller's own work that follows is never bounded by it. 0
# disables; positive values below 1000 are clamped to 1000.
# DB_ACCESS_CONTEXT_PROLOGUE_TIMEOUT_MS=15000
#
# The prologue clock starts once the pool has handed over a connection; the
# wait for a pool slot is bounded separately (#8229). postgres.js has no
# acquire timeout of its own, so without this a request queued behind a
# saturated pool waits forever. Expiry raises DbPoolAcquireTimeoutError and
# requests no reclaim pass (nothing is wedged, every connection is busy).
# 0 disables; positive values below 1000 are clamped to 1000.
# Default 10000 so acquire + prologue (+ two lag graces) = 29 s stays under the
# agent's 30 s HTTP timeout for a request that opens one DB context. A nested
# escalation (withResolvedDbAccessContext / runOutsideDbContext) opens another
# and gets its own acquire + prologue budget on top. A request still waiting
# for a permit when it expires never reaches the database (#8143).
# DB_POOL_ACQUIRE_TIMEOUT_MS=10000
#
# When a pool-acquire or prologue timer fires at least 1 s late (the event loop
# was stalled), it gets this one extra grace period before failing the request,
# so a reply that arrived during the stall is not thrown away (#8143). 0
# disables; capped at 10000.
# DB_TIMER_LAG_GRACE_MS=2000
#
# Detector: periodic pg_stat_activity scan for backends stuck in that state.
# When a wedged backend is an RLS prologue set_config('breeze.…') statement
# at least 5 minutes old, the detector also requests a reclaim pass (below),
# with all of the reclaimer's safety bounds (#6348). Set
# DB_WEDGED_BACKEND_SCANNER_RECLAIM_DISABLED for detector-reports-only.
# DB_WEDGED_BACKEND_SCAN_DISABLED=
# DB_WEDGED_BACKEND_SCAN_INTERVAL_MS=300000
# DB_WEDGED_BACKEND_MIN_AGE_MS=300000
# DB_WEDGED_BACKEND_SCANNER_RECLAIM_DISABLED=
#
# Reclaimer: when a transaction abandoned by its prologue deadline still holds
# its pool permit one more prologue budget plus ~1 s later, terminates the
# wedged backend from a fresh side connection (same-role pg_terminate_backend) so the socket
# closes and the pool slot is reconnected. Only ever signals a backend that two
# consecutive snapshots agree has not moved. Set DB_WEDGED_BACKEND_RECLAIM_DISABLED
# for detection without termination.
# DB_WEDGED_BACKEND_RECLAIM_DISABLED=
# DB_WEDGED_BACKEND_RECLAIM_MIN_INTERVAL_MS=60000
# DB_WEDGED_BACKEND_RECLAIM_MAX_PER_PASS=4
# DB_WEDGED_BACKEND_RECLAIM_TIMEOUT_MS=5000
# DB_WEDGED_BACKEND_CONFIRM_DELAY_MS=250

# Platform-operator signup-abuse detection and its alerts.
#
# NOT all-or-nothing on being unset: ABUSE_SIGNALS_ENABLED defaults to the value
# of IS_HOSTED, so leaving it unset ENABLES the whole detection subsystem on a
# hosted install and disables it on a self-hosted one. Every OTHER variable in
# this block is optional and unset = that piece disabled.
#
# Signup-abuse detection polices UNTRUSTED PUBLIC SIGNUPS on a multi-tenant
# hosted service. On a normal self-hosted install — one IT team, its own
# machines, no signup funnel — most of these heuristics are noise or actively
# wrong, which is why the default follows IS_HOSTED. Set it explicitly only to
# override that: true to opt a self-hosted multi-tenant service in, false to
# switch a hosted deployment off. Must be a boolean (true/false, 1/0, yes/no,
# on/off) — the API refuses to boot on anything else, so a typo cannot silently
# turn detection off.
# ABUSE_SIGNALS_ENABLED=true
# OPS_ALERT_WEBHOOK_URL=https://discord.com/api/webhooks/your-webhook
# OPS_ALERT_EMAIL=ops@your-domain.example.com
# OPS_ALERT_LABEL=US
# ABUSE_SIGNAL_OVERRIDES={"rmm.enrollment_velocity.devices_24h": 25}
# Script-content detector indicator lists (unset = empty lists; the repo
# deliberately ships no indicators).
# ABUSE_SCRIPT_INDICATORS={"tlds": [], "hosts": []}
# Durable event dispatch (wave 3.5c, #4085).
#
# Governs how events (AI agent and automation triggers, DNS threat alerts,
# notifications, policy alerts, webhook deliveries) reach their subscribers:
#   off     - today's behavior: in-process delivery only (default).
#   shadow  - mirror routing plans into event_delivery_receipts for
#             observability, but still execute nothing via the queue.
#   enforce - subscribers listed in EVENT_DISPATCH_QUEUE_SUBSCRIBERS deliver
#             via BullMQ ONLY (in-process delivery is skipped for them);
#             every other subscriber keeps delivering in-process.
# Must be off/shadow/enforce (or unset) — the API refuses to boot on anything
# else, so a typo can never silently change delivery. Unrecognized values are
# ALSO not silently treated as "on" at runtime; see eventDispatchMode() in
# config/env.ts.
# EVENT_DISPATCH_MODE=off
#
# Comma-separated subscriber ids to route via the queue when
# EVENT_DISPATCH_MODE=enforce (ignored otherwise). Known ids are declared in
# services/eventSubscriberIds.ts: ai-agent-alert-verdict, ai-agent-anomaly,
# ai-agent-ticket-helpdesk, automation-worker, dns-threat-alerts,
# notification-dispatcher, policy-alert-bridge, webhook-delivery. Unknown ids
# are rejected at boot. Naming a subscriber selects durable queue delivery;
# it does not enable or disable the feature behind that subscriber.
# EVENT_DISPATCH_QUEUE_SUBSCRIBERS=webhook-delivery,notification-dispatcher

# Enforcement gate for fail-closed Stripe Checkout session revocation.
#   enforce (DEFAULT) - a transition that cannot prove every open Checkout
#             session for the invoice is dead is REFUSED (503
#             STRIPE_REVOCATION_PENDING). The durable intent survives the
#             refusal and the 60s sweep retries, so the refusal is bounded.
#   observe - the intent is still written and Stripe is still called, but a
#             failure never blocks the transition. This is the incident
#             de-escalation lever.
# Rollback is a flip to `observe`, NEVER a migration revert: code that ignores
# revocation_requested re-opens the finding and strands the intent rows.
# An unrecognized value falls back to enforce with a warning — a typo must never
# silently unlock the fail-open path. See stripeSessionRevocationMode() in
# config/env.ts.
# STRIPE_SESSION_REVOCATION_MODE=enforce

# Process role for the 3.5d socket/worker split (wave 3.5b, #4084; compose
# wiring wave 3.5d-b, #4086). Unset (or 'all') = today's all-in-one process.
# 'worker' disables socket-local agent dispatch (agentWs
# sendCommandToAgent/isAgentConnected throw instead of silently reporting
# every agent offline) — do not set this until the 3.5d rollout actually
# splits processes. The API process itself still reads BREEZE_ROLE, but a
# bare BREEZE_ROLE set here is NOT mapped by either compose file's
# x-api-env anchor — it is not settable directly. Use BREEZE_API_ROLE below
# for the api container; the worker container's role is always hardcoded.

# BREEZE_API_ROLE=all — role for the api container (all|api); the worker
# container in docker-compose.yml is always hardcoded to BREEZE_ROLE=worker,
# so this can never accidentally change it. Enable the worker container with:
# docker compose --profile worker-split up -d
# See docs/deploy/worker-split.md for the rollout/rollback runbook.
# BREEZE_API_ROLE=all

# Hostname prefixes attributed to abusive hosting, matched against device
# hostnames (unset = empty list; the repo deliberately ships no indicators,
# since publishing a prefix just tells an operator which string to rename).
# ABUSE_HOSTNAME_INDICATORS={"prefixes": []}

# --------------------------------------------
# Application URLs
# --------------------------------------------
# Used for links in emails and notifications
# For Docker deployment, use your BREEZE_DOMAIN with https
DASHBOARD_URL=https://breeze.yourdomain.com
PUBLIC_APP_URL=https://breeze.yourdomain.com

# Self-hosted documentation origin for the in-app Help panel (the slide-out docs
# iframe). Leave UNSET to use the hosted Breeze docs (which are only embeddable
# on Breeze-owned domains). Set this to the origin of a docs site you control and
# have configured to allow framing from your app domain (i.e. its frame-ancestors
# / X-Frame-Options permits PUBLIC_APP_URL). When set, the app rebases docs links
# onto this origin, widens the CSP frame-src to it, and treats your custom app
# origin as embed-eligible so the Help panel renders inline instead of falling
# back to "open in a new tab". Build-time constant — changing it requires a web
# rebuild.
# PUBLIC_DOCS_URL=https://docs.yourdomain.com

# --------------------------------------------
# Proxy Configuration
# --------------------------------------------
# The API only believes X-Forwarded-For / CF-Connecting-IP when the request's
# immediate TCP peer matches TRUSTED_PROXY_CIDRS. Headers arriving from any
# other peer are ignored, so a CIDR that matches nothing trusts nothing — it
# fails closed, it never opens a hole.
#
# The defaults below match the bundled `docker compose up` stack: it ships a
# Caddy in front of the API and pins it to a known address on the `breeze`
# network, so the API can trust that one hop and see real client IPs out of the
# box. deploy/docker-compose.prod.yml is configured the same way.
#
# Pick ONE of the three setups:
#
# 1) Using the bundled Caddy service (docker-compose.yml) — the shipped
#    default; nothing to change. Caddy is pinned via BREEZE_CADDY_IP, and
#    TRUSTED_PROXY_CIDRS follows it automatically:
#      TRUST_PROXY_HEADERS=true
#      TRUSTED_PROXY_CIDRS=172.31.0.10/32
#
# 2) Fronting the API with your OWN reverse proxy (nginx, Traefik, a
#    different Caddy, etc.) instead of the bundled one — point the CIDR at the
#    address the API sees as the TCP peer (your proxy's container/host IP),
#    NOT the original client's IP:
#      TRUST_PROXY_HEADERS=true
#      TRUSTED_PROXY_CIDRS=<your-proxy-peer-ip>/32
#    Leaving the bundled default in place is safe but useless: your proxy's
#    peer address won't match, so no headers are trusted and you land in the
#    degraded state described in (3).
#
# 3) Running the API with NO proxy in front (direct exposure) — turn trust off
#    so the API uses the raw socket peer, which is the real client:
#      TRUST_PROXY_HEADERS=false
#
# What "no trusted client IP" costs you (setup 3, or a misconfigured 1/2):
#   - Partner IP allowlists (dashboard "Admin IP allowlist") FAIL CLOSED and
#     deny all access. The dashboard refuses to let you enable one in this
#     state, so you cannot lock yourself out by accident — but the feature is
#     unavailable. Break glass with IP_ALLOWLIST_ENFORCEMENT_MODE=off.
#   - Auth rate limits (registration, invites, email verification, password
#     reset) key off the TCP peer. Behind an untrusted proxy that peer is the
#     PROXY for every request, so all users share ONE instance-wide bucket and
#     legitimate users throttle each other. Direct exposure is unaffected:
#     the socket peer is the real client.
# Neither degradation is spoofable by an attacker — that is the point. Trust
# is what buys you per-client granularity, and it is only ever granted to a
# peer address you name yourself.
TRUST_PROXY_HEADERS=true
# Redirect HTTP requests to HTTPS at the API layer. Caddy normally handles this
# in Docker production, but the API still receives the explicit value.
FORCE_HTTPS=true
# Comma-separated CIDR list. Only requests from these source IPs are allowed
# to set X-Forwarded-For / CF-Connecting-IP headers that the API will trust.
# Required (non-empty) in production whenever TRUST_PROXY_HEADERS=true.
# Defaults to the bundled Caddy hop, and tracks BREEZE_CADDY_IP if you move it.
# Example for a Cloudflare-fronted deploy: TRUSTED_PROXY_CIDRS=173.245.48.0/20,103.21.244.0/22
# (Do NOT set 0.0.0.0/0 or broad RFC1918 ranges — the validator rejects those.)
TRUSTED_PROXY_CIDRS=172.31.0.10/32
# Trust the CF-Connecting-IP header for the real client IP. Set to true ONLY
# when this deployment is genuinely fronted by Cloudflare (which overwrites the
# header at its edge). A non-Cloudflare reverse proxy — including the bundled
# Caddy — does NOT strip CF-Connecting-IP, so trusting it without a Cloudflare
# front would let a client spoof the header to choose its own rate-limit bucket
# or defeat a partner IP allowlist. Off by default; X-Forwarded-For (managed by
# your proxy) is used instead. Leave unset unless you front Breeze with Cloudflare.
TRUST_CF_CONNECTING_IP=false

# Docker network layout for the bundled stack. Leave these commented unless the
# default range clashes with something already on the host — both this default
# and deploy/docker-compose.prod.yml's 172.30.0.0/24 sit inside Docker's
# default bridge pool (172.17.0.0/12), so a host that has already
# auto-allocated the range needs a subnet outside it.
#
# If you uncomment BREEZE_CADDY_IP, keep it inside BREEZE_DOCKER_SUBNET and
# update TRUSTED_PROXY_CIDRS above to match — otherwise the API stops
# recognising Caddy and silently falls into the degraded state described there.
#BREEZE_DOCKER_SUBNET=172.31.0.0/24
#BREEZE_CADDY_IP=172.31.0.10

# --------------------------------------------
# Admin IP allowlist (partner-level)
# --------------------------------------------
# Break-glass switch for the partner dashboard IP allowlist. Default 'enforce'.
# Set to 'off' to globally disable enforcement (e.g. if an allowlist locks
# everyone out, or if proxy trust breaks after an allowlist was enabled and the
# allowlist starts denying everyone). The allowlist only acts when a partner has
# configured one AND the API can see real client IPs (requires
# TRUST_PROXY_HEADERS + a TRUSTED_PROXY_CIDRS that matches your actual proxy);
# without one it FAILS CLOSED and denies all access rather than waving requests
# through unchecked.
# Only 'enforce', 'off', or an empty/whitespace-only value (= unset, meaning
# 'enforce') are accepted. The API refuses to start on anything else rather than
# silently enforcing while you believe enforcement is disabled.
IP_ALLOWLIST_ENFORCEMENT_MODE=enforce

# Guided setup fills these when using an external reverse proxy instead of the
# packaged Caddy service. The generated docker-compose.yml consumes only the
# bind/port values: BREEZE_PROXY_BIND_HOST, BREEZE_API_HOST_PORT, and
# BREEZE_WEB_HOST_PORT.
#
# The remaining BREEZE_EXTERNAL_PROXY* values are setup bookkeeping used for
# generated reverse-proxy guidance. BREEZE_EXTERNAL_PROXY_CIDRS is copied into
# TRUSTED_PROXY_CIDRS, which is what the API reads when trusting real client IP
# headers from an external proxy.
BREEZE_EXTERNAL_PROXY=
BREEZE_PROXY_TARGET_HOST=
BREEZE_PROXY_BIND_HOST=
BREEZE_API_HOST_PORT=3001
BREEZE_WEB_HOST_PORT=4321
BREEZE_EXTERNAL_PROXY_CIDRS=
# Caddy only trusts these upstream proxy hops when deriving client IPs.
CADDY_TRUSTED_PROXIES=127.0.0.1/32 ::1/128
CADDY_CLIENT_IP_HEADERS=CF-Connecting-IP X-Forwarded-For
# Bind WebSocket session-ticket consumption to the issuer's IP. Default true.
# Set false only if your network topology causes legitimate IP changes between
# the ticket-issue and ticket-consume HTTPS requests (rare, ~60s window).
# UA-hash binding is always enforced regardless of this setting.
WS_TICKET_BIND_IP=true

# --------------------------------------------
# Logging & Monitoring
# --------------------------------------------
LOG_LEVEL=info
# Set to true for JSON structured logs
LOG_JSON=false

# Agent diagnostic log retention. `agent_logs` rows older than this are pruned
# daily by the agent-log-retention worker. Default 7, clamped to 1..365.
#
# Redaction of agent logs happens at INGEST and on read, never as a backfill, so
# rows captured before a redaction fix shipped keep whatever they captured until
# they age out of this window. If you have widened this for diagnostic history,
# that self-clearing property no longer holds and a targeted purge of pre-fix
# rows is the right move instead (#3109).
# AGENT_LOG_RETENTION_DAYS=7
# AGENT_LOG_RETENTION_BATCH_SIZE=10000
# AGENT_LOG_RETENTION_MAX_BATCHES=200

# AI invocation ledger (ai_invocations) retention. The table is append-only; a
# daily worker deletes rows older than this window as breeze_audit_admin.
# Default 400 days, capped at 3650. Aggregate for chargeback before rows age out.
# AI_INVOCATIONS_RETENTION_DAYS=400
# AI_INVOCATIONS_RETENTION_BATCH_SIZE=5000
# AI_INVOCATIONS_RETENTION_MAX_BATCHES=200

# LLM egress audit (llm_egress_events) retention. Raw per-request rows older
# than this window are folded into per-org daily summaries
# (llm_egress_daily_rollups, kept until the org is erased) and deleted.
# Default 90 days, capped at 3650.
# LLM_EGRESS_EVENTS_RETENTION_DAYS=90
# LLM_EGRESS_EVENTS_RETENTION_BATCH_SIZE=5000
# LLM_EGRESS_EVENTS_RETENTION_MAX_BATCHES=200

# --------------------------------------------
# Sentry Error Tracking
# --------------------------------------------
SENTRY_DSN=
# Sentry's `environment` dimension. In a MULTI-REGION deployment this MUST be
# region-qualified — `production-us`, `production-eu`, … — not a bare
# `production`. Every deployment reporting the same value makes regions
# indistinguishable in Sentry: `server_name` is a per-deploy container hash, so
# with a shared `production` there is no dimension left to attribute an error,
# a spike or a regression to a region, and no way to filter one out.
# Single-region and self-hosted deployments can leave `production` as-is.
SENTRY_ENVIRONMENT=production
SENTRY_RELEASE=
SENTRY_TRACES_SAMPLE_RATE=0.1

# Web (Astro) — separate Sentry project. Optional: leave blank to disable.
# Captures unhandled errors + session replay (replay only fires when an error occurs).
# Replay masks all text + inputs and blocks media by default. URLs are scrubbed of
# UUIDs/hashes before send. See apps/web/sentry.client.config.ts.
PUBLIC_SENTRY_DSN_WEB=
# Optional: send SSR/server errors to a different Sentry project than the
# browser DSN above. Defaults to PUBLIC_SENTRY_DSN_WEB when unset.
SENTRY_DSN_WEB_SERVER=
# Optional: explicit release tag for the web bundle (CI build stamps this).
# Falls back to PUBLIC_APP_VERSION at runtime in the browser when unset.
PUBLIC_RELEASE_VERSION=
# Optional: smoke endpoint /api/sentry-smoke (404 unless this is 1 OR build
# mode is production). Useful for verifying SSR error capture in dev.
ENABLE_SENTRY_SMOKE=
# Optional: source maps upload at build time.
SENTRY_ORG=
SENTRY_PROJECT=
SENTRY_AUTH_TOKEN=

# --------------------------------------------
# Session Configuration
# --------------------------------------------
SESSION_SECRET=another-secret-for-sessions-change-in-production

# --------------------------------------------
# Feature Flags
# --------------------------------------------
# Partner self-service registration. Single runtime flag controls BOTH the API
# enforcement (/auth/register-partner) AND the web UI: the dashboard reads this
# value at runtime from GET /api/v1/config, so a plain restart applies a change
# with no web rebuild (the old build-time PUBLIC_ENABLE_REGISTRATION is gone).
ENABLE_REGISTRATION=false               # gates both the API endpoints and the "Register your MSP" UI
# Optional scheduling link shown to pending (not-yet-activated) partners on the
# /account/inactive screen next to the billing CTA, so stopping at the payment
# step isn't a dead end. Must be an absolute http(s) URL; label defaults to
# "Book a call with us".
# PENDING_ACCOUNT_MEETING_URL=https://your-scheduler.example.com/intro-call
# PENDING_ACCOUNT_MEETING_LABEL=
ENABLE_2FA=true
# Kill-switch for the role-level MFA gate. Defaults OFF for this release
# (#4491): the reconcile migration flips force_mfa on every EXISTING
# Partner Admin role, so enforcing on upgrade with no warning would lock
# those admins into enrolment unexpectedly. Set to true to opt in now and
# enforce immediately — members of a force_mfa role (the system Partner
# Admin role on every install since RMM-QA-164) are then minted mfa=false
# and receive 428 mfa_enrollment_required until they enrol at
# /auth/mfa/setup (settings-driven requireMfa is unaffected either way —
# it stays enforced). Read at call time, so no code deploy is needed to
# flip it. Enforcement returns to default ON once the notification-period
# feature (#5306) ships. Mirrors deploy/.env.example.
# MFA_FORCE_FOR_PARTNER_ADMIN=true
# Per-refresh-token-family budget for POST /auth/refresh (#3696). The web app is
# an Astro MPA, so one full-page navigation spends exactly one refresh; the
# default 60/60s sits far above any human click rate while still capping a
# runaway client. A 429 is a wait, never a logout — lower these only while
# actively containing an abusive client.
# AUTH_REFRESH_RATE_LIMIT=60
# AUTH_REFRESH_RATE_WINDOW_SECONDS=60
# Interactive Swagger UI at /docs (loads scripts/styles from unpkg). Defaults to
# ON outside production and OFF in production; the raw OpenAPI spec at /docs is
# always served regardless.
# ENABLE_API_DOCS_UI=false
# Set to 1 to use the Claude Agent SDK for AI chat (instead of raw Anthropic SDK)
# USE_AGENT_SDK=1
# Auto-migrate database schema and seed on startup (default: true).
# Set to false to manage migrations manually via `pnpm db:migrate`.
# AUTO_MIGRATE=false

# --------------------------------------------
# C2C Microsoft 365 Multi-Tenant App (Optional)
# --------------------------------------------
# When set, enables one-click admin consent for M365 backup connections.
# Users grant access via Microsoft's admin consent flow instead of
# manually creating their own Azure AD app registration.
# Register a multi-tenant app in Azure AD with these Graph application permissions:
#   Mail.Read, Files.Read.All, Sites.Read.All, TeamSettings.Read.All, etc.
C2C_M365_CLIENT_ID=
C2C_M365_CLIENT_SECRET=
# Future: certificate-based auth
# C2C_M365_CERT_THUMBPRINT=
# C2C_M365_CERT_PRIVATE_KEY_PATH=

# M365 Customer Graph-read consent (Optional, dark by default)
# --------------------------------------------
# Enables only NEW customer-graph-read consent initiation. Existing connection
# status, callback, retest, and disconnect flows remain independent of this flag.
# When enabled, set the allowlist to comma-separated canonical organization UUIDs
# or literal * for all organizations.
M365_CUSTOMER_GRAPH_READ_ONBOARDING_ENABLED=false
M365_CUSTOMER_GRAPH_READ_ONBOARDING_ORG_IDS=
# Fixed multi-tenant Entra application descriptor. The API receives only this
# opaque, version-pinned reference; certificate material and Key Vault access
# belong exclusively to the isolated Graph-read executor.
M365_CUSTOMER_GRAPH_READ_CLIENT_ID=
M365_CUSTOMER_GRAPH_READ_VAULT_REF=
M365_CUSTOMER_GRAPH_READ_CREDENTIAL_VERSION=
# Private HTTPS executor transport and short-lived internal request signing.
# The API signing key must be an Ed25519 private JWK in an absolute-path file
# whose mode denies all group/other access (0600 or stricter). Do not put the
# private JWK directly in an environment variable.
M365_GRAPH_READ_EXECUTOR_URL=
M365_GRAPH_READ_EXECUTOR_AUDIENCE=m365-graph-read-executor
M365_GRAPH_READ_EXECUTOR_SIGNING_PRIVATE_JWK_FILE=/run/secrets/m365-graph-read-api-signing.jwk
M365_GRAPH_READ_EXECUTOR_SIGNING_KID=
# Independent flag gating the six m365_query_* AI tools (POST /v1/read-action)
# instead of connection onboarding above. Still requires the executor
# descriptors above — enabling it forces full executor config validation at boot.
M365_GRAPH_READ_TOOLS_ENABLED=false
# Literal * or comma-separated canonical organization UUIDs; required when the
# flag above is enabled.
M365_GRAPH_READ_TOOLS_ORG_IDS=

# M365 Ticket Mailbox (Optional — email-to-ticket via a shared support mailbox)
# --------------------------------------------
# SEPARATE Azure app registration from the C2C app above. When set, partner admins
# can connect an M365 shared mailbox (admin-consent flow) so customer email becomes
# tickets and replies are sent from that mailbox via Microsoft Graph.
# Register a multi-tenant app; required Graph permissions (application + delegated) are listed in
# apps/docs/src/content/docs/deploy/environment.mdx → "Ticket Mailbox (M365 email-to-ticket)".
# Redirect URI: <PUBLIC_APP_URL>/api/v1/tickets/mailbox/callback on a stock compose install
# (the API resolves PUBLIC_URL, then PUBLIC_APP_URL, then DASHBOARD_URL, and docker-compose.yml
# passes only PUBLIC_APP_URL). The mailbox settings card shows the exact value to register.
# Unset = feature disabled (routes return 400, nothing breaks at boot).
TICKET_MAILBOX_M365_CLIENT_ID=
TICKET_MAILBOX_M365_CLIENT_SECRET=

# --------------------------------------------
# Cloudflare mTLS (API Shield Client Certificates)
# --------------------------------------------
# Optional: When set, agents receive mTLS client certificates during enrollment.
# mTLS is NOT enforced until you add Cloudflare WAF rules.
#
# Soft-enabled by CLOUDFLARE_API_TOKEN. In production (Task 26 / audit H-3),
# CLOUDFLARE_ZONE_ID is REQUIRED whenever CLOUDFLARE_API_TOKEN is set — the API
# refuses to boot otherwise so that mTLS issuance can't 5xx on first request.
CLOUDFLARE_API_TOKEN=
CLOUDFLARE_ZONE_ID=

# Agent mTLS certificate-binding enforcement mode. This is a separate switch
# from issuance above: it controls whether the API consults the edge's
# verified-certificate assertion when deciding whether to trust a request.
# off (default) is the safe mixed-version and self-hosted default — the
# assertion is never consulted, so leaving this unset is a no-op. Never infer
# audit/enforce from NODE_ENV, IS_HOSTED, or CF_MTLS_* — the operator must
# select the mode explicitly. See docs/operations/cloudflare-mtls-setup.md
# before setting this to anything other than off.
#   off     - assertion never consulted (default; safe for self-hosted/no proxy validation)
#   audit   - binding decision computed and counted, never denies
#   enforce - devices with active certificate history must present a matching
#             verified assertion or the request is denied
AGENT_MTLS_BINDING_MODE=off

# --------------------------------------------
# Wave 6 security remediation — agent update/network rollout controls
# --------------------------------------------
# See docs/operations/agent-network-and-manifest-rollout.md for the full
# canary-ring rollout procedure before changing either of these in
# production. Both boot-refuse on an invalid value (not silently fall back).
#
# Keep false until every served update response includes signingKeyId and
# fleet adoption is proven (observe the missing-ID count at zero for 7
# consecutive days across every active server version). Pushed to agents
# running this build or newer via configUpdate.require_manifest_signing_key_id
# when true; older agent builds ignore the pushed value and continue
# accepting ID-less manifests regardless of this setting. false/unset omits
# the key entirely for rolling-deploy/server-rollback compatibility. This is
# not a no-op fleet-wide switch: a capable agent applies the pushed value on
# its next update check (the value is re-read at updater-construction time),
# while its helper-manager needs a restart to pick up the change — the same
# limitation backup_server_url already has.
AGENT_REQUIRE_MANIFEST_SIGNING_KEY_ID=false
#
# Heartbeat retain-state kill switch (#8616). Default true: an agent that
# advertises retain-state protocol 1 is told to keep its current PAM / helper /
# remote-management state on a beat where the server could not decide it,
# instead of being sent "off". false = every agent gets the legacy payload.
HEARTBEAT_RETAIN_STATE_ENABLED=true
#
# Managed-software destination policy mode (approved plan deviation D1).
#   compat (default) — a private destination still requires agent capability
#     >= 1 and fails closed; an apparently-public destination stays permitted
#     to a capability-0 device so deploy day doesn't fail in-flight software
#     pushes to a not-yet-upgraded fleet.
#   enforce — every managed-software command requires capability >= 1,
#     public destinations included. Do not flip to enforce before the fleet
#     has reached capability 1 (see the runbook's canary-ring row for this
#     flip) — capability-0 devices are denied every managed-software command.
MANAGED_SOFTWARE_POLICY_MODE=compat

# --------------------------------------------
# Billing service (breeze-billing — hosted SaaS only)
# --------------------------------------------
# Optional. Two distinct soft-enable indicators (Task 26 / audit H-3):
#   BREEZE_BILLING_URL — service-to-service API base URL used by
#     breezeBillingClient.ts (payment-setup, plan info). When set in
#     production, BREEZE_BILLING_API_KEY is REQUIRED.
#   BILLING_SERVICE_URL — partner AI-credits service used by aiCostTracker.
#     When set in production, BILLING_SERVICE_API_KEY is REQUIRED.
# BREEZE_BILLING_URL=
# BREEZE_BILLING_API_KEY=
# BILLING_SERVICE_URL=
# BILLING_SERVICE_API_KEY=

# --------------------------------------------
# Reporting FX — exchange-rate feed (multi-currency wave 7, #3779)
# --------------------------------------------
# Exchange rates are used for REPORTING ONLY: dashboard/report roll-ups show an
# optional "≈ approximate" total alongside the authoritative per-currency
# segmentation. FX never touches document math and is never stored on an
# invoice, quote or contract.
#
# EXCHANGE_RATE_SYNC_ENABLED — default ON. Set to false/0/no/off for air-gapped
#   or offline installs: the daily ECB feed is never scheduled, no outbound
#   request is made, and only rates a platform admin enters manually are used.
#   A currency pair with no rate is reported as unavailable, never as 1:1.
# FRANKFURTER_BASE_URL — override the public Frankfurter v2 endpoint
#   (https://api.frankfurter.dev/v2) with an internal mirror/proxy. Trusted
#   deployment config, never request input.
# EXCHANGE_RATE_SYNC_ENABLED=true
# FRANKFURTER_BASE_URL=https://api.frankfurter.dev/v2

# --------------------------------------------
# Built-in extensions (optional, OFF)
# --------------------------------------------
# First-party extensions ship inside the API image but are NOT loaded unless the
# deployment switches them on, so a deployment that does not want one pays
# nothing for it — no migrations, no schema, no infrastructure requirements.
# Each flag is strict: only the exact string "true" enables it.
#
# Workspace (file/email indexing, content search). Enabling it requires a
# PostgreSQL image with the pgvector extension available — its migrations run
# `CREATE EXTENSION vector` on API boot, and a stock postgres:16-alpine will
# fail the boot with `extension "vector" is not available`. The
# POSTGRES_IMAGE_REF default below already includes it.
# BREEZE_WORKSPACE_ENABLED=true

# AI operator agents (settings → AI Agents). Default false; nothing runs
# unattended until a later release even when true.
# BREEZE_AI_AGENTS_ENABLED=false

# AI Operator task delegation (#5205). Both default false — decision D2 keeps
# the feature to internal and test orgs until it graduates. TASKS_ENABLED gates
# the admission route POST /ai/operator/tasks and the "Delegate to Operator"
# action; the RECIPE flag additionally gates the one recipe that exists
# (service recovery). With either off, admission answers 422 with an
# actionable reason and the web action does not render.
# AI_OPERATOR_TASKS_ENABLED=false
# AI_OPERATOR_RECIPE_SERVICE_RECOVERY_ENABLED=false

# Wave 5 Part B (#3827) sub-flag of BREEZE_AI_AGENTS_ENABLED above. Gates
# attemptPolicyDecision: an agent-originated, supervised-scope action-intent
# whose operation is in the operator's per-agent actAssets.supervisedActionKeys
# (⊆ POLICY_DECIDABLE_TIER3) is authorized by policy — no human approval —
# instead of the normal human-decide fanout. Default false (dark-ship): when
# false, resolvePolicyDecisionState behaves exactly as before this wave.
# BREEZE_AI_AGENTS_POLICY_DECIDE_ENABLED=false
# AI sweeps act mode (#5755 W04): lets a sweep schedule opt into Act mode so
# sweep-minted intents reach policy-decide. Sub-flag: requires POLICY_DECIDE too. Default OFF.
# BREEZE_AI_AGENTS_SWEEP_ACT_ENABLED=false

# AI execution plane — sandboxed analysis workspaces (hosted only).
# Sub-flag of BREEZE_AI_AGENTS_ENABLED above; default false. When true in
# production the API refuses to boot unless IS_HOSTED=true, the backend is
# `vercel`, and all three VERCEL_* values below are set.
# BREEZE_AI_WORKSPACE_ENABLED=false
# Large-tool-result capture + read_artifact (#6732). Off by default: capture
# stores oversized tool results (redacted) in your S3/MinIO bucket, so it is
# opt-in. Set true only with an artifact bucket configured (ARTIFACT_S3_BUCKET_US
# or S3_BUCKET, plus S3_ACCESS_KEY/S3_SECRET_KEY); the API refuses to boot
# otherwise. Independent of BREEZE_AI_WORKSPACE_ENABLED (hosted-only).
# BREEZE_AI_ARTIFACT_CAPTURE_ENABLED=false
#
# Sandbox provider. `vercel` in production; `fake` is an in-process test double
# that runs code in the API process itself and is refused in production.
# AI_WORKSPACE_BACKEND=vercel
#
# Vercel Sandbox credentials. The token needs sandbox create/exec/delete on the
# project below; the SDK's ambient-credential fallback is deliberately unused.
# VERCEL_SANDBOX_TOKEN=
# VERCEL_TEAM_ID=team_xxxxxxxxxxxxxxxxxxxxxxxx
# VERCEL_PROJECT_ID=prj_xxxxxxxxxxxxxxxxxxxxxxxx
#
# Deployment-owned Vercel image reference with analysis libraries preinstalled.
# Unset or empty retains the universal base image (Python/Node/shell only). Set this to
# your published analysis image; run-time networking remains deny-all, so
# packages must be installed when building the image, never during a run.
# Nonempty image references must contain no whitespace.
# For the bundled runtime and build/publish instructions see docker/ai-workspace/README.md.
# VERCEL_SANDBOX_IMAGE=vercel/sandbox/universal
#
# Sandbox region per Breeze region. The sandbox region is asserted to equal the
# org's region at create. Do NOT use lhr1 for EU — the UK is a third country
# for GDPR transfer purposes.
# VERCEL_SANDBOX_REGION_EU=fra1
# VERCEL_SANDBOX_REGION_US=iad1
#
# Multiplier applied to vendor list compute prices (margin, and the regional
# rate spread we have not extracted). Default 1.0; a malformed or non-positive
# value falls back to 1.0 rather than zeroing billing.
# AI_COMPUTE_PRICE_MULTIPLIER=1.0

# AI script authoring, independent review and reviewer-gated execution (#5612).
# Default ON since W03 (approval cards, STRICT acknowledgement, verification and
# promotion are all in place). Set false to keep propose_script /
# get_script_proposal unregistered and /api/v1/ai/script-proposals dark.
BREEZE_AI_SCRIPT_AUTHORING_ENABLED=true

# --- AI execution plane (hosted only) ---------------------------------------
# Sub-flag of BREEZE_AI_AGENTS_ENABLED. Gates artifact capture of oversized AI
# tool results and (later waves) sandboxed workspaces. Honoured only when
# IS_HOSTED=true; self-hosted deployments see the capability absent. Default off.
# BREEZE_AI_WORKSPACE_ENABLED=false

# Deployment region for the hosted platform: eu | us. Selects the artifact blob
# bucket below and, in later waves, the sandbox region. Default us.
# BREEZE_REGION=us

# Artifact blob store. v1 supports "s3" only (S3-compatible object storage —
# MinIO locally, any provider in production). "db" is refused at boot.
# ARTIFACT_BLOB_BACKEND=s3
# Per-region bucket/endpoint. Each falls back to the platform S3_* value above
# when unset, so a single-bucket dev stack needs nothing here. Keys never carry
# a tenant id; a bucket lifecycle rule of ~60 days on the eu/ and us/ prefixes is
# the operational backstop for blobs whose row insert rolled back.
# ARTIFACT_S3_ENDPOINT_EU=https://object-storage.example.com
# ARTIFACT_S3_ENDPOINT_US=https://object-storage.example.com
# ARTIFACT_S3_BUCKET_EU=breeze-ai-artifacts-eu
# ARTIFACT_S3_BUCKET_US=breeze-ai-artifacts-us
# ARTIFACT_S3_REGION_EU=us-east-1
# ARTIFACT_S3_REGION_US=us-east-1
# ARTIFACT_S3_ACCESS_KEY=
# ARTIFACT_S3_SECRET_KEY=
# Server-side encryption header to send on every put: AES256 | aws:kms | unset.
# Leave unset on providers that encrypt at rest and reject the header.
# ARTIFACT_S3_SSE=

# Per-partner BYO-LLM provider catalog (#3922 W01-W04). Gates catalog-mode
# provider/endpoint selection (a connection's catalog endpoint) for the
# AI agent LLM resolver. Default false: selection-write routes 404 and any
# existing catalog config resolves as unavailable('catalog_disabled') —
# fail-loud, never a silent fallback to direct Anthropic.
# LLM_PROVIDER_CATALOG_ENABLED=false

# --------------------------------------------
# Docker Deployment
# --------------------------------------------
# Stable Compose project name for container labels and Docker named volumes.
# Keep this unchanged after first start so named volumes continue to attach to
# the same Postgres/Redis/API data after reboots, reruns, or directory moves.
COMPOSE_PROJECT_NAME=breeze

# BREEZE_VERSION names the Breeze release this server runs and selects the agent
# release offered to the fleet. With tag-form image refs
# (`ghcr.io/lanternops/breeze/api:${BREEZE_VERSION}`) it also picks the images. With
# the digest-pinned refs below, it does NOT: change it together with the four
# BREEZE_*_IMAGE_REF digests, via `bash scripts/guided-setup.sh --upgrade <version>`.
# See https://github.com/lanternops/breeze/releases for the current release.
#
# This must name a version whose images are actually PUBLISHED to GHCR, which is
# not the same as the newest git tag: a release can be tagged and then fail to
# publish (v0.105.2 and v0.106.0 are both tagged with no images). All four
# repositories below must carry the tag — `portal` is the one that catches this,
# since it was added after 0.81.0 and so 404s on every earlier pin.
# scripts/security/check-env-example-version-pin.sh verifies the pin against GHCR.
#
# Server-only releases: a hotfix release may rebuild only the server images
# (api/web/portal) and carry the previous full release's agent binaries forward.
# Its API image has the binaries release it pairs with baked in as
# BREEZE_BINARIES_VERSION, so boot sync, download redirects, installer
# verification and recovery media all follow that release while BREEZE_VERSION
# names the server. Do NOT set BREEZE_BINARIES_VERSION here or in compose — it is
# image-baked, and an empty override would break the pairing. GET /health reports
# both `version` and `binariesVersion`.
BREEZE_VERSION=0.105.1

# Breeze application images must be copied from the signed image inventory on
# the matching GitHub Release. scripts/guided-setup.sh verifies that inventory
# and fills these automatically. For manual setup, verify
# release-artifact-manifest.json.ed25519 with the public key above and copy the
# exact repository@sha256 tuples; a GHCR tag or package page is not an
# authorization source.
BREEZE_API_IMAGE_REF=ghcr.io/lanternops/breeze/api@sha256:replace-with-signed-release-digest
BREEZE_WEB_IMAGE_REF=ghcr.io/lanternops/breeze/web@sha256:replace-with-signed-release-digest
BREEZE_PORTAL_IMAGE_REF=ghcr.io/lanternops/breeze/portal@sha256:replace-with-signed-release-digest
BREEZE_BINARIES_IMAGE_REF=ghcr.io/lanternops/breeze/binaries@sha256:replace-with-signed-release-digest

# Third-party sidecar images. Pinned to specific minor versions to match what
# Breeze is tested against. Override to digest-pinned refs in production
# (e.g. `caddy@sha256:<digest>` from `docker buildx imagetools inspect caddy:2-alpine`).
CADDY_IMAGE_REF=caddy:2-alpine
# pgvector/pgvector is the official Postgres image + the vector extension
# pre-installed. Required only when BREEZE_WORKSPACE_ENABLED=true (above),
# whose migrations (ee/workspace/migrations/*.sql) run `CREATE EXTENSION
# vector` on API boot for content embeddings. Same Postgres major version as
# stock, just with the extension baked in — kept as the default so enabling
# Workspace later needs no database swap.
#
# UPGRADE CAVEAT — do NOT swap this image over an EXISTING data volume.
# postgres:16-alpine is built against musl; pgvector/pgvector:pg16 is built
# against glibc. The two disagree about collation versions, so starting one over
# a data directory initialized by the other logs a collation version mismatch
# and leaves every text index (and every unique constraint on a text column)
# potentially inconsistent until it is rebuilt — which can silently return wrong
# rows, not just fail loudly. If you are already running and want to switch,
# either dump and restore into a freshly-initialized volume, or run
# `REINDEX DATABASE <dbname>;` after the first start on the new image (and
# `ALTER DATABASE <dbname> REFRESH COLLATION VERSION;`). If you do not need
# Workspace, the simplest answer is to keep the image you already have.
POSTGRES_IMAGE_REF=pgvector/pgvector:pg16
REDIS_IMAGE_REF=redis:7-alpine
COTURN_IMAGE_REF=coturn/coturn:latest
#
# Container platform — defaults to linux/amd64 (matches GHCR images).
# GHCR does not publish arm64. On Apple Silicon, use
# docker-compose.override.yml.local-build to build native arm64 images.
# DOCKER_PLATFORM=linux/arm64
#
# Binary download source:
#   github (default) — agents download directly from GitHub Releases CDN.
#   local — serve from disk + optional S3 upload. Use this to distribute
#           binaries from your own infrastructure (S3, CDN, etc.).
# BINARY_SOURCE=github
#
# BYO signing: pull releases from YOUR signed-release repository instead of the
# official one (see the "Sign Your Own Agent Packages" guide). When you set this
# to a non-official repository you MUST also change
# RELEASE_ARTIFACT_MANIFEST_PUBLIC_KEYS to YOUR release manifest public key
# (the signing workflow's run summary prints it). Leaving it as the official key
# is rejected at boot in production: manifests from your repo are signed by your
# key and could never verify under the official one, so every sync would fail
# closed and the fleet would silently stay on its current version.
# BINARY_GITHUB_REPOSITORY=your-org/breeze-selfhost-signing
#
# Binary edition:
#   self-host (default) — today's behavior, unchanged.
#   hosted — this deployment serves privately-distributed binaries only. In
#            production this REQUIRES BINARY_SOURCE=local and
#            RELEASE_ARTIFACT_MANIFEST_PUBLIC_KEYS to be set; the deployment
#            refuses to boot otherwise, and local binary-sync fallbacks that
#            would otherwise reach out to the public GitHub release are
#            disabled. Not relevant to self-hosted deployments.
# BINARY_EDITION=self-host
#
# Automatic agent edition migration (#4072). When 'true' on a hosted-edition
# deployment, a Windows/amd64 device whose stranded self-host build is refused
# an update offer by the artifact-edition gate gets the 'Migrate Agent Edition
# (Windows)' system script dispatched automatically (one attempt per device,
# org update policy and version pins honored). Requires the raw MSI staged at
# AGENT_BINARY_DIR/breeze-agent.msi and PUBLIC_API_URL (or API_URL) set.
# AGENT_EDITION_AUTO_MIGRATE_ENABLED=false
#
# Controlled agent-fleet rollout. Default true: registering/syncing a release
# immediately becomes the fleet upgrade target (agent_versions.isLatest). Boot
# sync is pinned to the binaries release this server pairs with — BINARY_VERSION
# if set, else the release baked into a server-only image, else BREEZE_VERSION —
# so a newly published GitHub release never moves the fleet until you upgrade.
# A server-only release never registers or re-promotes agent binaries. Set
# false to decouple registration from promotion — new binaries are downloadable
# but the fleet only moves to a new version via an explicit, platform-admin
# POST /api/v1/agent-versions/promote { "version": "x.y.z" } after you verify it.
# AGENT_AUTO_PROMOTE=true
#
# Version tagging works like this:
#   git tag v0.3.0 && git push --tags   → stable release, tagged as "latest" + "0.3.0"
#   git tag v0.3.0-rc.1 && git push --tags → prerelease, tagged as "0.3.0-rc.1" only
#
# To upgrade a digest-pinned install (the default above): run
# `bash scripts/guided-setup.sh --upgrade <version>`. It verifies the signed image
# inventory and rewrites BREEZE_VERSION plus all four BREEZE_*_IMAGE_REF digests
# together, then pulls and restarts. Editing BREEZE_VERSION and running
# `docker compose pull` alone re-fetches the images already running. Tag-form installs
# can bump BREEZE_VERSION, then run `docker compose pull && docker compose up -d`.
# Full procedure: https://docs.breezermm.com/deploy/upgrades/

# --------------------------------------------
# MCP OAuth 2.1 (SaaS-only — leave unset for self-hosted Breeze)
# --------------------------------------------
# Enables the OAuth 2.1 + DCR authorization server for MCP clients
# (Claude.ai, ChatGPT). When false the /oauth/* routes are not mounted.
#
# In production (Task 26 / audit H-3): when MCP_OAUTH_ENABLED=true, the API
# refuses to boot unless BOTH OAUTH_JWKS_PRIVATE_JWK and OAUTH_COOKIE_SECRET
# are also set. Without these, /oauth/* boots clean and 5xxs on first
# authorization request instead of failing fast at startup.
MCP_OAUTH_ENABLED=false
# Dynamic Client Registration. Defaults to FALSE in every environment —
# enable explicitly only when public MCP clients must self-register
# (Claude.ai, ChatGPT installer flows, etc.).
#
# SECURITY: When OAUTH_DCR_ENABLED=true in production you MUST choose an
# anti-spam posture — set EITHER OAUTH_DCR_REQUIRE_IAT=true OR
# OAUTH_DCR_ALLOW_ANONYMOUS=true. The API refuses to boot if DCR is on with
# neither, so an accidental deploy can't leave POST /oauth/reg ungated.
OAUTH_DCR_ENABLED=false
# Require an initial-access-token (issued out-of-band via the dashboard) for
# each DCR registration. Closes the public-spam vector, BUT is incompatible
# with public MCP clients (Claude Desktop / claude.ai) — they register via
# anonymous RFC 7591 DCR and cannot supply an IAT. Leave false for a public
# MCP server; use OAUTH_DCR_ALLOW_ANONYMOUS instead.
OAUTH_DCR_REQUIRE_IAT=false
# Deliberately permit anonymous DCR. This is the REQUIRED posture for a public
# MCP server: anonymous registration is the only path Claude's connector can
# use. Residual spam risk is bounded by the controls on /oauth/reg (per-IP
# rate limit, forced public clients, mandatory PKCE S256, software_id
# rejection, daily stale-client GC). Set true when serving Claude / ChatGPT.
OAUTH_DCR_ALLOW_ANONYMOUS=false
# Issuer URL — public origin where /oauth/* is reachable (e.g. https://us.2breeze.app)
# OAUTH_ISSUER=
# Resource indicator audience for access tokens (typically `${OAUTH_ISSUER}/mcp/server`)
# OAUTH_RESOURCE_URL=
# Absolute end of the one-access-token-lifetime compatibility window for
# pre-Wave-3 access tokens that do not carry auth_epoch. Required when OAuth
# is enabled in production/staging; choose once per rollout and never extend it
# on restart. It must be at least 1800 seconds after new token writers start.
OAUTH_AUTH_EPOCH_ENFORCE_AFTER=2026-08-06T00:30:00Z
# Rolling-deploy compatibility for event WebSocket permission epochs. Deploy
# new writers/readers with compat, wait at least 60 seconds after the last
# version-one writer drains, then switch the whole fleet to enforce.
EVENT_PERMISSION_EPOCH_MODE=compat
# Origin that hosts the /oauth/consent UI. For single-origin deployments this
# equals OAUTH_ISSUER; for cross-origin dev set to the web app origin
# (e.g. http://localhost:4321).
# OAUTH_CONSENT_URL_BASE=
# Cookie signing secret for oidc-provider session/interaction cookies.
# Use: openssl rand -base64 64
# OAUTH_COOKIE_SECRET=
# JWKS private key in JWK JSON form (Ed25519). Generate with the helper script
# in apps/api/scripts/generate-oauth-jwk.ts. Required for JWT signing.
# OAUTH_JWKS_PRIVATE_JWK=

# --------------------------------------------
# Hosted SaaS (leave unset / false for self-hosted Breeze)
# --------------------------------------------
# Set to true on hosted deployments. Bypasses self-host gates (e.g. setup-admin
# requirement on /auth/register) and enables billing redirect flows. Also gates
# the email-verification → status='active' path in /auth/register-partner.
# Required in production: must be explicitly set to true or false. The API
# refuses to start if NODE_ENV=production and IS_HOSTED is unset, so a
# misconfigured deploy can't silently bypass the verification gate (#570).
IS_HOSTED=false

# Remote-access WebSocket cutover controls. Keep admission closed while
# upgrading the first lease-aware release; see the upgrade guide.
REMOTE_ACCESS_ADMISSION_MODE=open
REMOTE_WS_AUTH_MODE=post_upgrade
REMOTE_WS_REDIS_TOPOLOGY=standalone-single-primary
REMOTE_WS_LEGACY_TICKET_WRITER_DRAINED_AT=
REMOTE_WS_LEGACY_VIEWER_ISSUER_DRAINED_AT=
# Remote-desktop start fence. Default true: every desktop start is refused
# (503 agent_upgrade_required, "Remote desktop needs an agent update on this
# device") for an agent that has not declared the durable start/terminal fence
# (desktopFenceProtocolVersion=1, agents v0.114.0 and later). Set false only as
# a temporary opt-out while older agents are still updating.
REMOTE_DESKTOP_FENCE_REQUIRED=true

# Approver assurance platform default. Partners that have not chosen an
# approval-security enforcement setting (Settings > Organization > Approval
# Security left on "Platform default") require a registered approver device
# for high- and critical-risk approvals from this date. Blank = the built-in
# date (2026-11-05T00:00:00Z). Accepts an ISO date or timestamp; an invalid
# value refuses to boot. Partners that saved an explicit choice are unaffected.
# APPROVER_ASSURANCE_DEFAULT_ENFORCE_FROM=2026-11-05T00:00:00Z

# Pre-assignment enrollment platform switch. When false (the default),
# deploy-key enrollment into a partner's unassigned-devices holding area is off
# everywhere, whatever each partner's own setting says.
PRE_ASSIGNMENT_ENROLLMENT_ENABLED=false

# BYO-MCP tool catalog (#5216 W01): register external MCP servers as tool
# sources, discover their tools, and expose them to AI chat / the MCP bridge.
# Dark-shipped, default OFF. Tier-3 external tools always go through action
# intents (human approval).
TOOL_SOURCES_ENABLED=false
# Self-hosted only (refused when IS_HOSTED=true): allow a tool source URL to
# resolve to a private, link-local, or loopback address.
TOOL_SOURCES_ALLOW_PRIVATE_EGRESS=false

# Caller verification (anti-vishing, #6354). W01 backend core ships dark:
# authenticated caller-verification routes 404 and the release gate refuses
# until this is EXACTLY 'true' ('1'/'yes'/'on' are refused at boot).
CALLER_VERIFICATION_ENABLED=false

# WebAuthn / passkeys. Optional — the relying-party id defaults to the
# hostname of PUBLIC_APP_URL and the origin to PUBLIC_APP_URL itself. Set
# these only when the browser reaches the app on a different host than
# PUBLIC_APP_URL (e.g. WEBAUTHN_RP_ID=localhost on a local stack), or every
# passkey ceremony fails with "The RP ID ... is invalid for this domain".
# WEBAUTHN_RP_ID=
# WEBAUTHN_ORIGIN=
# WEBAUTHN_RP_NAME=
# Hosted SaaS only — URL to breeze-billing's payment-setup landing page.
# Empty on self-host (no billing service running).
BILLING_URL=
# PUBLIC_ACTIVATION_BASE_URL=https://us.2breeze.app
# BUSINESS_EMAIL_ALLOW_OVERRIDES=/etc/breeze/email-overrides.json

# --------------------------------------------
# Platform admins (cross-tenant /admin/* gate)
# --------------------------------------------
# Comma-separated list of user emails to promote to platform admin at API
# startup. Idempotent (already-promoted users are skipped) and never demotes —
# removing an email from this list does NOT revoke the flag, demote via DB.
# Leave unset to opt out (no platform admins, /admin/* endpoints will 403).
BREEZE_PLATFORM_ADMINS=

# --------------------------------------------
# Inbound automation webhooks
# --------------------------------------------
# Authentication for POST /automations/webhooks/:id. Default is HMAC-signed
# requests only (x-breeze-signature + x-breeze-timestamp).
#
# Set true ONLY as a short-term emergency rollback while migrating legacy
# senders to HMAC. Plain x-webhook-secret / x-automation-secret in transit is
# replayable forever by anyone who reads one access-log line or pcap.
# This flag will be removed in a future release.
AUTOMATION_WEBHOOK_ALLOW_LEGACY_SECRET=false

# AUTOMATION_WEBHOOK_ALLOW_QUERY_SECRET was removed entirely. The `?secret=`
# query-string parameter is no longer accepted under any configuration —
# query strings end up in every proxy/load-balancer/CDN access log on the path.

# --------------------------------------------
# Native APNs push (iOS app)
# --------------------------------------------
# All optional — leave every value unset (or empty) to disable push entirely.
#
# All-or-none: setting ANY APNS_* value makes APNS_AUTH_KEY, APNS_KEY_ID,
# APNS_TEAM_ID and APNS_BUNDLE_ID all required, in every NODE_ENV. That is
# deliberate — a half-configured relay would otherwise fail silently at first
# send instead of loudly at boot. APNS_ENVIRONMENT stays optional.
#
# These must also be mapped in the api service `environment:` block of your
# compose file — a value in .env alone is never seen by the API.
#
# APNS_AUTH_KEY is the .p8 signing key PEM (newlines included).
# APNS_AUTH_KEY=
# APNS_KEY_ID=
# APNS_TEAM_ID=
# APNS_BUNDLE_ID=
# APNS_ENVIRONMENT=production

# --------------------------------------------
# Outbox / anomaly-incident retention (#4210)
# --------------------------------------------
# ticket_outbox, intent_outbox and metric_anomaly_incidents are transactional
# outbox tables drained within seconds by their own publisher workers, but
# nothing previously deleted the drained rows. These three daily jobs prune
# rows once they are terminal: delivered (published_at/dispatched_at set) or
# permanently stuck (publish/dispatch attempts exhausted — see the matching
# publisher job's MAX_PUBLISH_ATTEMPTS). All optional; defaults shown below.
# TICKET_OUTBOX_RETENTION_DAYS=14
# TICKET_OUTBOX_RETENTION_BATCH_SIZE=5000
# TICKET_OUTBOX_RETENTION_MAX_BATCHES=50
# INTENT_OUTBOX_RETENTION_DAYS=14
# INTENT_OUTBOX_RETENTION_BATCH_SIZE=5000
# INTENT_OUTBOX_RETENTION_MAX_BATCHES=50
# METRIC_ANOMALY_INCIDENT_RETENTION_DAYS=14
# METRIC_ANOMALY_INCIDENT_RETENTION_BATCH_SIZE=5000
# METRIC_ANOMALY_INCIDENT_RETENTION_MAX_BATCHES=50

# --------------------------------------------
# QuickBooks Online (accounting integration)
# --------------------------------------------
# All optional — leave every value unset (or empty) to keep the QuickBooks
# integration dark. The Connect button then reports that the provider is not
# configured rather than starting an OAuth flow that cannot complete.
#
# QBO_CLIENT_ID / QBO_CLIENT_SECRET come from your Intuit developer app
# (Keys & credentials). QBO_REDIRECT_URI must match a redirect URI registered
# on that same app, and must be the PUBLIC url of this deployment's API.
# QBO_ENVIRONMENT selects Intuit's sandbox or production API host.
#
# QBO_WEBHOOK_VERIFIER_TOKEN is the app-level verifier token Intuit shows on
# the app's Webhooks page. Without it, POST /api/v1/webhooks/quickbooks answers
# 503 (never 200) and payment pull-back falls back entirely to the 15-minute
# sweep — which is the supported configuration if you have no public webhook
# URL. Intuit allows ONE webhook URL per app, so only one deployment per app
# can receive notifications.
#
# QBO_CLIENT_ID=
# QBO_CLIENT_SECRET=
# QBO_REDIRECT_URI=https://your-domain.example.com/api/v1/accounting/quickbooks/callback
# QBO_ENVIRONMENT=production
# QBO_WEBHOOK_VERIFIER_TOKEN=

# --------------------------------------------
# Xero (accounting integration)
# --------------------------------------------
# All optional — leave XERO_CLIENT_ID unset to keep the Xero integration dark
# (the Xero card is hidden). Register a Web app at developer.xero.com, then:
#   XERO_CLIENT_ID / XERO_CLIENT_SECRET  from the app's Configuration page.
#   XERO_REDIRECT_URI  must match a redirect URI registered on the app, and be
#                      the PUBLIC url of this deployment's API.
#   XERO_WEBHOOK_KEY   the app's webhook signing key. In the Xero app's Webhooks
#                      page, subscribe to Invoices with delivery URL
#                      https://your-domain.example.com/api/v1/webhooks/xero, then
#                      send "Intent to receive". Without it, payments recorded
#                      in Xero still reach Breeze through the 15-minute sweep,
#                      just more slowly.
#   XERO_DAILY_CALL_LIMIT  per-organisation daily API budget for your Xero tier
#                      (Starter = 1000, the default; Core/Plus/Advanced = 5000).
#
# XERO_CLIENT_ID=
# XERO_CLIENT_SECRET=
# XERO_REDIRECT_URI=https://your-domain.example.com/api/v1/accounting/xero/callback
# XERO_WEBHOOK_KEY=
# XERO_DAILY_CALL_LIMIT=1000

# --------------------------------------------
# Offline work queue (#5128)
# --------------------------------------------
# Work targeted at an OFFLINE device is persisted with a delivery deadline and
# claimed by the agent on its next successful heartbeat, instead of failing
# immediately. This covers patch jobs, automation `run_script` /
# `execute_command` actions, scan/rollback commands, manual scripts, and
# software installs.
#
# How long a queued row may wait for its device before it expires undelivered.
# Per TTL class, in hours; the defaults below apply when unset.
# DEVICE_COMMAND_QUEUE_TTL_HOURS=168
# DEVICE_COMMAND_QUEUE_SHORT_TTL_HOURS=24
# DEVICE_COMMAND_QUEUE_POWER_STATE_TTL_HOURS=24

# --------------------------------------------
# Audit chain: anchor signing, verification, retention credential (#7470)
# --------------------------------------------
# All optional; leaving them unset keeps the defaults noted on each line.
# See deploy/environment.mdx → "Audit chain".
#
# AUDIT_ANCHOR_SIGNING_KEY signs each daily audit-chain anchor (04:45 UTC) with
# Ed25519 so a copy kept outside the database can be checked against the
# public key. Value: a base64-encoded 32-byte seed. Generate one with:
#   openssl rand -base64 32
# Treat it like JWT_SECRET. It must live outside the database (that is what
# makes the signature worth checking), and you should keep a copy: a new key
# means a new public key for your verifier. The API logs the key id and public
# key at boot. Unset = anchors are written unsigned.
# AUDIT_ANCHOR_SIGNING_KEY=
# Kill switch for the daily anchor job (default on).
# AUDIT_CHAIN_ANCHOR_ENABLED=true
# Nightly audit-chain verification (04:15 UTC).
# AUDIT_CHAIN_VERIFY_ENABLED=true
# AUDIT_CHAIN_VERIFY_MODE=incremental
# AUDIT_CHAIN_VERIFY_RESCAN_SLICES=30
# Dedicated breeze_audit_admin login used ONLY by audit retention. Unset = the
# legacy shared-credential path (logged as a SECURITY warning at boot).
# AUDIT_ADMIN_DATABASE_URL=postgresql://breeze_audit_admin:password@postgres:5432/breeze

# Retention windows, agent ingest quotas / rate limits and misc tuning knobs
# (#7640 batch 2). All optional: leave unset to keep the built-in default shown.
# AGENT_CHANGES_MAX_BYTES_PER_DEVICE_PER_DAY=
# AGENT_CHANGES_MAX_BYTES_PER_ORG_PER_DAY=
# AGENT_CHANGES_MAX_ROWS_PER_DEVICE_PER_DAY=
# AGENT_CHANGES_MAX_ROWS_PER_ORG_PER_DAY=
# AGENT_EVENTLOG_MAX_BYTES_PER_DEVICE_PER_DAY=
# AGENT_EVENTLOG_MAX_BYTES_PER_ORG_PER_DAY=
# AGENT_EVENTLOG_MAX_ROWS_PER_ORG_PER_DAY=
# AGENT_LOG_MAX_BYTES_PER_DEVICE_PER_DAY=
# AGENT_LOG_MAX_BYTES_PER_ORG_PER_DAY=
# AGENT_LOG_MAX_ROWS_PER_DEVICE_PER_DAY=
# AGENT_LOG_MAX_ROWS_PER_ORG_PER_DAY=
# AGENT_ORG_RATE_LIMIT_MAX=20000
# AGENT_ORG_RATE_LIMIT_PER_DEVICE=12
# AGENT_ORG_RATE_LIMIT_PER_MIN=
# AGENT_WS_COMMAND_RESULT_MESSAGE_BUDGET_CAPACITY=600
# AGENT_WS_COMMAND_RESULT_MESSAGE_BUDGET_REFILL_PER_SECOND=120
# AGENT_WS_MESSAGE_BUDGET_CAPACITY=300
# AGENT_WS_MESSAGE_BUDGET_CLOSE_THRESHOLD=200
# AGENT_WS_MESSAGE_BUDGET_REFILL_PER_SECOND=60
# AGENT_WS_UPDATE_STATUS_MESSAGE_BUDGET_CAPACITY=
# AGENT_WS_UPDATE_STATUS_MESSAGE_BUDGET_REFILL_PER_SECOND=
# CHANGE_LOG_RETENTION_BATCH_SIZE=10000
# CHANGE_LOG_RETENTION_DAYS=90
# CHANGE_LOG_RETENTION_MAX_BATCHES=
# DB_POOL_MAX=30
# DEVICE_METRICS_RETENTION_DAYS=30
# HELPER_SCREENSHOT_RATE_LIMIT=12
# HELPER_SCREENSHOT_RATE_WINDOW_SECONDS=60
# IP_HISTORY_RETENTION_BATCH_SIZE=10000
# IP_HISTORY_RETENTION_DAYS=90
# IP_HISTORY_RETENTION_MAX_BATCHES=
# LOGIN_ACCOUNT_LOCKOUT_MAX=5
# LOGIN_ACCOUNT_LOCKOUT_WINDOW_SECONDS=
# LOG_FORWARDING_MAX_JOB_BYTES=1048576
# LOG_FORWARDING_MAX_PENDING_PER_ORG=2000
# LOG_FORWARDING_MAX_WAITING_GLOBAL=
# METRIC_ROLLUP_5M_RETENTION_DAYS=
# METRIC_ROLLUP_DAILY_RETENTION_DAYS=
# METRIC_ROLLUP_DELETE_BATCH_SIZE=5000
# METRIC_ROLLUP_HOURLY_RETENTION_DAYS=
# METRIC_ROLLUP_MAINTENANCE_CRON=
# METRIC_ROLLUP_MAINTENANCE_ENABLED=true
# METRIC_ROLLUP_PARTITION_MONTHS_AHEAD=3
# ML_OUTPUT_RETENTION_BATCH_SIZE=5000
# ML_OUTPUT_RETENTION_DAYS=365
# ML_OUTPUT_RETENTION_MAX_BATCHES=50
# OFFBOARDING_DRAIN_WINDOW_HOURS=72
# PROCESS_SAMPLE_RETENTION_DAYS=7
# PUBLIC_DOWNLOAD_KEY_MAX_TTL_MINUTES=
# RELIABILITY_HISTORY_RETENTION_BATCH_SIZE=10000
# RELIABILITY_HISTORY_RETENTION_DAYS=120
# RELIABILITY_HISTORY_RETENTION_MAX_BATCHES=50
# SCREENSHOT_MAX_BYTES=1600000
# SCREENSHOT_MAX_BYTES_PER_DEVICE=
# SCREENSHOT_MAX_PER_DEVICE=20
# SERVICE_PROCESS_CHECK_RESULTS_RETENTION_DAYS=14
# SNMP_METRICS_RETENTION_BATCH_SIZE=10000
# SNMP_METRICS_RETENTION_DAYS=30
# SNMP_METRICS_RETENTION_MAX_BATCHES=
# TENANT_TOOL_MAX_IN_FLIGHT_PER_ORG=8
# TURN_CREDENTIAL_MINT_LIMIT_PER_WINDOW=30
# TURN_CREDENTIAL_MINT_WINDOW_SECONDS=600
# USER_RISK_RETENTION_BATCH_SIZE=5000
# USER_RISK_RETENTION_DAYS=90
# USER_RISK_RETENTION_MAX_BATCHES=50