Server and worker settings

Every Flux server, database, scheduling, workers, security, and observability option in tabular form, with defaults and env var equivalents.

The canonical option lookup for Flux 0.56.0. Every field on FluxConfig and its nested models appears below with its type, default, env var, and one-line purpose. For operator deployment context see Server configuration; this page is the field-by-field reference.

Server

Top-level fields under [flux]. Env vars use a single underscore — FLUX_SERVER_HOST, not FLUX_SERVER__HOST.

Field	Type	Default	Env var	Purpose
`debug`	`bool`	`false`	`FLUX_DEBUG`	Enable debug mode.
`log_level`	`str`	`"INFO"`	`FLUX_LOG_LEVEL`	Logging level.
`log_format`	`str`	`"%(asctime)s - %(name)s - %(levelname)s - %(message)s"`	`FLUX_LOG_FORMAT`	Log message format.
`log_date_format`	`str`	`"%Y-%m-%d %H:%M:%S"`	`FLUX_LOG_DATE_FORMAT`	Date format in log messages.
`server_host`	`str`	`"localhost"`	`FLUX_SERVER_HOST`	Server bind address.
`server_port`	`int`	`8000`	`FLUX_SERVER_PORT`	Server bind port.
`home`	`str`	`".flux"`	`FLUX_HOME`	Flux home directory. Bootstrap token and default SQLite DB live here.
`cache_path`	`str`	`".cache"`	`FLUX_CACHE_PATH`	Cache directory path.
`local_storage_path`	`str`	`".data"`	`FLUX_LOCAL_STORAGE_PATH`	Local storage directory path.
`serializer`	`"json" \| "pkl"`	`"pkl"`	`FLUX_SERIALIZER`	Default serializer. Any other value raises `ValueError` at load.

Database

Top-level fields, also under [flux]. database_url accepts ${VAR} and $VAR interpolation.

Field	Type	Default	Env var	Purpose
`database_url`	`str`	`"sqlite:///.flux/flux.db"`	`FLUX_DATABASE_URL`	SQLAlchemy URL. Supports env-var interpolation.
`database_type`	`"sqlite" \| "postgresql"`	`"sqlite"` (inferred from URL prefix)	`FLUX_DATABASE_TYPE`	Backend type. Auto-set to `postgresql` when `database_url` starts with `postgresql://`.
`database_pool_size`	`int`	`20`	`FLUX_DATABASE_POOL_SIZE`	Connection pool size (PostgreSQL only).
`database_max_overflow`	`int`	`20`	`FLUX_DATABASE_MAX_OVERFLOW`	Maximum pool overflow (PostgreSQL only).
`database_executor_threads`	`int`	`16`	`FLUX_DATABASE_EXECUTOR_THREADS`	Server thread pool for blocking database calls. Keep at or below the pool size so threads never block waiting for a connection; `0` uses the asyncio default executor.
`database_pool_timeout`	`int` (seconds)	`30`	`FLUX_DATABASE_POOL_TIMEOUT`	Connection acquisition timeout.
`database_pool_recycle`	`int` (seconds)	`3600`	`FLUX_DATABASE_POOL_RECYCLE`	Connection recycle interval.
`database_health_check_interval`	`int` (seconds)	`300`	`FLUX_DATABASE_HEALTH_CHECK_INTERVAL`	Pool health-check interval.

Workers

Under [flux.workers]. Nested — env vars use double underscore.

