Skip to content

Architecture for operators

What runs on a Flux server, how the parts talk, and where the data lives.

Browsers, phones and MCP clients reach one HTTPS reverse proxy, which forwards to the Flux API on the host’s loopback port. The API and the worker share PostgreSQL and the files volume. The keyring sits on an internal network with only the API and the worker. The one-shot migrate service runs before them. Optional: the agent runtime and LiveKit for live media. The worker and API make outbound connections for mail, push, AI providers and link cards.

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.

  • 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 files volume, shared by api and worker.
  • The api and worker ask the keyring for keys of unlocked encrypted spaces over the internal network, with a token.
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

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.