Architecture for operators
What runs on a Flux server, how the parts talk, and where the data lives.
Services
Section titled “Services”| Service | Image | Does | Ports and networks |
|---|---|---|---|
db |
PostgreSQL 18, pinned by digest | All records, the job queue and the event log | none published; default |
migrate |
Flux | Applies new SQL migrations in order, each in its own transaction, then exits | default |
api |
Flux | The web app and PWA, the HTTP API, /mcp for agents, WebSocket streams, sign-in and OAuth |
127.0.0.1:FLUX_PORT → 8080; default, keyring |
worker |
Flux | Queued jobs: notifications, email, Web Push, agent runs and schedules, encryption key rotation | default, keyring |
keyring |
Flux | Holds the boot key of encrypted spaces in memory | keyring only (internal) |
Optional parts:
| Part | Turned on by | Adds |
|---|---|---|
| Agent runtime | FLUX_AGENT_RUNTIME (guide) |
runtime-install, runtime-manager, runtime-egress and one runtime-1 for everyone, each person under their own user id, on their own internal networks; the egress proxy is their only way out |
| Built-in HTTPS | An https FLUX_PUBLIC_ORIGIN with FLUX_TRUSTED_PROXIES empty (docker/compose.https.yaml, guide) |
proxy, Caddy on 80 and 443 with automatic certificates, on an edge network shared only with api, which trusts exactly its address |
| Live media | FLUX_CALLS=on (docker/compose.live.yaml, guide) |
livekit, with ICE and TURN ports reached directly by browsers, and signaling only through the API at /media |
| Hot-reload development | ./flux dev |
A Vite server and a mail catcher; never on a server |
api, worker, keyring and migrate run one image at one revision. A release’s ./flux pulls it by the digest that
docker/release.env names; a developer’s source checkout builds it from the checkout.
How requests flow
Section titled “How requests flow”- Browsers, installed phone apps and MCP clients use one origin,
FLUX_PUBLIC_ORIGIN, through your TLS reverse proxy. Everything is under it: pages,/api/*,/mcp, OAuth discovery under/.well-known/, WebSocket upgrades and, with live media,/media/*. - The API writes to PostgreSQL. Each write records an event; the live stream sends those events to open browsers, and the worker picks up queued jobs from the same database. The API and worker do not call each other directly, except that the worker asks the API for a short-lived token when it starts an agent’s run.
- Files go to the
filesvolume, shared byapiandworker. - The
apiandworkerask thekeyringfor keys of unlocked encrypted spaces over the internal network, with a token.
Data and secrets
Section titled “Data and secrets”| What | Where | Backed up by ./flux backup |
|---|---|---|
| Records, history, queue | volume <FLUX_PROJECT>_pgdata |
yes (database dump) |
| Uploaded files | volume <FLUX_PROJECT>_files |
yes |
| Settings and secrets | docker/.env (release: .env) |
yes (copied into the archive) |
| Boot key of encrypted spaces | keyring memory only | no, by design: a restart locks them |
| Agent runtime logins | the runtime’s volume | no (why) |
| OIDC client secret, background key | files you keep on the host | no: keep them yourself |
What leaves the server
Section titled “What leaves the server”Only what you turn on, and what people use: SMTP to your mail server, Web Push to the browser vendors’ push services,
requests to the AI providers that people connect, link-card fetches (off by default), GitHub (when
the App is configured), MCP client metadata documents when a local client signs in, and, with the agent
runtime, the vendors’ CLIs through the egress proxy to their documented hosts. Agents’ web reading and search are on by
default (FLUX_WEB_READS): when a person’s agent needs a public web page, the API server fetches it, and the provider’s search receives
the agent’s query; FLUX_WEB_READS=off stops both. Flux itself sends no telemetry.
The code-level picture, module boundaries and dependency rules are in the developer architecture.