Field	Type	Default	Env var	Purpose
`bootstrap_token`	`str \| None`	`None` (server auto-generates)	`FLUX_WORKERS__BOOTSTRAP_TOKEN`	Token workers present to `POST /workers/register`. Required on workers; server persists an auto-generated one to `<home>/bootstrap-token` if unset.
`server_url`	`str`	`"http://localhost:8000"`	`FLUX_WORKERS__SERVER_URL`	Server URL workers connect to.
`default_timeout`	`int` (seconds)	`0`	`FLUX_WORKERS__DEFAULT_TIMEOUT`	Default task timeout. `0` means no timeout.
`http_timeout`	`int` (seconds)	`30`	`FLUX_WORKERS__HTTP_TIMEOUT`	Timeout for worker HTTP calls to the server. `0` disables.
`checkpoint_retry_max_delay`	`int` (seconds)	`30`	`FLUX_WORKERS__CHECKPOINT_RETRY_MAX_DELAY`	Backoff cap between checkpoint send retries.
`terminal_checkpoint_deadline`	`int` (seconds)	`300`	`FLUX_WORKERS__TERMINAL_CHECKPOINT_DEADLINE`	Max time to keep retrying a terminal (finished-state) checkpoint before giving up and leaving the execution to the server reaper.
`retry_attempts`	`int`	`3`	`FLUX_WORKERS__RETRY_ATTEMPTS`	Default retry attempts for failed tasks.
`retry_delay`	`int` (seconds)	`1`	`FLUX_WORKERS__RETRY_DELAY`	Initial delay between retries.
`retry_backoff`	`int`	`2`	`FLUX_WORKERS__RETRY_BACKOFF`	Retry-delay multiplier.
`heartbeat_interval`	`int` (seconds)	`10`	`FLUX_WORKERS__HEARTBEAT_INTERVAL`	Seconds between server ping events.
`heartbeat_timeout`	`int` (seconds)	`30`	`FLUX_WORKERS__HEARTBEAT_TIMEOUT`	Seconds before a worker is considered stale.
`reconnect_max_delay`	`int` (seconds)	`60`	`FLUX_WORKERS__RECONNECT_MAX_DELAY`	Max backoff cap for worker reconnect.
`eviction_grace_period`	`int` (seconds)	`30`	`FLUX_WORKERS__EVICTION_GRACE_PERIOD`	Wait after marking worker stale before evicting.
`offline_ttl`	`int` (seconds)	`7200`	`FLUX_WORKERS__OFFLINE_TTL`	How long offline workers are kept in memory before pruning.
`module_cache_ttl`	`int` (seconds)	`300`	`FLUX_WORKERS__MODULE_CACHE_TTL`	Compiled-workflow-module cache TTL. `0` disables caching.
`module_cache_max_size`	`int`	`64`	`FLUX_WORKERS__MODULE_CACHE_MAX_SIZE`	LRU bound on cached workflow modules; least-recently-used entries are evicted beyond it. `0` = unbounded (legacy behavior).
`runners`	`list[str]`	`["inprocess", "subprocess"]`	`FLUX_WORKERS__RUNNERS`	Runners enabled on this worker, advertised at registration. Workflows declaring `runner=...` only dispatch to workers advertising it. Set as JSON array.
`default_runner`	`str`	`"subprocess"`	`FLUX_WORKERS__DEFAULT_RUNNER`	Runner used when a workflow does not declare one.
`subprocess_term_grace`	`float` (seconds)	`10.0`	`FLUX_WORKERS__SUBPROCESS_TERM_GRACE`	Wait after SIGTERM for a runner child to finish cancellation handling before SIGKILL.
`subprocess_memory_limit`	`int` (bytes)	`0`	`FLUX_WORKERS__SUBPROCESS_MEMORY_LIMIT`	Address-space limit per runner child (Linux only). `0` = unlimited.
`docker_image`	`str`	`""`	`FLUX_WORKERS__DOCKER_IMAGE`	Image the docker runner launches per execution; must have flux-core at a worker-compatible version. Required when `"docker"` is in `runners`.
`docker_network`	`str`	`""`	`FLUX_WORKERS__DOCKER_NETWORK`	Docker network for runner containers. Empty = docker default.
`docker_memory`	`str`	`""`	`FLUX_WORKERS__DOCKER_MEMORY`	Per-container memory limit, docker syntax (e.g. `"512m"`). Empty = unlimited.
`docker_cpus`	`float`	`0.0`	`FLUX_WORKERS__DOCKER_CPUS`	Per-container CPU limit (`docker --cpus`). `0` = unlimited.
`docker_extra_args`	`list[str]`	`[]`	`FLUX_WORKERS__DOCKER_EXTRA_ARGS`	Extra `docker run` arguments (volumes, env vars, `--user`, …). Set as JSON array.
`loop_lag_threshold`	`float` (seconds)	`1.0`	`FLUX_WORKERS__LOOP_LAG_THRESHOLD`	Event-loop lag beyond which a self-health probe counts as a breach; three consecutive breaches mark the worker unhealthy (it declines new work and advertises the state on heartbeats until three clean probes). `0` disables self-health monitoring.
`loop_lag_probe_interval`	`float` (seconds)	`1.0`	`FLUX_WORKERS__LOOP_LAG_PROBE_INTERVAL`	Seconds between event-loop lag probes.
`metrics_provider`	`str \| None`	`None`	`FLUX_WORKERS__METRICS_PROVIDER`	Dotted path (`"package.module:callable"`) to a sync or async callable returning `dict[str, float]`. The worker advertises the snapshot on heartbeat pongs; routing policies read it through `metric(...)` selectors.
`metrics_interval`	`float` (seconds)	`10.0`	`FLUX_WORKERS__METRICS_INTERVAL`	Seconds between metrics-provider refreshes.
`builtin_metrics`	`bool`	`true`	`FLUX_WORKERS__BUILTIN_METRICS`	Publish the built-in `flux.*` worker metrics (loop lag, load, failure/crash rates, durations, CPU/memory, …) on heartbeats so routing policies can rank on them without a `metrics_provider`.
`transient_fast_path`	`bool`	`true`	`FLUX_WORKERS__TRANSIENT_FAST_PATH`	Execute `call()` targets that are transient workflow objects in-process on the same worker (the mesh fast path). Disable to force every `call()` through the server.
`max_concurrent_executions`	`int`	`16`	`FLUX_WORKERS__MAX_CONCURRENT_EXECUTIONS`	Capacity the worker advertises at registration; the server never assigns beyond it. `0` = unlimited (legacy behavior).
`drain_timeout`	`int` (seconds)	`60`	`FLUX_WORKERS__DRAIN_TIMEOUT`	How long a stopping worker waits for running executions to finish before cancelling them. `0` = cancel immediately.
`register_rate_limit`	`str`	`"30/minute"`	`FLUX_WORKERS__REGISTER_RATE_LIMIT`	Per-client-IP rate limit for `POST /workers/register` (slowapi syntax). Empty string disables. Raise for large fleets restarting behind a shared NAT.

