Skip to content

Configuration reference

Flux is configured with environment variables in one private file, docker/.env in the Flux folder (./flux up creates it from docker/.env.example with new secrets). Compose reads the file and passes each value to the services that need it. After a change, apply it with ./flux up. A variable exported in your shell overrides the file, so do not export Flux variables on a server. Keep the file private (chmod 600) and keep it with your backups: it holds the database password and the secrets that cannot change.

Each variable lists its type, its default, the services that receive it and where it applies: release is the docker/compose.yaml that ./flux runs in a release, source the source checkout’s Compose file that ./flux runs for developers, an overlay an optional extra Compose file, and ./flux the launcher itself. Override only means the application reads it but no shipped Compose file passes it in: add it under the service’s environment: in docker/compose.override.yaml, which ./flux includes when it exists. A wrong value stops the service at start with a message that names the variable.

Variable Group Default
FLUX_AGENT_RUNTIME Agent runtime: the owner’s own Claude Code or Codex empty
FLUX_AGENT_RUNTIME_COMMERCIAL_TERMS Agent runtime: the owner’s own Claude Code or Codex empty
FLUX_AGENT_RUNTIME_IDLE_DAYS Agent runtime: the owner’s own Claude Code or Codex empty
FLUX_AGENT_RUNTIME_RECONCILE_MS Agent runtime: the owner’s own Claude Code or Codex 10000
FLUX_AI_PRIVATE_TARGETS AI providers empty
FLUX_API_MEMORY Memory limits 1536m
FLUX_AUTH_RATE_LIMIT Accounts, sign-up and sessions true
FLUX_AUTH_SECRET Accounts, sign-up and sessions required
FLUX_BACKGROUND_KEY_HOST_FILE AI providers empty; made by ./flux up
FLUX_BACKUP_DIR Source checkout, launcher and checks backups/ in the checkout
FLUX_CALLS Live media: LiveKit and TURN off
FLUX_COWORK_WATCHDOG_SECONDS Source checkout, launcher and checks 300
FLUX_DB_CONNECT_TIMEOUT_MS Database 1500
FLUX_DB_MEMORY Memory limits 768m
FLUX_DEMO_OWNER_PASSWORD Source checkout, launcher and checks empty; generated by ./flux
FLUX_DEMO_PARTNER_PASSWORD Source checkout, launcher and checks empty; generated by ./flux
FLUX_DEV_POLL Source checkout, launcher and checks false
FLUX_DEV_PORT Source checkout, launcher and checks 5173
FLUX_EMBEDDINGS Local embeddings (optional) off
FLUX_EMBEDDINGS_CPUS Local embeddings (optional) 1
FLUX_EMBEDDINGS_MEMORY Local embeddings (optional) 6g
FLUX_FIXTURE_TOKEN Source checkout, launcher and checks required (source); release: empty
FLUX_GITHUB_APP_ID GitHub App (optional) empty
FLUX_GITHUB_APP_SLUG GitHub App (optional) empty
FLUX_GITHUB_CLIENT_ID GitHub App (optional) empty
FLUX_GITHUB_CLIENT_SECRET GitHub App (optional) empty
FLUX_GITHUB_DELIVERY GitHub App (optional) webhook
FLUX_GITHUB_ENCRYPTION_KEY GitHub App (optional) empty
FLUX_GITHUB_WEBHOOK_SECRET GitHub App (optional) empty
FLUX_KEYRING Encrypted spaces and the keyring on
FLUX_KEYRING_MEMORY Memory limits 128m
FLUX_KEYRING_TOKEN Encrypted spaces and the keyring empty; generated by ./flux
FLUX_KEY_PIN_SECRET Encrypted spaces and the keyring empty; generated by ./flux
FLUX_LINK_PREVIEWS Collaboration, link cards and the live stream off
FLUX_LIVEKIT_API_KEY Live media: LiveKit and TURN required
FLUX_LIVEKIT_API_SECRET Live media: LiveKit and TURN required
FLUX_LIVEKIT_DOMAIN Live media: LiveKit and TURN required
FLUX_LIVEKIT_ICE_TCP_PORT Live media: LiveKit and TURN 7881
FLUX_LIVEKIT_ICE_UDP_PORT Live media: LiveKit and TURN 7882
FLUX_LIVEKIT_MEDIA_CIDR Live media: LiveKit and TURN 0.0.0.0/0
FLUX_LIVEKIT_PUBLIC_IP Live media: LiveKit and TURN required
FLUX_LIVEKIT_TURN_CERT_DIR Live media: LiveKit and TURN required
FLUX_LIVEKIT_TURN_DOMAIN Live media: LiveKit and TURN required
FLUX_LIVEKIT_TURN_TLS_BIND Live media: LiveKit and TURN 0.0.0.0
FLUX_LIVEKIT_TURN_TLS_HOST_PORT Live media: LiveKit and TURN 443
FLUX_LIVEKIT_TURN_UDP_PORT Live media: LiveKit and TURN 3478
FLUX_LIVE_EDITING Collaboration, link cards and the live stream on
FLUX_MAILPIT_PORT Source checkout, launcher and checks 8025
FLUX_MAIL_FROM Email empty (./flux dev: Flux dev <flux-dev@localhost>)
FLUX_NO_CACHE Source checkout, launcher and checks empty
FLUX_OIDC_CLIENT_ID Single sign-on (OpenID Connect) empty
FLUX_OIDC_CLIENT_SECRET_HOST_FILE Single sign-on (OpenID Connect) empty
FLUX_OIDC_CONFIRMATION_MAX_AGE Single sign-on (OpenID Connect) empty
FLUX_OIDC_ISSUER Single sign-on (OpenID Connect) empty
FLUX_OIDC_LABEL Single sign-on (OpenID Connect) empty
FLUX_OIDC_STANDING Single sign-on (OpenID Connect) refresh
FLUX_OIDC_STANDING_INTERVAL_SECONDS Single sign-on (OpenID Connect) 900
FLUX_PASSWORD_RESET_TTL_SECONDS Accounts, sign-up and sessions 3600
FLUX_PERSONAL_RUNS AI providers empty; on from ./flux up
FLUX_PORT Instance and network 8081
FLUX_PROJECT Instance and network generated by ./flux up (flux-<directory>-<hash>); release: flux
FLUX_PUBLIC_ORIGIN Instance and network required
FLUX_RUNTIME_CPUS Agent runtime: the owner’s own Claude Code or Codex 1
FLUX_RUNTIME_MANAGER_SECRET Agent runtime: the owner’s own Claude Code or Codex empty; generated by ./flux
FLUX_RUNTIME_MAX_RUNS Agent runtime: the owner’s own Claude Code or Codex empty
FLUX_RUNTIME_MEMORY Agent runtime: the owner’s own Claude Code or Codex 2560m
FLUX_RUNTIME_SECRET_1 Agent runtime: the owner’s own Claude Code or Codex empty; generated by ./flux
FLUX_SEALED_SEARCH_IDLE_MS Encrypted spaces and the keyring 300000
FLUX_SEALED_SEARCH_MAX_BYTES Encrypted spaces and the keyring 268435456 (256 MiB), at most the process bound
FLUX_SEALED_SEARCH_PROCESS_MAX_BYTES Encrypted spaces and the keyring a quarter of the container memory, 64–512 MiB
FLUX_SESSION_IDLE Accounts, sign-up and sessions empty
FLUX_SESSION_MAX_AGE Accounts, sign-up and sessions empty
FLUX_SETUP_TOKEN Accounts, sign-up and sessions empty
FLUX_SMTP_URL Email empty (./flux dev: smtp://mailpit:1025)
FLUX_SSO_MODE Single sign-on (OpenID Connect) sso
FLUX_STREAM_HEARTBEAT_MS Collaboration, link cards and the live stream 25000
FLUX_SWAP_ACKNOWLEDGED Encrypted spaces and the keyring empty
FLUX_TRUSTED_PROXIES Instance and network empty
FLUX_VAPID_PRIVATE_KEY Web Push empty; generated by ./flux
FLUX_VAPID_PUBLIC_KEY Web Push empty
FLUX_VAPID_SUBJECT Web Push empty
FLUX_VIDEO_MAX_MIB Files and video 200
FLUX_WAIT_TIMEOUT Source checkout, launcher and checks 300
FLUX_WEB_READS AI providers on
FLUX_WORKER_MEMORY Memory limits 512m
POSTGRES_DB Database flux
POSTGRES_PASSWORD Database required
POSTGRES_USER Database flux

Where Flux listens and the one address people use. Every deployment sets FLUX_PUBLIC_ORIGIN.

Type name · Default generated by ./flux up (flux-<directory>-<hash>); release: flux · Used by release, ./flux

Compose project name: prefixes the containers and the pgdata and files volumes. ./flux writes flux-<directory>-<hash of the checkout path> on first use. Keep it across upgrades, or the new version starts with empty volumes. Example: flux.

Type port · Default 8081 · Used by api (release, source, ./flux)

Port of the API on the host’s loopback address (127.0.0.1). Point the TLS reverse proxy at it. ./flux up reads it only when it creates docker/.env. Example: 8081.

Type origin URL · Default required · Used by api, proxy, worker (release, source, HTTPS overlay)

The exact origin people open, without a path. It is the only origin accepted for state-changing browser requests, the base of mailed links, OAuth and MCP addresses. https makes cookies Secure; plain http is accepted only for loopback (localhost, 127.0.0.0/8, [::1]), any other http origin stops the API. Example: https://flux.example.org.

Type list of IPs or CIDRs · Default empty · Used by api (release, source)

Comma-separated reverse-proxy addresses whose X-Forwarded-For is believed. Empty trusts none, and the socket peer is the client address. It also chooses the HTTPS front: with an https origin and this empty, ./flux up runs the bundled Caddy (automatic certificates, ports 80 and 443) and the API trusts exactly Caddy’s address; set it only for a proxy of your own, which then owns 80 and 443 (reverse proxy guide). Never 0.0.0.0/0. Example: 172.27.0.1/32.

PostgreSQL runs in the db service with the pgdata volume; it is never published.

Type name · Default flux · Used by api, db, migrate, worker (release, source)

PostgreSQL user, also part of the database URL of every Flux service. Example: flux.

Type secret · Default required · Used by api, db, migrate, worker (release, source)

PostgreSQL password, part of the database URL: use hex (openssl rand -hex 32). ./flux up generates it. Never change it on an existing volume.

Type name · Default flux · Used by api, db, migrate, worker (release, source)

PostgreSQL database name. Example: flux.

Type integer, 100–60000 ms · Default 1500 · Used by api, worker, migrate (override only)

How long a request waits for a database connection (pool of 10 per process) before it fails.

Type secret, ≥ 32 characters · Default required · Used by api (release, source)

Signs session cookies, invite-link tokens and cursors. Changing it signs everyone out and voids pending invite links.

Type secret, 32–256 letters, digits, - or _ · Default empty · Used by api (release, source)

The setup link’s token: the first account, the company’s owner, is made only from <origin>/setup#<token>, and every other account from an invite link or single sign-on. ./flux up writes a random one and prints the link while no company exists. Empty: no first account can be made. Once the company exists it does nothing. See install.

Type integer, 60–86400 s · Default 3600 · Used by api (release, source)

Lifetime of a password reset link, mailed or made in Settings › Company or by ./flux reset-link. Links are single use, stored hashed, and stop when a newer one is made for the same account. Example: 3600.

Type number and unit: 30m, 12h, 7d (5m–365d) · Default empty · Used by api (release, source)

How long a signed-in session lasts without use. Using it renews it. Empty is 7d, or FLUX_SESSION_MAX_AGE if that is shorter. Set, it must not be longer than FLUX_SESSION_MAX_AGE. Example: empty (7d).

Type number and unit: 30m, 12h, 7d (5m–365d) · Default empty · Used by api (release, source)

The longest a session lasts from sign-in, however much it is used; the person then signs in again. Empty is 30d. OWASP ASVS Level 2 asks for 12h with FLUX_SESSION_IDLE=30m. Example: empty (30d).

Type true, false · Default true · Used by api (release, source)

Rate limits: Better Auth’s on sign-in, sign-up and reset (per client address, an IPv6 address as its /64, kept in PostgreSQL so every API process shares it), and the API-wide floor under every other route (in memory: 1,200 requests a minute per session, counted as its own only once the server has accepted that session cookie, or the bearer of /mcp; 600 per address without a credential; 1,200 a minute per address for a cookie or bearer not accepted yet, so a made-up one never has a budget of its own, whatever else the request carries; an IPv6 address counts as its /64; no total per address). The account’s own back-off after repeated wrong passwords is separate and always on; a browser that has signed in to the account is remembered by a signed cookie and is not held by other people’s guesses. Only the test scripts turn the limits off. Example: true.

Optional, one provider. The single sign-on guide walks through it.

Type https URL · Default empty · Used by api (release, source)

Issuer of the OpenID Connect provider. Set it with FLUX_OIDC_CLIENT_ID, or neither. Must be https (plain http only for a loopback issuer). Changing it later makes a new provider: people link again. Example: https://id.example.org/realms/team.

Type string · Default empty · Used by api (release, source)

Client id registered at the provider. Example: flux.

Type absolute host path · Default empty · Used by api (release, source)

File on the host holding the client secret, mounted read-only into the API at /run/secrets/flux_oidc_client_secret (how). Example: /etc/flux/oidc-client-secret.

Type text, ≤ 60 characters · Default empty · Used by api (release, source)

Name on the sign-in button. Empty shows “single sign-on”. Example: Example ID.

Type sso, prepare · Default sso · Used by api (release, source)

prepare keeps password sign-in while existing accounts link their provider identity; sso is the cutover, after which ordinary sign-in is through the provider only. prepare needs a provider. Example: prepare.

Type duration, 1h–30d · Default empty · Used by api (release, source)

How long the provider’s last confirmation of a person keeps their access, in whole hours or days. Empty is 7d. Example: 12h.

Type refresh, off · Default refresh · Used by api (release, source)

refresh checks at the provider that each signed-in person still has an account there; off keeps only logout and the confirmation age. Example: off.

Type integer, 5–86400 s · Default 900 · Used by api (release, source)

How often the standing check runs per live identity. Example: 900.

Optional. Without it password reset reports unavailable; the in-app Inbox and push keep working.

Type SMTP URL · Default empty (./flux dev: smtp://mailpit:1025) · Used by api, worker (release, source, ./flux)

Transport for password reset and notification email. TLS: smtps://…:465 or smtp://…:587?requireTLS=true; certificates are verified. Percent-encode special characters in the user name and password. Needs FLUX_MAIL_FROM. Example: smtps://flux:password@mail.example.org:465.

Type address · Default empty (./flux dev: Flux dev <flux-dev@localhost>) · Used by api, worker (release, source, ./flux)

Sender of every mail. Required when FLUX_SMTP_URL is set. Example: Flux <flux@example.org>.

Optional: both keys or neither; the contact is optional. See phones, tablets and push.

Type base64url P-256 key · Default empty · Used by api, worker (release, source)

Public VAPID key; the API gives it to browsers. Generate the pair once (web-push generate-vapid-keys, see push); ./flux up does it.

Type secret · Default empty; generated by ./flux · Used by worker (release, source)

Private VAPID key; only the worker receives it. Changing the pair makes every device subscribe again.

Type mailto: or https: URL · Default empty · Used by worker (release, source)

Optional contact sent to the push services. Empty, it is FLUX_PUBLIC_ORIGIN when that is https: (Apple’s push service accepts it). Set it only to give a mailto: address at your own domain; a contact Apple cannot reach (localhost, .local, .test) makes iPhone and iPad notifications fail with 403. Example: mailto:ops@example.org.

Section titled “Collaboration, link cards and the live stream”

Type on, off · Default on · Used by api (release, source)

Shared live editing of maps and Wiki pages. off keeps the ordinary saved views and editors; save shared working copies before turning it off. Other values stop the API. Example: off.

Type on, off · Default off · Used by api (release, source)

on lets the server fetch the title and description of links in messages for their cards. Only public http(s) addresses on default ports; never in encrypted spaces, and never for a line an agent that runs on the server wrote. A fetch tells the site this server’s address. Example: on.

Type integer, ≥ 100 ms · Default 25000 · Used by api (release, source)

Ping, session recheck and polling interval of the live WebSocket stream. Keep it below your proxy’s idle timeout. Example: 25000.

Every file is at most 5 MiB, except a video, which has its own limit. See requirements for the disk.

Type integer, 1–1024 MiB · Default 200 · Used by api (release, source)

The largest video one person can send (#1352, C-61). MP4, WebM and MOV files that a browser plays natively play inside Flux and seek without loading in full (the server answers HTTP range requests from disk); they are stored as sent, never converted, and each counts against the files volume. Every other file stays at 5 MiB, and in an encrypted space a video is an ordinary 5 MiB file that downloads. A video is a stream and an upload of this size must get through your reverse proxy: its body limit must be at least this (nginx: client_max_body_size). Other values stop the API. Example: 500.

Calls and screen sharing. FLUX_CALLS=on is all: ./flux layers compose.live.yaml and writes the key, the secret and the public address itself (calls). The values below are its own.

Type on, off · Default off · Used by ./flux

on makes ./flux layer docker/compose.live.yaml (the LiveKit media server) on every command, write FLUX_LIVEKIT_API_KEY and FLUX_LIVEKIT_API_SECRET once, use the origin’s host as FLUX_LIVEKIT_DOMAIN and keep FLUX_LIVEKIT_PUBLIC_IP at the IPv4 address that host resolves to. ./flux up prints the address and the ports to open. off removes the media server at the next ./flux up, and the app offers no calls. Example: on.

Type string · Default required · Used by api, livekit (live-media overlay, TURN overlay)

LiveKit API key, shared by the API and the SFU. Rotate with the secret. ./flux writes it when FLUX_CALLS=on. Example: livekit-key-1.

Type secret · Default required · Used by api, livekit (live-media overlay, TURN overlay)

LiveKit API secret. ./flux writes it when FLUX_CALLS=on.

Type IP address · Default required · Used by livekit (live-media overlay, TURN overlay)

Public media address advertised to browsers in ICE candidates. With FLUX_CALLS=on, ./flux up sets it to the address the origin’s host resolves to. Example: 203.0.113.20.

Type DNS name · Default required · Used by livekit (live-media overlay)

Operator-owned media name used for STUN and TURN/UDP. With FLUX_CALLS=on, ./flux uses the origin’s host and ignores this line. Example: media.example.org.

Type CIDR · Default 0.0.0.0/0 · Used by livekit (live-media overlay, TURN overlay)

The SFU’s media interface when the host has several; the default keeps every IPv4 interface. Example: 203.0.113.20/32.

Type port · Default 7881 · Used by livekit (live-media overlay)

Host port of ICE over TCP.

Type port · Default 7882 · Used by livekit (live-media overlay)

Host port of the ICE UDP mux.

Type port · Default 3478 · Used by livekit (live-media overlay)

Host port of TURN/UDP and STUN.

Type DNS name · Default required · Used by livekit (TURN overlay)

Name dedicated to TURN/TLS; the certificate’s SAN must match. Example: turn.example.org.

Type absolute host path · Default required · Used by livekit (TURN overlay)

Directory with fullchain.pem and privkey.pem for the TURN name, readable by the LiveKit container. Example: /etc/flux/turn-tls.

Type IP address · Default 0.0.0.0 · Used by livekit (TURN overlay)

Address for TURN/TLS on TCP/443. The default conflicts with an HTTPS proxy on the same address: use a dedicated IP. Example: 203.0.113.21.

Type port · Default 443 · Used by livekit (TURN overlay)

Host port of TURN/TLS. Keep 443 for a public deployment.

People connect their own AI in Settings → AI (Connect AI). These switches decide what the instance allows: agents that run on an API key, and agents that search and read the web. A Claude or ChatGPT plan needs the agent runtime below instead. Both Compose files pass the switches to api and worker; agents on API keys also need the key file FLUX_BACKGROUND_KEY_HOST_FILE (see below). AI works right after install (founder decision, 2026-11-13, #1438): while both are empty, ./flux up makes the key file and sets FLUX_PERSONAL_RUNS=on, and people connect AI in the app; off stays off.

Type on, off · Default on · Used by api, worker (release, source)

On by default (founder direction 2026-11-08, C-29): a server agent’s run reads public web pages and searches the web. off turns both off. Reading is Flux’s flux_read_web tool (read-only, GET only), with the guard of link cards: public http(s) addresses on default ports, five redirects at most (a link card keeps three), bounded in time and size. Searching is the provider’s own built-in search on the owner’s key, with no other account (Anthropic’s web_search, OpenAI’s Responses web_search on its cached index; $0.01 a search, counted in the key’s daily budget; no limit on how many an agent makes), and on the owner’s own Claude Code its WebSearch tool, on their Codex its own search on the cached index (#1065); other providers have none. An agent may read any public address, as many as its question needs, but the server refuses one that carries private Flux text the run read: an address is a way to send something to a site (founder direction 2026-11-09, C-30). Each address is written down before the request goes out, and the run lists its searches, the addresses its answer cites and every address the server asked for, those that failed too, under its answer or, when it ends without one, in its end line. A read tells the site this server’s address, a search sends the agent’s query to the provider’s search partner, and the open web can try to instruct an agent: rights, waits and Undo are the defence. Other values stop the API and the worker. Example: off.

Type absolute host path · Default empty; made by ./flux up · Used by api, worker (release, source)

File with 32 random bytes that seals owners’ AI keys for work the worker does on their behalf. Keep it outside the Flux folder and the database backup. Empty leaves agents on API keys unavailable. ./flux mounts it into api and worker at /run/secrets/flux_background_key. While this and FLUX_PERSONAL_RUNS are both empty, ./flux up writes 32 random bytes to ${XDG_STATE_HOME:-~/.local/state}/flux/<project>/background.key and records the path here: the directory is 0700; the file is 0400 when the containers’ user 1000 runs ./flux, given to user 1000 when root does, and otherwise 0444 inside that private directory (another host user, a rootless engine). It never replaces a file, never prints the bytes and leaves a path you set alone. Back it up with docker/.env; it is not in the archive of ./flux backup. Example: /etc/flux/background.key.

Type empty, off, on · Default empty; on from ./flux up · Used by api, worker (release, source)

on lets people’s agents run on their own API key, in pi in the agent runtime (pi in FLUX_AGENT_RUNTIME, which every agent needs). Needs FLUX_BACKGROUND_KEY_HOST_FILE. Empty and off keep them unavailable. ./flux up sets on while this and the key file are empty (#1438) and never changes off, the operator’s switch for a Flux without AI on API keys; a release install sets it itself. Example: off.

Type list of hosts, IPs or CIDRs · Default empty · Used by api, worker (release, source)

Private addresses an OpenAI-compatible endpoint may use, such as a local model server. Empty allows public HTTPS endpoints only; cloud metadata addresses are always refused. Example: ollama,10.0.0.0/8.

Off by default (F-042). Search ranks by BM25 alone; with the overlay compose.embeddings.yaml it also ranks by meaning. See requirements for the memory it needs.

Type on, off · Default off · Used by ./flux

on makes ./flux layer docker/compose.embeddings.yaml: a text-embeddings-inference container running bge-m3 (about 3.2 GiB idle, 3.9 GiB peak; a 2.3 GB model downloaded on its first start). The worker embeds every searchable row of a space whose AI is on, and search fuses the nearest vectors with BM25. Encrypted spaces and spaces with AI off are never embedded; nothing is embedded through a person’s own AI connection. off removes the container at the next ./flux up (the downloaded model stays in the embeddings volume until ./flux clean), and the next worker start deletes every vector. Example: off.

Type Compose memory size · Default 6g · Used by embeddings (embeddings overlay)

Memory of the embeddings container, memory and swap alike. bge-m3 with 2,048 batch tokens idled at 3.15 GiB and peaked at 3.9 GiB (#1242); a limit of 4 GiB killed it while it warmed up. Example: 6g.

Type Compose CPU count · Default 1 · Used by embeddings (embeddings overlay)

CPUs the embeddings container may use. One by default, so that on a 2-core server the other core stays Flux’s while a backfill runs (unbounded it held 150–175 % of two cores for hours, audit of #1270); raise it on a larger server for a faster backfill. Embedding is CPU-bound: about 0.35 messages of ~700 characters a second on 2 cores, fewer with one. Example: 1.

Agent runtime: the owner’s own Claude Code or Codex

Section titled “Agent runtime: the owner’s own Claude Code or Codex”

Off by default. See the agent runtime guide; ./flux ai on writes these for you.

Type empty, any of claude_code, codex, pi, comma-separated · Default empty · Used by api, runtime-1, runtime-egress, runtime-install, worker (release runtime overlay, source, ./flux)

Lets people sign in with their own Claude or ChatGPT subscription and run that CLI, isolated from everyone else; pi runs every API-key agent in pi in the same runtime, with shell and files in a scratch of each run. Empty is off and no runtime service runs. Example: codex,pi.

Type date YYYY-MM-DD · Default empty · Used by api, worker (release runtime overlay, source)

Required with claude_code: the date you agreed to Anthropic’s Commercial Terms with Anthropic. Recorded, not verified. Example: 2026-10-01.

Type integer, 1–365 days · Default empty · Used by api, worker (release runtime overlay, source)

Release a person’s place in the runtime after this many days without a run. Empty is off. Example: 30.

Type secret, ≥ 32 characters · Default empty; generated by ./flux · Used by api, runtime-manager, worker (release runtime overlay, source)

Authenticates the API and worker to the runtime manager. Generated by ./flux.

Type secret · Default empty; generated by ./flux · Used by runtime-1, runtime-manager (release runtime overlay, source)

The runtime’s own secret, shared only with the manager.

Type integer, 1–9999 · Default empty · Used by runtime-1 (release runtime overlay, source)

How many agents run at once. Empty works it out from the runtime’s memory, about 2 on a 4 GB server; the others wait with “Waiting for room on the server” (what each agent needs). Example: 4.

Type Compose memory size · Default 2560m · Used by runtime- (release runtime overlay, source)

Memory of all the agents together. Empty: ./flux takes the server’s memory less 1.25 GiB. Example: 6g.

Type number of CPUs · Default 1 · Used by runtime- (release runtime overlay, source)

CPUs of all the agents together. Empty: ./flux takes all the server’s CPUs but one. Example: 3.

Type integer, 500–600000 ms · Default 10000 · Used by worker (override only)

How often the worker reconciles people’s places with the runtime manager.

See operating encrypted spaces. ./flux up generates the secrets.

Type on, off · Default on · Used by api, worker (release, source)

off disables encrypted spaces: each stays locked and none can be created. Example: off.

Type secret · Default empty; generated by ./flux · Used by api, keyring, worker (release, source)

Authenticates the API and worker to the keyring on its internal network. Empty leaves the keyring idle and every encrypted space locked.

Type secret, ≥ 32 characters · Default empty; generated by ./flux · Used by api, worker (release, source)

Pins every unlock password and key version, so rows planted in the database are refused. Never change it; back it up with the settings file (docker/.env), not with the database.

Type empty, encrypted-swap · Default empty · Used by api, keyring, worker (release, source)

Declares that every swap device is encrypted with a key not stored on disk. Only then may keys be held where swap is on and not limited per container. Example: encrypted-swap.

Type integer, bytes · Default 268435456 (256 MiB), at most the process bound · Used by api (override only)

Largest in-memory search index of one unlocked encrypted space (estimated heap); a larger space answers that search is unavailable.

Type integer, bytes · Default a quarter of the container memory, 64–512 MiB · Used by api (override only)

Bound on all encrypted-space search indexes of one API process.

Type integer, ms · Default 300000 · Used by api (override only)

An index nobody searched for this long may be evicted for another space’s.

Memory and swap are limited to the same value, so these containers cannot write memory to a swap device.

Type Compose memory size · Default 768m · Used by db (release, source)

Memory of db, PostgreSQL (about 70 MiB idle; its page cache counts towards the limit and is given back under pressure). Example: 1g.

Type Compose memory size · Default 1536m · Used by api (release, source)

Memory of api (measured peak 431 MB in the encryption checks). A quarter of it (64 to 512 MiB) bounds the search index of unlocked encrypted spaces. Example: 3g.

Type Compose memory size · Default 512m · Used by worker (release, source)

Memory of worker (measured peak 111 MB). Example: 1g.

Type Compose memory size · Default 128m · Used by keyring (release, source)

Memory of keyring (measured peak 42 MB). Example: 256m.

A read-only GitHub App links pull requests to tasks. Set all six secrets together, or none.

Type string · Default empty · Used by api (release, source)

The App’s OAuth client id.

Type secret · Default empty · Used by api (release, source)

The App’s OAuth client secret. Never give it to agents or models.

Type integer · Default empty · Used by api (release, source)

The App’s numeric id.

Type slug · Default empty · Used by api (release, source)

The App’s URL name (a-z, 0-9, -). Example: acme-team-app.

Type secret, ≥ 32 characters · Default empty · Used by api (release, source)

Verifies webhook deliveries.

Type webhook, poll · Default webhook · Used by api (release, source)

poll when GitHub cannot reach this server: open linked pull requests are read every 2 minutes. Example: poll.

Type 64 hex characters · Default empty · Used by api (release, source)

AES key for stored GitHub credentials. Keep it with your backups to reconnect them after a restore.

Read by ./flux, the hot-reload dev profile or the check scripts, not by the application.

Type secret · Default required (source); release: empty · Used by api, keyring, worker (release, source)

Enables the integration-fixture endpoints used by smoke checks, behind this bearer token. The source Compose file requires it and ./flux up generates it; leave it empty in a release .env.

Type path · Default backups/ in the checkout · Used by ./flux

Where ./flux backup writes archives. Example: /mnt/backup/flux.

Type 1 · Default empty · Used by ./flux

1 builds the image without the Docker build cache (./flux up, ./flux upgrade). Example: 1.

Type seconds · Default 300 · Used by ./flux

How long ./flux waits for services to become healthy. Example: 600.

Type seconds · Default 300 · Used by ./flux

Stops a native ./flux cowork run after this long. Example: 600.

Type port · Default 5173 · Used by web (dev, ./flux)

./flux dev only: port of the Vite dev server; the dev origin is http://127.0.0.1:<port>. Does nothing on a server.

Type true, false · Default false · Used by web (dev)

./flux dev only: watch files by polling, for file systems without change events. Example: true.

Type port · Default 8025 · Used by source, ./flux

./flux dev and checks: port of the local mail catcher’s web page. Does nothing on a server.

Type secret · Default empty; generated by ./flux · Used by ./flux

Password ./flux demo gives the demo owner. Leave empty on a real deployment and never run the demo there.

Type secret · Default empty; generated by ./flux · Used by ./flux

Password ./flux demo gives the second demo account.

The services also read 80 names that Compose, the launcher or the code sets: wiring between services and test switches. Do not set them. They are listed for developers in internal configuration names.

./flux help prints this list; it is copied here from the launcher. The operations overview links each command to its guide.

Flux launcher. Flux runs in Docker; the external cowork action also needs the native Codex CLI.
./flux up Create docker/.env with new secrets if it is missing (never overwrites it),
get the images (a release pulls its own, pinned by digest; a source
checkout builds them), migrate, start and print the URL; while no
company exists, the setup link that makes the owner's account.
./flux demo [--dev] Seed demo data through the public API and print two logins.
Refuses non-loopback (production-looking) origins unless --force.
./flux dev [--build] Hot-reload development in Docker: Vite for the web app, tsx watch
[--follow] for API and worker, PostgreSQL and Mailpit; separate data.
./flux down Stop both stacks; keep data.
./flux logs [--dev] [service] Follow logs (api, worker, web, db, migrate, mailpit).
./flux reset [-y] Delete this checkout's data volumes after confirmation.
./flux clean [-y] reset, plus remove the images this checkout built.
./flux backup [--output DIR] [--keep N]
Stop API and worker, write a timestamped archive (database dump, files
volume, .env, manifest with checksums) to backups/, restart them.
./flux restore <archive> [--migrate] [--revoke-agent-connections] [-y]
Check the archive, confirm, replace this project's data with it, migrate
and run health and schema checks. Refuses another Flux version unless
--migrate. --revoke-agent-connections ends every agent connection and
OAuth token from the backup (they need connecting again).
./flux export <space> [--as EMAIL] [--output FILE]
Write a space's JSON-plus-files bundle to exports/ (as the company
owner by default; the account needs project.manage).
./flux reset-link <email>
Print a one-time password reset link for that account, the owner's too
(works once, for FLUX_PASSWORD_RESET_TTL_SECONDS; a newer link stops it).
./flux identity link <userId> --subject <sub> --reason "<why>" [--old-issuer <URL>] [--allow-sso]
Audited operator recovery by Flux account id; requires the running API.
./flux identity unlink <userId> --reason "<why>"
Audited operator removal of the provider sign-in; refused as the last way in.
./flux upgrade [VERSION | --file flux.tar.gz] [--output DIR] [-y]
A release: download the latest release (or VERSION), check it against
SHA256SUMS and its signature (cosign, or its image), pull its images, back up,
put its files in place, migrate and check health; on failure print the
way back. A source checkout: ./flux upgrade [--pull] builds its own code.
./flux runtime status | release <email> | purge [-y]
Agent runtime (FLUX_AGENT_RUNTIME): show who is in it, release one person's
place (they are signed out and told), or sign out and delete every login.
./flux ai on Ask whether people may sign in with their own ChatGPT and Claude subscriptions
(Enter = yes for Codex; Claude Code needs a typed y to Anthropic's Commercial
Terms), write FLUX_AGENT_RUNTIME into docker/.env and apply it. The first
interactive ./flux up asks the same once. Needs a terminal.
./flux cowork start|resume --client codex --origin URL --connection ID --project ID
Supplied native host action from Connect/Agents. Requires this built checkout,
Docker and Codex 0.160.1 signed in with ChatGPT. Resume uses its exact saved thread
(unverified with a real account). A native run is stopped after
FLUX_COWORK_WATCHDOG_SECONDS (default 300).
./flux help This text.
Commands that start, stop, back up, restore or delete refuse a Compose project that belongs to another
checkout; --force-project overrides that check.
Environment: FLUX_PROJECT (Compose project; default flux-<dir>-<hash of this checkout's path>,
stored in docker/.env on first use; dev uses <project>-dev),
FLUX_PORT (8081, used when creating .env), FLUX_DEV_PORT (5173), FLUX_MAILPIT_PORT (8025),
FLUX_NO_CACHE=1 (a source checkout: build without the Docker cache), FLUX_BACKUP_DIR (default backups/),
FLUX_RELEASE_URL (where ./flux upgrade downloads releases; default the GitHub Releases of Flux).
Operations guide: docs/operations/README.md.