app/docs/reference/configuration.md

Configuration

Most installations can keep the defaults. Settings come from environment variables and an env file:

How you start Fluksio	Env file
fluksio serve	<data-dir>/env, unless FLUKSIO_ENV_FILE names another file
Docker with the Makefile	.env in this repository's root

Exported variables override the file. fluksio serve flags override both. For CLI installations, select storage with --data-dir, FLUKSIO_HOME or --global; see The fluksio command.

Storage

Variable	Default	Purpose
DATA_DIR	flow-data; CLI uses ./.fluksio or ~/.fluksio with --global	base directory for instance data
DATABASE_URL	SQLite at $DATA_DIR/fluksio.db	SQLite URL; other database engines are unsupported
FLOWS_DIR	$DATA_DIR/flows	flow git repository
SECRETS_FILE	$DATA_DIR/secrets.enc	encrypted credentials
ALERTS_FILE	$DATA_DIR/alerts.json	alert channels and rules
WEBPUSH_FILE	$DATA_DIR/webpush.json	push keys and browser subscriptions
PROVISIONERS_FILE	$DATA_DIR/provisioners.json	optional worker provisioning configuration
PANELS_FILE	$DATA_DIR/panels.json	wall-panel pairings
OAUTH_PRIVATE_KEY_FILE	$DATA_DIR/oauth-key.pem	agent and worker signing key
CLOUD_CONFIG_FILE	$DATA_DIR/cloud.json	optional portal enrollment
AI_CONFIG_FILE	$DATA_DIR/ai.json	optional assistant provider configuration
CHATS_DIR	$DATA_DIR/chats	assistant transcripts
NODE_VENV	auto	interpreter for node code

Changing DATA_DIR moves the derived paths unless you set them individually. Docker stores instance data under /data on the app-flow-data volume.

NODE_VENV value	Behavior
auto	keeps an existing managed venv; otherwise uses the installation's venv when available, or creates a managed one
managed	creates a venv under DATA_DIR; the Modules screen manages its packages
interpreter or venv path	uses the specified Python environment

Docker uses managed. When Fluksio adopts your own venv, the Modules screen is read-only; install packages into that environment yourself.

Back up the whole data directory and the persistent SECRET_KEY. In Docker, keep .env and app-flow-data; back up app-redis-data too when preserving live state. Compose prefixes volume names with the project name fluksio-app. Keep runtime files on persistent storage so rebuilds preserve credentials, pairings and subscriptions.

Live state

Variable	Default	Purpose
REDIS_HOST	unset	unset uses memory; a Redis host enables persistent flow state
REDIS_PORT	6379	Redis port

Live state includes message values, node memory and queued work. In-memory state is lost on restart. The Docker stack uses Redis with append-only persistence on its own app-redis-data volume. Its default sync policy may lose about a second of recent writes after an unclean shutdown.

Accounts and access

Variable	Default	Purpose
SECRET_KEY	generated	signs sessions and encrypts the secrets store; the CLI persists it and make init writes it to .env
ACCESS_TOKEN_EXPIRE_MINUTES	11520 (8 days)	session-token lifetime
FIRST_SUPERUSER	unset	initial administrator email; the CLI creates an account if needed
FIRST_SUPERUSER_PASSWORD	unset	initial password; the CLI generates and prints one if needed
DOMAIN	localhost	API hostname and OAuth issuer; Docker also uses it for routing
FRONTEND_HOST	http://localhost:5173	interface URL for links and metadata
BACKEND_CORS_ORIGINS	[]	allowed origins, as comma-separated URLs or a JSON list; FRONTEND_HOST is also allowed
FORWARDED_ALLOW_IPS	127.0.0.1	trusted proxies; Docker adds 172.16.0.0/12
SIGNUP_ENABLED	false	allows account creation from the login page; otherwise use Admin → Users

!!! warning "Keep your secret key"

Changing `SECRET_KEY` signs everyone out and makes existing encrypted
secrets unreadable. Back it up with your data.

Interface API address

VITE_API_URL is a frontend build argument, so changing it requires rebuilding the frontend image.

Setup	Value
Production Docker	set .env to https://api.<your-domain>
make dev-local	overlay sets http://api.localhost by default
make dev-lan	overlay sets an empty value, using /api on the page's own origin

Without an explicit value, the production Compose file falls back to https://api.${DOMAIN}. Set FRONTEND_HOST and BACKEND_CORS_ORIGINS to match your deployment as well; make init generates secrets, not deployment URLs.

The LAN overlay also configures nginx to proxy /api and WebSocket requests to the backend. An empty value needs that proxy when the frontend and backend are served separately. See facility automation for deployment settings.

Image options

WITH_FFMPEG=true in .env installs ffmpeg into the backend image on the next build, for node code that transcodes video. It is off by default because it adds about 400 MB.