Dispatch

Under [flux.dispatch]. Server-side execution dispatch — see Dispatch modes for when to switch off the default.

Field	Type	Default	Env var	Purpose
`mode`	`"poll" \| "event"`	`"poll"`	`FLUX_DISPATCH__MODE`	Dispatch strategy. `poll` is the legacy per-worker query loop (~5 queries per worker per 0.5 s); `event` runs one dispatcher task per replica that batch-claims on wakeups (LISTEN/NOTIFY on PostgreSQL) — the scalable mode for large fleets.
`batch_size`	`int`	`64`	`FLUX_DISPATCH__BATCH_SIZE`	Max executions claimed per dispatcher wakeup (event mode).
`fallback_interval`	`float` (seconds)	`15.0`	`FLUX_DISPATCH__FALLBACK_INTERVAL`	Dispatcher safety-net tick (event mode); covers missed notifications, which are wakeups only and carry no data.

Retention

Under [flux.retention]. Execution-history cleanup — see Retention for semantics.

Field	Type	Default	Env var	Purpose
`enabled`	`bool`	`false`	`FLUX_RETENTION__ENABLED`	Delete terminal executions (and their events/approvals/sessions) older than `retention_days`. Off by default so upgrades never silently remove history; enable in production or the executions tables grow without bound.
`retention_days`	`int`	`30`	`FLUX_RETENTION__RETENTION_DAYS`	Age (days since last event) after which terminal executions are deleted.
`sweep_interval`	`int` (seconds)	`3600`	`FLUX_RETENTION__SWEEP_INTERVAL`	Seconds between retention sweeps.
`batch_size`	`int`	`500`	`FLUX_RETENTION__BATCH_SIZE`	Executions deleted per transaction during a sweep.

Scheduling

Under [flux.scheduling]. The scheduler runs in-process inside the server.

