Configuration¶

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

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¶

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

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. The single container keeps both, and its Redis, on the /data volume. The operator stack under docker/ keeps .env and app-flow-data, plus app-redis-data for live state. Compose prefixes volume names with the project name. Keep runtime files on persistent storage so rebuilds preserve credentials, pairings and subscriptions.

Live state¶

Live state includes message values, node memory and queued work. In-memory state is lost on restart. The Docker image starts a Redis of its own with append-only persistence in /data/redis whenever REDIS_HOST is unset. Set REDIS_HOST to use an external one instead, as the operator stack does with its app-redis-data volume. The default sync policy may lose about a second of recent writes after a power cut.

Accounts and access¶

Interface address¶

The image serves the interface and the API on one origin, so the interface calls the API as a path on whatever address served it. One build works behind any port, hostname or reverse proxy. FRONTEND_DIST points at the built interface and is set by the image. A checkout leaves it empty and runs the Vite dev server, which needs its origin in BACKEND_CORS_ORIGINS.

Image options¶

The EXTRAS build argument picks the optional features built into the image, comma separated. Empty, the default, is the minimal engine.

A node whose extra is missing says so on the canvas. The same names work as pip extras, such as pip install 'fluksio[mqtt]'. Connector packages built with make connectors are installed into the image too.

Environment¶

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. make up, make update and make dev warn when .env lacks it, or any other key .env.example lists that Compose would otherwise default.

Engine and resources¶

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¶

Cleanup removes durable artifacts no longer referenced by recorded runs or current messages, and pauses while a run is active. Volatile artifacts live in a bounded ring in the engine's memory, and the oldest disappear as it fills. Recorded run outputs are copied into durable storage. A worker in the engine's container writes its frames to ARTIFACT_VOLATILE_DIR instead, which the engine trims to the same size every few seconds. If workers publish frames under Docker, raise shm_size with the ring size.

Agents¶

See Agents over MCP.

Mail and monitoring¶

Password-reset mail requires SMTP_HOST and EMAILS_FROM_EMAIL.

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.