Environment

Variable	Default	Purpose
ENVIRONMENT	local	local, staging or production
PRIVATE_API_ENABLED	false	test endpoints; also requires ENVIRONMENT=local
API_DOCS_ENABLED	false	opens /docs, /redoc and /api/v1/openapi.json to network callers outside production
TZ	host timezone; Docker defaults to UTC	timezone used by cron schedules

API documentation is available to loopback callers outside production. API_DOCS_ENABLED=true opens it to other callers, as the Docker development stack does. Production disables it entirely. Staging and production also refuse changethis values for the session key or administrator password.

Set TZ in .env for schedules that should follow local time, such as Europe/Berlin.

Engine and resources

Variable	Default	Purpose
FLOW_MAX_WORKERS	4	local node-code subprocesses
FLOW_MAX_CASCADES	4	concurrent live message cascades
FLOW_MAX_RUNS	4	concurrent batch runs
FLOW_NODE_TIMEOUT	0	maximum node silence in seconds, unless the node overrides it; 0 disables
FLOW_CPUS	0	CPU budget; 0 detects cores and reserves two for the engine
FLOW_GPUS	0	local GPU count; 0 counts the engine's CUDA_VISIBLE_DEVICES, or NVIDIA device nodes without it
FLOW_RAM	0	memory budget in MB; 0 detects host/container memory and reserves 1 GiB
FLOW_WORKER_MAX_RSS_MB	0	retire a local worker above this memory use after a call; 0 disables
FLOW_NODE_STOP_TIMEOUT	5	seconds a node gets to stop during a rebuild before the rebuild moves on
FLOW_PIPELINE_REBUILD_WAIT	15	seconds a request waits for a running whole-pipeline rebuild before it gets a 503
FLOW_REBUILD_WAIT	5	the same for a single flow's rebuild, such as a deploy
FLOW_RESTART_BACKOFF	[1,5,30,60]	seconds between restarts of a crashed node loop; the last step repeats
FLOW_CANCEL_GRACE	5	seconds a cancelled node loop gets to stop before it is abandoned
OBS_RETENTION_DAYS	30	retention for metrics, events and run records

The three concurrency limits must be at least 1. They also have CLI flags: --max-workers, --max-cascades and --max-runs. When FLOW_MAX_WORKERS or FLOW_MAX_CASCADES is more than four times the machine's core count, the engine logs a warning at startup and uses the value anyway. Resource flags are --gpus, --ram and --worker-max-rss.

Nodes with declared resources are scheduled against the available budget. Undeclared nodes use the shared pool and receive thread caps. Attached workers report their own inventory; the engine's resource settings describe only its own machine. See Remote workers and the Workers screen.

When the engine runs with CUDA_VISIBLE_DEVICES, a node's card is named the way that list names it, so under 2,3 the first card is device 2. UUID and MIG entries are passed on as written.

Artifacts

Variable	Default	Purpose
MAX_ARTIFACT_BYTES	2147483648 (2 GiB)	upload limit; 0 removes it
ARTIFACT_GC_INTERVAL_S	3600	cleanup interval; 0 disables
ARTIFACT_GC_GRACE_S	3600	minimum age before cleanup
ARTIFACT_VOLATILE_DIR	auto-detected	live-media directory under /dev/shm, or the temporary directory
ARTIFACT_VOLATILE_BYTES	50331648 (48 MiB)	live-media ring size; 0 stores volatile saves durably

Cleanup removes durable artifacts no longer referenced by recorded runs or current messages, and pauses while a run is active. Volatile artifacts use a bounded ring; the oldest disappear as it fills. Recorded run outputs are copied into durable storage. If you increase the ring size in Docker, increase shm_size too.

Agents

Variable	Default	Purpose
MCP_ENABLED	false	enables /mcp and OAuth client registration; .env.example sets it to true
MCP_TOKEN_EXPIRE_MINUTES	60	access-token lifetime
MCP_REFRESH_EXPIRE_DAYS	30	refresh-token lifetime
OAUTH_CODE_EXPIRE_SECONDS	60	authorization-code lifetime

See Agents over MCP.

Mail and monitoring

Password-reset mail requires SMTP_HOST and EMAILS_FROM_EMAIL.

Variable	Default
SMTP_HOST	unset
SMTP_PORT	587
SMTP_USER / SMTP_PASSWORD	unset
SMTP_TLS / SMTP_SSL	true / false
EMAILS_FROM_EMAIL	unset
EMAILS_FROM_NAME	PROJECT_NAME, normally Fluksio
EMAIL_RESET_TOKEN_EXPIRE_HOURS	48
SENTRY_DSN	unset; enables error reporting when configured

GET /api/v1/utils/health/ checks the event loop and state backend. Docker uses it as a health check; make up also starts the autoheal service to restart an unhealthy backend.