Field	Type	Default	Env var	Purpose
`poll_interval`	`float` (seconds)	`30.0`	`FLUX_SCHEDULING__POLL_INTERVAL`	How often the scheduler polls for due schedules.
`schedule_check_tolerance`	`float` (seconds)	`1.0`	`FLUX_SCHEDULING__SCHEDULE_CHECK_TOLERANCE`	Tolerance for cron schedule matching.
`once_schedule_tolerance`	`float` (seconds)	`60.0`	`FLUX_SCHEDULING__ONCE_SCHEDULE_TOLERANCE`	Tolerance for one-time schedule matching.
`auto_schedule_enabled`	`bool`	`true`	`FLUX_SCHEDULING__AUTO_SCHEDULE_ENABLED`	Auto-create schedules from `@workflow.with_options(schedule=...)`.
`auto_schedule_suffix`	`str`	`"_auto"`	`FLUX_SCHEDULING__AUTO_SCHEDULE_SUFFIX`	Suffix appended to auto-created schedule names.

Security

Top-level fields under [flux.security]. Encryption and auth live in their own sub-tables.

Field	Type	Default	Env var	Purpose
`execution_token_secret`	`str \| None`	`None` (required in production)	`FLUX_SECURITY__EXECUTION_TOKEN_SECRET`	HMAC secret for signing execution tokens.
`execution_token_ttl`	`int` (seconds)	`86400` (24 hours; earlier releases defaulted to 7 days)	`FLUX_SECURITY__EXECUTION_TOKEN_TTL`	Execution-token lifetime. The token is scoped to a single execution and minted fresh on every dispatch and resume, so it only needs to outlive one continuous run.

Provider validation order on the server is ExecutionToken → OIDC → API key: each incoming request is checked against the execution-token provider first, then OIDC, then API key.

Encryption

Under [flux.security.encryption]. The encryption key is a passphrase fed to PBKDF2 (SHA-256, 1,000,000 iterations) — Flux does not hex-decode or base64-decode the value.

Field	Type	Default	Env var	Purpose
`encryption_key`	`str \| None`	`None` (required for secrets store)	`FLUX_SECURITY__ENCRYPTION__ENCRYPTION_KEY`	Master passphrase for encrypting secrets and configs at rest.

Auth

Under [flux.security.auth]. The master switch; provider-specific config lives in the OIDC and API-key sub-tables below.

Field	Type	Default	Env var	Purpose
`enabled`	`bool`	`false`	`FLUX_SECURITY__AUTH__ENABLED`	Master switch for authentication. Enabling a provider forces this on; enabling it with no provider configured is rejected at startup.
`resolution_cache_ttl`	`float` (seconds)	`30.0`	`FLUX_SECURITY__AUTH__RESOLUTION_CACHE_TTL`	Per-process cache for token-to-identity and principal-to-permissions resolution (`0` disables). Mutations invalidate the local replica immediately; other replicas converge within the TTL, so a revoked credential can remain usable there for up to this long — keep it short.
`allow_anonymous`	`bool`	`false`	`FLUX_SECURITY__AUTH__ALLOW_ANONYMOUS`	When auth is disabled, must be `true` to permit anonymous state-changing requests (POST/PUT/PATCH/DELETE). No effect when auth is enabled.

OIDC

Under [flux.security.auth.oidc].

Field	Type	Default	Env var	Purpose
`enabled`	`bool`	`false`	`FLUX_SECURITY__AUTH__OIDC__ENABLED`	Toggle OIDC auth.
`issuer`	`str`	`""`	`FLUX_SECURITY__AUTH__OIDC__ISSUER`	OIDC issuer URL.
`audience`	`str`	`""`	`FLUX_SECURITY__AUTH__OIDC__AUDIENCE`	Expected audience claim.
`roles_claim`	`str`	`"roles"`	`FLUX_SECURITY__AUTH__OIDC__ROLES_CLAIM`	Deprecated. Flux reads roles from the principals registry, not the token.
`jwks_cache_ttl`	`int` (seconds)	`3600`	`FLUX_SECURITY__AUTH__OIDC__JWKS_CACHE_TTL`	JWKS-key cache lifetime.
`clock_skew`	`int` (seconds)	`30`	`FLUX_SECURITY__AUTH__OIDC__CLOCK_SKEW`	Leeway for `exp`/`nbf` claims.
`default_user_roles`	`list[str]`	`[]`	`FLUX_SECURITY__AUTH__OIDC__DEFAULT_USER_ROLES`	Roles auto-granted to a new OIDC user. Set as JSON array.

