Documentation Index
Fetch the complete documentation index at: https://docs.fluxamerica.io/llms.txt
Use this file to discover all available pages before exploring further.
Environment variables
Self-hosted deployments of the Flux Platform are configured exclusively through environment variables. The table below lists every variable the platform binary reads, with its default (if any), sensitivity, and operational notes. A missing required variable causes the binary to refuse to start; an unknown variable is silently ignored. This page is auto-generated fromdocs/OPERATIONS.md § 3 Configuration in the platform repository (ADR-0044 § M.8 enforces a bijection between the env vars the code reads and the variables documented in that table). The implementation-detail “Read in” column from the canonical source is omitted here; partner operators do not need the in-source module path.
| Variable | Default | Sensitive | Notes | ||
|---|---|---|---|---|---|
PLATFORM_BIND | 0.0.0.0:8080 | no | TCP listen address | ||
PLATFORM_VERIFIER_TICK_SECONDS | 30 | no | Period of the continuous audit-chain verifier tick (ADR-0007 / OPS §5.2). Each tick walks every known tenant’s audit chain from its audit_verifier_checkpoint, advances the checkpoint, and emits a Sev-1 log on hash mismatch. | ||
PLATFORM_VERIFIER_BATCH_SIZE | 1024 | no | Max events advanced per tenant per verifier tick (ADR-0007 / OPS §5.2). Bounds the per-tick latency at the cost of slightly delayed Sev-1 detection on a tenant with > batch-size new events between ticks. | ||
PLATFORM_ATTACHMENT_SWEEP_TICK_SECONDS | 3600 | no | Period of the attachment-pending sweep tick (ADR-0015). Each tick walks every tenant, lists its Pending attachments via AttachmentStore::list_pending, and transitions any older than PLATFORM_ATTACHMENT_PENDING_MAX_AGE_SECONDS to Expired. | ||
PLATFORM_ATTACHMENT_PENDING_MAX_AGE_SECONDS | 86400 | no | Max age of a Pending attachment before the sweep transitions it to Expired (ADR-0015 § “Scan state machine”). Defaults to 24 hours per ADR-0015. | ||
PLATFORM_ATTACHMENT_RESCAN_TICK_SECONDS | 86400 | no | Period of the periodic-rescan tick (ADR-0015 § “Periodic rescan”). Each tick walks every tenant, lists Clean attachments older than PLATFORM_ATTACHMENT_RESCAN_INTERVAL_SECONDS, and re-enqueues each into scan_queue with ScanReason::Rescan. Defaults to 24 hours (nightly cadence). | ||
PLATFORM_ATTACHMENT_RESCAN_INTERVAL_SECONDS | 604800 | no | Minimum age of a Clean attachment before the rescan task re-enqueues it (ADR-0015 § “Periodic rescan”). Defaults to 7 days per ADR-0015 — catches signature-update reclassifications without re-scanning fresh work. | ||
PLATFORM_LOG_JSON | false | no | true ⇒ JSON-structured logs | ||
RUST_LOG | info,platform=debug | no | tracing-subscriber env-filter directive | ||
PLATFORM_DATA_DIR | ./data | no | ADR-0041 — canonical root for the platform’s durable + scratch state. Subdirs surrealkv/, backups/, scratch/ are created by platform-admin init <data-dir> (boot fails-fast otherwise when PLATFORM_DB_URL is surrealkv-backed). | ||
PLATFORM_DB_URL | derived: surrealkv://$PLATFORM_DATA_DIR/surrealkv/ | no | SurrealDB connection URL. ADR-0038 makes embedded SurrealKV the default production engine; the path derives from PLATFORM_DATA_DIR when this var is unset. Network URLs (ws://, wss://) stay supported for deployments that run a separate SurrealDB server process and bypass the ADR-0041 sentinel check. memory:// is dev/test only (no durability). Read by both the platform binary (startup connect + migrate) and the platform-admin CLI. | ||
PLATFORM_DB_NAMESPACE | platform | no | Surreal namespace | ||
PLATFORM_DB_NAME | platform | no | Surreal database | ||
PLATFORM_DB_USERNAME | — (required) | yes | Surreal Root user | ||
PLATFORM_DB_PASSWORD | — (required) | yes | Surreal Root password | ||
PLATFORM_DB_POOL_CAPACITY | 128 | no | Bounded LRU per-tenant connection pool capacity (ADR-0029 M.1). Must be > 0. Provisional default — supported envelope is the ADR-0028 N.5 / ADR-0033 S6 benchmark output. | ||
PLATFORM_DB_POOL_IDLE_TTL_SECONDS | 900 | no | Idle-TTL after which a per-tenant connection is evicted (ADR-0029 M.1). Provisional; tuned by N.5. | ||
PLATFORM_MIGRATIONS_DIR | ./surreal | no | Path to bundled SurrealQL migrations. Defaults match the Dockerfile (/app/surreal after WORKDIR /app); override only for non-standard layouts. | ||
WORKOS_API_BASE | https://api.workos.com/ | no | WorkOS REST root | ||
WORKOS_API_KEY | — (required) | yes | WorkOS API key | ||
WORKOS_CLIENT_ID | — (required) | no | WorkOS client id | ||
WORKOS_AUDIENCE | — (required) | no | JWT audience | ||
WORKOS_ISSUER | https://api.workos.com/ | no | JWT issuer | ||
WORKOS_JWKS_URL | https://api.workos.com/sso/jwks | no | JWKS endpoint | ||
PLATFORM_BASE_URL | http://127.0.0.1:8080 | no | The platform’s own externally-visible base URL. Used by the device-authorization flow’s redirect handling (ADR-0009) and embedded into /.well-known/auth-config responses. Production: the platform’s public URL behind any load balancer / ingress. | ||
AUTH_DEVICE_AUTHORIZATION_ENDPOINT | https://api.workos.com/user_management/authorize/device | no | Device flow endpoint | ||
AUTH_TOKEN_ENDPOINT | https://api.workos.com/user_management/authenticate | no | Token endpoint | ||
JWKS_TTL_SECONDS | 3600 | no | JWKS cache TTL | ||
PLATFORM_WT_BIND | [::]:8443 | no | UDP bind address for the WebTransport listener (ADR-0023). Default is IPv6 unspecified with dual-stack (accepts both IPv4 and IPv6 clients on a single endpoint). Sibling to PLATFORM_BIND (which is TCP/HTTP). | ||
PLATFORM_WT_IPV6_V6_ONLY | 0 (dual-stack on) | no | Set to 1 to disable dual-stack acceptance when PLATFORM_WT_BIND is an IPv6 address. Required only on hosts that must keep IPV6_V6ONLY=1 for compliance. Ignored for IPv4 binds. | ||
PLATFORM_WT_CERT | (unset → self-signed) | no | Path to TLS certificate file (PEM or DER). Production. Must be set together with PLATFORM_WT_KEY; one without the other is a startup error. | ||
PLATFORM_WT_KEY | (unset → self-signed) | yes | Path to PKCS#8 private key file. Production. Pair with PLATFORM_WT_CERT. | ||
PLATFORM_WT_SAN | localhost | no | Comma-separated SAN list for the self-signed identity. Ignored when PLATFORM_WT_CERT is set. Dev/test only. | ||
PLATFORM_WT_SHUTDOWN_DRAIN_SECONDS | 30 | no | Graceful-shutdown drain window for the WebTransport listener. After ServerControlFrame::Shutdown is sent, in-flight op streams keep running and new op-stream creation is rejected for this many seconds before the session closes. Tighten on tight-rollout clusters; widen if long-lived ops dominate. | ||
PLATFORM_RESUME_TOKEN_SECRET | (unset → ephemeral) | yes (production) | Hex-encoded 32-byte HMAC key used to sign subscription resume tokens (ADR-0023 § 6.5). MUST be set in production and MUST be identical across every server instance behind a load balancer; otherwise resume tokens issued by one instance are rejected by another. Unset → ephemeral random secret with a startup warning; tokens won’t survive restart in that mode. Rotation invalidates outstanding tokens (clients fall back to the gap-exceeded recovery path). | ||
PLATFORM_TENANT_USER_SECRET | (unset → Root fallback) | yes (production) | Hex-encoded 32-byte HMAC key used to derive namespace-scoped SurrealDB users (ADR-0029 M.5). When set, every per-tenant connection signs in as tenant_<slug> instead of Root; provisioning runs DEFINE USER tenant_<slug> ON NAMESPACE PASSWORD '<hash>' ROLES OWNER with the derived credentials. Unset → factory falls back to Root (M.1 footprint) and a startup WARN fires. Rotation: change the env var, then re-run ensure_provisioned for each tenant (DEFINE USER OVERWRITE is idempotent across rotations; first session against a tenant after rotation re-derives + writes the new password). | ||
PLATFORM_BUILD_ID | CARGO_PKG_VERSION | no | Build identifier reported in protocol ServerHello.server_metadata.build_id. Typically a git short-sha set by CI. | ||
PLATFORM_FX_ASSETS_DIR | ./target/fx-assets | no | Directory holding fx_wasm.wasm + fx.surli artifacts (ADR-0034 W.5). Missing artefacts boot with a structured WARN and degrade gracefully via the router’s SurrealismPlugin → WasmtimeHost → Native fallback chain. | ||
PLATFORM_FX_TARGET_<SURFACE> | (per-surface defaults — all in-DB except as overridden) | no | Per-surface evaluator-target override (ADR-0034 W.5). <SURFACE> is one of VALIDATOR, COMPUTED, DEFAULTVALUE, INDEX, VISIBILITY. Values: `native | wasmtime-host | surrealism-plugin. Unknown values log a WARN` and keep the default. |
PLATFORM_FX_SIDECAR_TTL_DAYS | 30 | no | TTL for record_version_sidecar rows beyond the last-3 versions per (record, slug) (ADR-0022 K.6). The last-3 rows are kept regardless of age for rollback ergonomics; older rows whose updated_at is past the TTL are GC’d by the sidecar GC tick. | ||
PLATFORM_FX_SIDECAR_GC_TICK_SECONDS | 21600 (6 hours) | no | Cadence of the sidecar GC tick (ADR-0022 K.6). | ||
PLATFORM_FX_INVALIDATION_DRAIN_TICK_SECONDS | 30 | no | Cadence of the invalidation-backfill drainer tick (ADR-0021 I.3). The drainer pages rows truncated past the synchronous fanout cap, marks dependent records stale, and emits ComputedInvalidated broker events per page. | ||
PLATFORM_LIST_LIMIT_CEILING | 250 | no | ADR-0046 § P.6 — operator-policy ceiling on list-op limit parameters. Acts as both the no-override default and the clamp on per-tenant tenant.list_limit_max overrides. Default fits the FSM-exemplar dispatcher’s daily job board (250 jobs/page with same-day-view headroom). | ||
PLATFORM_SUBSCRIPTION_BUFFER_CEILING | 10000 | no | ADR-0046 § P.6 — operator-policy ceiling on the per-subscription broker buffer. Tenants raise via tenant.subscription_buffer_max. | ||
PLATFORM_FX_VALIDATOR_MAX_OPS_CEILING | 50000 | no | ADR-0046 § P.6 — operator-policy ceiling on the Fx Validator surface’s per-evaluation op budget. Default mirrors fx_lang::runtime::SURFACE_SPECS[validator].max_ops post-ADR-0046 P.4. | ||
PLATFORM_FX_VALIDATOR_MAX_WALL_MS_CEILING | 25 | no | ADR-0046 § P.6 — operator-policy ceiling on the Fx Validator surface’s per-evaluation wall-clock budget (ms). Default is the post-ADR-0046 P.4 write-path-critical value. | ||
PLATFORM_FX_COMPUTED_MAX_OPS_CEILING | 100000 | no | ADR-0046 § P.6 — operator-policy ceiling on the Fx ComputedField surface’s per-evaluation op budget. Default mirrors fx_lang::runtime::SURFACE_SPECS[computed_field].max_ops. | ||
PLATFORM_FX_COMPUTED_MAX_WALL_MS_CEILING | 50 | no | ADR-0046 § P.6 — operator-policy ceiling on the Fx ComputedField surface’s per-evaluation wall-clock budget (ms). | ||
PLATFORM_INVALIDATION_SYNC_FANOUT_CAP | 50000 | no | ADR-0046 § P.6 — synchronous invalidation cascade truncation cap. Fanout above this defers the leftover to invalidation_backfill_queue and increments platform_fx_invalidation_fanout_overflow_total. Default mirrors the ADR-0046 P.2 5× headroom over the FSM-exemplar ~10k dependent records per customer-name-change burst. |