HTTPS and reverse proxies
One proxy serves the entire Flux origin: the web app, authentication, OAuth discovery,
/mcp, /api/v1/stream and, when enabled, /media/*. Keep Flux’s API port on loopback.
Set FLUX_PUBLIC_ORIGIN to the exact HTTPS URL people open, including a nonstandard port.
Do not strip paths, authorization or cookies, or replace Host with the upstream address.
The proxy is built in: an https origin is all. A proxy of
your own is the same single setting with its address added (your own proxy).
For your own proxy, the Caddy example below is the most complete; nginx and Traefik follow, and any proxy that passes WebSocket upgrades
and request bodies of at least 5 MiB works the same way.
Built-in HTTPS
Section titled “Built-in HTTPS”Founder decision 3 of #1471 (2026-11-13). Point the
DNS name at the server, then set the origin in docker/.env and apply it:
FLUX_PUBLIC_ORIGIN=https://flux.example.orgFLUX_TRUSTED_PROXIES=./flux upWith an https origin and FLUX_TRUSTED_PROXIES empty, ./flux adds
docker/compose.https.yaml to every command: Caddy 2.11.9, pinned by
digest, as the proxy service. It listens on port 80 and on the origin’s port (443 unless the origin
names another; TCP, and UDP for HTTP/3), obtains and renews the certificate for the origin’s host
itself (ACME, Let’s Encrypt or ZeroSSL), redirects plain http to https, and passes everything to
the API over a network that only the two of them join. The API’s own port stays on 127.0.0.1.
The owner’s only steps are the DNS A record and opening 80/tcp and 443/tcp to the server; ACME needs
both to reach it. No AAAA record unless Docker’s IPv6 networking is enabled on the server: on Docker’s
default IPv4-only networks an IPv6 visitor reaches Caddy through Docker’s userland proxy, from the
network’s gateway address, so Flux would see every IPv6 visitor as one client (one shared sign-in limit,
the gateway in session lists).
The API trusts exactly Caddy’s address. Each time it starts, it looks up the proxy service and runs
with FLUX_TRUSTED_PROXIES=<Caddy's address>/32; ./flux up prints the value. docker/.env keeps
FLUX_TRUSTED_PROXIES empty: that empty line is what says “the bundled proxy”. Caddy replaces any
X-Forwarded-For a client sends with the address it sees, so sign-in limits and session lists see real
client addresses, and no other process can speak from Caddy’s address.
- Certificates persist in the
proxy-datavolume (certificates, the ACME account key and Caddy’s own CA);proxy-configholds Caddy’s saved configuration../flux down,upandupgradekeep them;./flux cleanandresetremove them../flux backupdoes not include them: on a new server Caddy gets new certificates by itself once the DNS points there. - Upgrades keep the same volumes; a new Caddy digest arrives with the Flux version that pins it, and Compose restarts the API with Caddy so the trusted address follows it.
- Private network or home lab: a name Caddy treats as internal (
localhost,*.localhost,*.local,*.internal,*.home.arpa, or an IP address) gets a certificate from Caddy’s own CA instead of ACME, with no other change. Every device then has to trust that CA’s root once:docker cp <project>-proxy-1:/data/caddy/pki/authorities/local/root.crt flux-root.crt, and install it as a trusted root on each computer, phone and tablet (phones need it for the installed app and push). - Switching back: an
http(loopback) origin, or aFLUX_TRUSTED_PROXIESvalue, makes the next./flux upremove theproxycontainer; its volumes stay until./flux clean.
Tested on 2026-11-13 with an isolated ./flux up of this checkout on a Linux Docker Engine 29.4.2 host,
origin https://127.0.0.1:23443 (an IP address, so Caddy’s own CA; no public ACME was attempted from
this host): see the evidence below.
Your own proxy instead
Section titled “Your own proxy instead”Already running nginx, Traefik or another Caddy on 80/443? Give its address in the same file, before or
together with the https origin, and ./flux bundles nothing:
FLUX_PUBLIC_ORIGIN=https://flux.example.orgFLUX_TRUSTED_PROXIES=172.27.0.1/32The address is where your proxy’s connections to Flux come from. For a proxy on the same host that
connects to 127.0.0.1:<FLUX_PORT>, it is the gateway of Flux’s Compose network:
docker network inspect "$(sed -n 's/^FLUX_PROJECT=//p' docker/.env)_default" --format '{{range .IPAM.Config}}{{.Gateway}}{{end}}'Write it with /32 (/128 for IPv6), run ./flux up, then check it
with one sign-in. The rest of this page is your proxy’s configuration: whole origin, WebSocket upgrades,
Host kept, X-Forwarded-For replaced.
Local HTTPS example
Section titled “Local HTTPS example”This is a proxy of your own; without one, HTTPS is built in. Edit only these settings in
docker/.env (the gateway address is the one of your own proxy; measure it below):
FLUX_PORT=19373FLUX_PUBLIC_ORIGIN=https://localhost:19443FLUX_TRUSTED_PROXIES=172.27.0.1/32Apply the settings with ./flux up. Keep the other settings and secrets from that installation.
Save this as Caddyfile in a separate proxy directory:
{ admin off auto_https disable_redirects skip_install_trust}
localhost:19443 { bind 127.0.0.1 tls internal reverse_proxy 127.0.0.1:19373}Validate and start the pinned image. :z makes the configuration readable on a Docker host
with SELinux; the two named volumes preserve Caddy’s certificates and configuration.
Choose names unused by another installation.
docker run --rm --network none \ -v "$PWD/Caddyfile:/etc/caddy/Caddyfile:ro,z" \ caddy@sha256:4e2425f6009577e7c651010f16679c28f7d12df3e7b1914f941a7a3370746b3c \ caddy validate --config /etc/caddy/Caddyfile --adapter caddyfiledocker run -d --name flux-proxy --restart unless-stopped --network host \ -v "$PWD/Caddyfile:/etc/caddy/Caddyfile:ro,z" \ -v flux-proxy-data:/data -v flux-proxy-config:/config \ caddy@sha256:4e2425f6009577e7c651010f16679c28f7d12df3e7b1914f941a7a3370746b3cdocker cp flux-proxy:/data/caddy/pki/authorities/local/root.crt ./flux-local-root.crtcurl --cacert ./flux-local-root.crt -fsS https://localhost:19443/api/v1/healthOnly the public CA certificate is exported. Trust it in the browser used for this local
installation, then open https://localhost:19443 and create an account. This local CA does
not obtain a public ACME certificate.
Trust only the measured proxy peer
Section titled “Trust only the measured proxy peer”An empty FLUX_TRUSTED_PROXIES with an https origin starts the built-in proxy, so set the
gateway address first and use the query below to confirm it. Create an identifiable account through Caddy,
for example proxy-probe@example.org, and inspect only its session address. For the
default database name and user, the command is (in the Flux folder):
docker compose --env-file docker/release.env --env-file docker/.env -p YOUR_PROJECT -f docker/compose.yaml exec -T db \ psql -U flux -d flux -c "SELECT s.ip_address FROM auth_sessions s JOIN auth_users u ON u.id = s.user_id WHERE u.email = 'proxy-probe@example.org' ORDER BY s.created_at DESC LIMIT 1;"Replace YOUR_PROJECT with the FLUX_PROJECT from docker/.env (a developer’s source checkout uses
--env-file docker/.env -f docker/compose.source.yaml).
Use your configured database user/name if changed. Do not select tokens or password hashes.
With trust empty, this address is the API’s socket peer, including Docker’s NAT if present.
Set FLUX_TRUSTED_PROXIES to that address with /32 for IPv4 or /128 for IPv6, and
apply the settings again. In our isolated project the observed peer was 172.27.0.1, so
the tested setting was 172.27.0.1/32. This is an observation, not a reusable default.
A quick cross-check is the gateway of the project’s network:
docker network inspect <FLUX_PROJECT>_default --format '{{range .IPAM.Config}}{{.Gateway}}{{end}}'.
The address can change when a Compose network is recreated; measure it again. A bridge
gateway identifies a network hop, not uniquely the Caddy process. Do not trust every
private network or 0.0.0.0/0; keep the API loopback publication in place.
Sign out and sign in through Caddy, then repeat the query. In this loopback example the
new session must contain the browser’s client address 127.0.0.1. Caddy’s direct-edge default discards client-supplied forwarding values. Flux
resolves the client address through its configured peers and strips arbitrary forwarding
headers before authentication. No Caddy trusted_proxies option is needed for this direct
edge; putting another proxy ahead of Caddy requires a separate, narrow trust configuration.
For an https FLUX_PUBLIC_ORIGIN the API itself sends Strict-Transport-Security: max-age=31536000, and the proxy passes it on, so
the proxy needs no header or add_header line for it. Add includeSubDomains or preload at the proxy only when every subdomain
of your name serves https for good: a browser keeps the rule for the whole period. Do not set a second, different value at the
proxy (nginx’s add_header adds a second header rather than replacing the first; use proxy_hide_header Strict-Transport-Security;
first if you do).
Public hostname and streaming
Section titled “Public hostname and streaming”For a public hostname, keep the same whole-origin proxy and matching upstream port. Change
FLUX_PUBLIC_ORIGIN to https://flux.example.org, apply Flux’s settings, and replace the
local Caddyfile with:
flux.example.org { reverse_proxy 127.0.0.1:19373}Use your hostname and actual FLUX_PORT. Its A/AAAA records must reach this host; inbound
80 and 443 must reach Caddy. Preserve writable /data and /config volumes, and restart
the proxy to load its new configuration. Caddy’s automatic HTTPS obtains and renews the
public certificate.
The same reverse_proxy supports the WebSocket upgrade at /api/v1/stream; no separate
WebSocket location or path rewrite is required.
When the optional live-media overlay is enabled, the
whole-origin proxy also covers /media/rtc, /media/rtc/v1 and the other /media/*
signaling paths. Actual media RTP/ICE/TURN reachability follows that guide separately;
an HTTPS proxy does not establish working audio/video transport. FLUX_CALLS=on layers the overlay (calls).
Check discovery and the unauthenticated MCP challenge at your exact public origin:
curl -i https://flux.example.org/.well-known/oauth-protected-resource/mcpcurl -i -X POST https://flux.example.org/mcpExpect metadata 200 with resource=https://flux.example.org/mcp, then 401 whose
WWW-Authenticate points to https://flux.example.org/.well-known/oauth-protected-resource/mcp.
For the local example use https://localhost:19443 and --cacert ./flux-local-root.crt.
Tested on 2026-10-07 with Caddy 2.11.7 on the host network of a Linux Docker Engine host, using
the local example above: health, sign-up, a WebSocket 101 on /api/v1/stream, the MCP discovery and
challenge, and a forged X-Forwarded-For replaced by the real client address. Public DNS and ACME
were not exercised (record;
references: reverse proxy,
automatic HTTPS).
The same whole-origin rule with nginx. Put this in a file under /etc/nginx/conf.d/ (the map
block must be at http level, which conf.d files are): pass every path, keep Host, forward WebSocket upgrades,
replace the client’s X-Forwarded-For with the address nginx sees, and let request bodies through
(nginx accepts 1 MiB by default; Flux takes files up to 5 MiB and a video up to FLUX_VIDEO_MAX_MIB, 200 MiB by default).
map $http_upgrade $connection_upgrade { default upgrade; '' close;}
server { listen 443 ssl; http2 on; server_name flux.example.org;
ssl_certificate /etc/letsencrypt/live/flux.example.org/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/flux.example.org/privkey.pem;
# Files up to 5 MiB, and videos up to FLUX_VIDEO_MAX_MIB (200 MiB by default), are accepted by Flux; nginx's default is 1 MiB. # Keep this at least as large as FLUX_VIDEO_MAX_MIB, or a video fails with 413 from nginx. client_max_body_size 210m;
location / { proxy_pass http://127.0.0.1:8081; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; # Live streams stay open; Flux pings every 25 s (FLUX_STREAM_HEARTBEAT_MS). proxy_read_timeout 1h; proxy_send_timeout 1h; proxy_buffering off; }}
server { listen 80; server_name flux.example.org; return 301 https://$host$request_uri;}nginx does not obtain certificates itself; use your ACME client (for example certbot) for the files
named above. Use your FLUX_PORT in proxy_pass. Then trust only the measured proxy
peer as for Caddy, with the database query from that section.
Tested on 2026-10-31 with nginx:1.29-alpine (nginx 1.29.8, digest
sha256:5616878291a2eed594aee8db4dade5878cf7edcb475e59193904b198d9b830de) on the host network of a
Linux Docker Engine 29.4.2 host, in front of a source ./flux up on a loopback port, with a
self-signed certificate for localhost and FLUX_PUBLIC_ORIGIN=https://localhost:<port>: the
server block above with that port, address and certificate (the port-80 redirect was not part of
the run). Through the proxy: health answered ok; sign-up and GET /api/v1/me answered 200; a
WebSocket upgrade of /api/v1/stream with the session cookie answered 101; the MCP metadata named
https://localhost:<port>/mcp and POST /mcp answered 401 with the matching WWW-Authenticate;
a 6 MB upload reached Flux (its own 400 answer, not nginx’s 413). With FLUX_TRUSTED_PROXIES empty
the session recorded the Docker bridge gateway 192.168.160.1; with that address as
192.168.160.1/32, a sign-in carrying a forged X-Forwarded-For: 203.0.113.199 recorded the real
client 127.0.0.1. Public DNS, ACME and the redirect block were not exercised.
Traefik
Section titled “Traefik”Traefik’s file provider, with a static configuration (traefik.yml) and a dynamic one
(flux.yml). Traefik forwards WebSocket upgrades and sets X-Forwarded-For itself, and by default
it does not believe a client’s own forwarding headers.
entryPoints: web: address: ":80" http: redirections: entryPoint: { to: websecure, scheme: https } websecure: address: ":443" transport: respondingTimeouts: readTimeout: 0s # no limit on reading a slow uploadcertificatesResolvers: letsencrypt: acme: email: ops@example.org storage: /letsencrypt/acme.json httpChallenge: { entryPoint: web }providers: file: filename: /etc/traefik/flux.ymlhttp: routers: flux: rule: Host(`flux.example.org`) entryPoints: [websecure] service: flux tls: certResolver: letsencrypt services: flux: loadBalancer: servers: - url: http://127.0.0.1:8081Run Traefik on the host network (or otherwise able to reach 127.0.0.1:<FLUX_PORT>), keep
/letsencrypt on a volume, and trust only the measured proxy peer.
If Flux and Traefik share a Compose network you could point the service at the API container
instead, but Flux’s Compose files publish the API on loopback only, and this guide keeps it so.
Tested on 2026-10-31 with traefik:v3.5 (Traefik 3.5.6, digest
sha256:16acb89c6db341182970d6fdafece31303b0a380a8ed7aa51682e225229bf1d2), same host and Flux as the
nginx run, with a websecure entry point on the test port, the same readTimeout, the file
provider and a static certificate under tls.certificates instead of the ACME resolver. The same
probes passed: health, sign-up, /api/v1/me, WebSocket 101 on /api/v1/stream, MCP metadata and
401 challenge, and a 6 MB upload reaching Flux. A sign-in with a forged
X-Forwarded-For: 203.0.113.199 recorded 127.0.0.1. The ACME resolver, the port-80 redirect and
public DNS were not exercised.
Other proxies
Section titled “Other proxies”Any proxy works when it serves the whole origin from one host name, passes WebSocket upgrades on any
path (/api/v1/stream, /api/v1/typing, /api/v1/agent-runtime/console, and /media/* with
live media), does not buffer or time
out long-lived connections sooner than a few minutes, accepts request bodies of at least the largest video you allow (5 MiB for everything else), passes Range requests and 206 Partial Content answers through (a video seeks with them), and
does not rewrite paths, Host, cookies or Authorization. A CDN or second proxy in front changes
which address Flux sees: trust only the hop that connects to Flux, and make sure that hop replaces
any client-supplied X-Forwarded-For.
Flux limits how fast the API is called (1,200 requests a minute per session once the server has accepted it, 600 a minute per address
without one and 1,200 a minute per address for a session cookie or bearer it has not accepted yet; an IPv6 address counts as its /64). The address is the client’s only when FLUX_TRUSTED_PROXIES names your proxy; without it every request comes from the
proxy, so everyone shares the per-address budgets and a busy company can meet the limit. Set it as described above.
Headers
Section titled “Headers”Flux sends its own Content-Security-Policy on the app’s pages and its service worker. The policy lists the SHA-256 of the
page’s inline scripts and the page’s own origin for sockets (FLUX_PUBLIC_ORIGIN), so a proxy must pass it through unchanged: do not
add, replace or strip Content-Security-Policy, X-Frame-Options or Content-Security-Policy-Report-Only for Flux’s
host. A second policy added at the proxy is combined with Flux’s by the browser (every policy must allow a request) and
can only break the app. Serve Flux on the origin FLUX_PUBLIC_ORIGIN names: the policy is written for it.
Built-in HTTPS evidence
Section titled “Built-in HTTPS evidence”Observed on 2026-11-13 (#1471) with an isolated copy of the checkout on a Linux Docker Engine 29.4.2 host: a first ./flux up
(loopback origin), then FLUX_PUBLIC_ORIGIN=https://127.0.0.1:23443 and FLUX_CALLS=on in its docker/.env and ./flux up again.
An IP address gets a certificate from Caddy’s own CA, so no public ACME was attempted; public DNS and ACME stay unexercised here.
./flux upprintedThe API trusts only Caddy's address: FLUX_TRUSTED_PROXIES=172.19.64.2/32, anddocker inspectgave theproxycontainer exactly172.19.64.2on theedgenetwork; the API’s own process environment had the same value.- With Caddy’s root certificate:
/api/v1/healthansweredokonhttps://127.0.0.1:23443;http://127.0.0.1/xanswered308tohttps://127.0.0.1:23443/x; the MCP metadata namedhttps://127.0.0.1:23443/mcpandPOST /mcpanswered401(HTTP/2) with the matchingWWW-Authenticate; a WebSocket upgrade of/api/v1/streamwith the session cookie answered101. - A sign-up and a sign-in through Caddy with a forged
X-Forwarded-For: 203.0.113.199recorded172.19.64.1, the address Caddy saw (Docker’s port forwarding on the same host), neither the forged one nor Caddy’s own; a sign-in straight to the loopback API port with the same forged header recorded the API’s socket peer172.19.32.1. - With the origin back on
http://127.0.0.1:23081andFLUX_CALLS=off, the next./flux upremoved theproxyandlivekitcontainers and theiredgeandlivekit-*networks, and kept theproxy-dataandproxy-configvolumes. - The first run found a defect this page’s design fixes: the image’s
caddybinary has a file capability, socap_drop: [ALL]alone makes it fail to start (operation not permitted); the overlay keepsNET_BIND_SERVICE, and Caddy’s health check now makesupfail instead of reporting Flux running behind a proxy that is not.