API keys

Under [flux.security.auth.api_keys]. Keys themselves are managed via flux principals.

Field	Type	Default	Env var	Purpose
`enabled`	`bool`	`false`	`FLUX_SECURITY__AUTH__API_KEYS__ENABLED`	Toggle API-key auth.
`worker_key_ttl`	`int` (seconds)	`604800` (7 days)	`FLUX_SECURITY__AUTH__API_KEYS__WORKER_KEY_TTL`	Lifetime of API keys minted for workers at registration (`0` = never expire). Workers re-register automatically on the first 401 after expiry, so keys rotate without operator action.

Observability

Under [flux.observability]. The OpenTelemetry pipeline runs only when enabled and the observability extra is installed.

Field	Type	Default	Env var	Purpose
`enabled`	`bool`	`false`	`FLUX_OBSERVABILITY__ENABLED`	Master toggle for OTel.
`service_name`	`str`	`"flux"`	`FLUX_OBSERVABILITY__SERVICE_NAME`	OTel `service.name` resource attribute.
`otlp_endpoint`	`str \| None`	`None`	`FLUX_OBSERVABILITY__OTLP_ENDPOINT`	OTLP collector endpoint (e.g. `http://localhost:4317`).
`otlp_protocol`	`"grpc" \| "http"`	`"grpc"`	`FLUX_OBSERVABILITY__OTLP_PROTOCOL`	OTLP exporter protocol: `grpc` or `http` (HTTP/protobuf).
`prometheus_enabled`	`bool`	`true`	`FLUX_OBSERVABILITY__PROMETHEUS_ENABLED`	Expose `/metrics` for Prometheus scraping.
`trace_sample_rate`	`float` (0.0–1.0)	`1.0`	`FLUX_OBSERVABILITY__TRACE_SAMPLE_RATE`	Trace sampling rate.
`metric_export_interval`	`int` (seconds)	`60`	`FLUX_OBSERVABILITY__METRIC_EXPORT_INTERVAL`	OTLP metric push interval.
`resource_attributes`	`dict[str, str]`	`{}`	`FLUX_OBSERVABILITY__RESOURCE_ATTRIBUTES`	Extra OTel resource attributes. Set as JSON object.

MCP

Under [flux.mcp]. Configures the MCP server started by flux start mcp.

Field	Type	Default	Env var	Purpose
`name`	`str`	`"flux-workflows"`	`FLUX_MCP__NAME`	MCP server name advertised to clients.
`host`	`str`	`"localhost"`	`FLUX_MCP__HOST`	Bind address.
`port`	`int`	`8080`	`FLUX_MCP__PORT`	Bind port.
`server_url`	`str`	`"http://localhost:8000"`	`FLUX_MCP__SERVER_URL`	Flux server URL the MCP server proxies to.
`transport`	`"stdio" \| "streamable-http" \| "sse"`	`"streamable-http"`	`FLUX_MCP__TRANSPORT`	MCP transport protocol.

Two cross-cutting notes

auth.enabled and the providers. auth.enabled is a real settable field ([flux.security.auth] enabled = true, or FLUX_SECURITY__AUTH__ENABLED). Enabling either provider ([flux.security.auth.oidc] or [flux.security.auth.api_keys]) forces auth.enabled to true. Setting auth.enabled = true with no provider configured is rejected at startup — auth needs at least one provider to validate against.

${VAR} interpolation. A field validator on database_url expands ${VAR} and $VAR references from the process environment at load time. Unresolved references are left literal. This is the only field that does interpolation; other string fields take env values directly via FLUX_*.

Server

Database

Workers

Dispatch

Retention

Scheduling

Security

Encryption

Auth

OIDC

API keys

Observability

MCP

Two cross-cutting notes

See also