Server configuration
Configuring the Flux server — config sources, precedence, environment variables, and the complete options table.
Flux loads configuration once at process startup via pydantic-settings. There is no runtime reload — change a setting on a running server by editing the source, then restarting. This page maps every server-level field to its TOML key, environment variable, type, and default.
Where configuration comes from
Flux reads from four places, listed highest precedence first:
- Environment variables prefixed
FLUX_, with double underscore for nested sections (FLUX_SERVER_PORT,FLUX_WORKERS__BOOTSTRAP_TOKEN,FLUX_SECURITY__ENCRYPTION__ENCRYPTION_KEY). flux.tomlin the current working directory, under a top-level[flux]table.[tool.flux]inpyproject.tomlin the current working directory.- Built-in defaults from the Pydantic models.
flux start server accepts --host/-h and --port/-p as final overrides. There are no other CLI flags for server-level config.
The flux.toml shape
[flux]
log_level = "INFO"
server_host = "0.0.0.0"
server_port = 8000
home = ".flux"
database_url = "postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:5432/${DB_NAME}"
database_type = "postgresql"
database_pool_size = 10
[flux.workers]
# Omit to let the server auto-generate one at <home>/bootstrap-token
# bootstrap_token = "..."
module_cache_ttl = 300
[flux.security.encryption]
# encryption_key = "<openssl rand -hex 32>"
[flux.observability]
enabled = false
prometheus_enabled = trueflux.toml is the canonical location; the same keys also work under [tool.flux] in pyproject.toml. Environment variables in database_url are expanded — both ${VAR} and $VAR forms.
Server options
All fields below live at the top level of the [flux] table. Types are the Pydantic field types; defaults are the values that apply when neither TOML nor env vars supply anything.
| Field | Type | Default | Environment variable |
|---|---|---|---|
debug | bool | false | FLUX_DEBUG |
log_level | str | "INFO" | FLUX_LOG_LEVEL |
log_format | str | "%(asctime)s - %(name)s - %(levelname)s - %(message)s" | FLUX_LOG_FORMAT |
log_date_format | str | "%Y-%m-%d %H:%M:%S" | FLUX_LOG_DATE_FORMAT |
server_host | str | "localhost" | FLUX_SERVER_HOST |
server_port | int | 8000 | FLUX_SERVER_PORT |
home | str | ".flux" | FLUX_HOME |
cache_path | str | ".cache" | FLUX_CACHE_PATH |
local_storage_path | str | ".data" | FLUX_LOCAL_STORAGE_PATH |
serializer | "json" | "pkl" | "pkl" | FLUX_SERIALIZER |
database_url | str | "sqlite:///.flux/flux.db" | FLUX_DATABASE_URL |
database_type | "sqlite" | "postgresql" | "sqlite" (inferred from database_url) | FLUX_DATABASE_TYPE |
database_pool_size | int | 5 | FLUX_DATABASE_POOL_SIZE |
database_max_overflow | int | 10 | FLUX_DATABASE_MAX_OVERFLOW |
database_pool_timeout | int (seconds) | 30 | FLUX_DATABASE_POOL_TIMEOUT |
database_pool_recycle | int (seconds) | 3600 | FLUX_DATABASE_POOL_RECYCLE |
database_health_check_interval | int (seconds) | 300 | FLUX_DATABASE_HEALTH_CHECK_INTERVAL |
serializer must be json or pkl (any other value raises ValueError at load). database_type auto-infers to postgresql when database_url starts with postgresql://. For backend choice and tuning see Storage backends.
Scheduling section
The server runs the scheduler in-process. These keys live under [flux.scheduling].
| Field | Type | Default | Environment variable |
|---|---|---|---|
poll_interval | float (seconds) | 30.0 | FLUX_SCHEDULING__POLL_INTERVAL |
schedule_check_tolerance | float (seconds) | 1.0 | FLUX_SCHEDULING__SCHEDULE_CHECK_TOLERANCE |
once_schedule_tolerance | float (seconds) | 60.0 | FLUX_SCHEDULING__ONCE_SCHEDULE_TOLERANCE |
auto_schedule_enabled | bool | true | FLUX_SCHEDULING__AUTO_SCHEDULE_ENABLED |
auto_schedule_suffix | str | "_auto" | FLUX_SCHEDULING__AUTO_SCHEDULE_SUFFIX |
Security section
[flux.security] exposes the execution-token settings; nested tables cover encryption and auth. Full coverage is in the security pages; the server-level keys are:
| Field | Type | Default | Environment variable |
|---|---|---|---|
security.auth.enabled | bool | false | FLUX_SECURITY__AUTH__ENABLED |
execution_token_secret | str | None | None (required in production) | FLUX_SECURITY__EXECUTION_TOKEN_SECRET |
execution_token_ttl | int (seconds) | 604800 (7 days) | FLUX_SECURITY__EXECUTION_TOKEN_TTL |
security.encryption.encryption_key | str | None | None | FLUX_SECURITY__ENCRYPTION__ENCRYPTION_KEY |
security.auth.enabled is a real, settable field — FLUX_SECURITY__AUTH__ENABLED=true enables authentication directly. The server validates the combination at startup: enabling auth with no provider configured ([flux.security.auth.oidc] or [flux.security.auth.api_keys]) is rejected with an error, and conversely enabling any provider implies enabled=true. See Authentication overview.
[flux.workers] and [flux.observability] have their own pages — see Running workers, Metrics, and Tracing.
Reload behaviour
Configuration is read once at startup and cached in a singleton (Configuration.get()). Editing flux.toml or exporting a new env var on a running server has no effect — restart the process. The Python API exposes .reload() and .override(...), but these are for tests.
What can go wrong
Wrong type in TOML. server_port = "8000" (string, not int) raises a Pydantic ValidationError at startup naming the field and expected type. Do not quote integers in TOML.
Wrong section. Top-level fields like server_host belong under [flux], not [flux.server] — there is no [flux.server] table in the model, so keys placed there are silently ignored.
Encryption key not set. Saving a secret or writing an encrypted config while security.encryption.encryption_key is None raises a clear error at encrypt time. Generate one with openssl rand -hex 32. See Encryption at rest.
CLI groups, not config keys. The start command is flux start server, not flux server start. Config keys themselves are stable in 0.56.0 — no recent renames — but CLI commands are grouped under start. See Running the server.
What’s next
- Running the server — process supervision, ports, health checks
- Storage backends — SQLite versus PostgreSQL, pool tuning
- Authentication overview — API keys, OIDC, principals
- Encryption at rest — the encryption-key surface
- Configuration reference — every field across every section