Skip to content

Self-hosting Flux

Flux runs on your own server as one Docker Compose project: PostgreSQL, the API, a worker and a small keyring, behind HTTPS (built in, or your own reverse proxy). You install a release and run it with its ./flux launcher. These pages are for the person who runs it, and describe Flux v0.2: one Flux is one company, with spaces, and AI is simple (everything is an agent, and people connect AI once). v0.2 is installed fresh: it does not upgrade a v0.1 installation (why).

Start here
Requirements Host, Docker, memory, disk and network
Installation Download a release, check it, ./flux up: on your computer or a server on your domain
HTTPS and reverse proxies Built-in HTTPS (an https origin and DNS), or your own Caddy, nginx or Traefik
Configuration reference Every setting, generated from the code
Administration in the app The company and its spaces, people and roles, invite links, AI in a space, agents and connections, encrypted spaces
Architecture What runs where, data and secrets
Keep it running
Upgrade, backup and restore, project export Moving forward safely (not from v0.1), and getting data out
Health, monitoring and logs What to watch
Operating encrypted spaces Keyring, restarts, swap, backups
Capacity and scaling Growing the one server
Security hardening Defaults and a checklist
Troubleshooting and FAQ Symptoms, causes and fixes
Optional features
Single sign-on People sign in with your OpenID Connect provider
Phones, tablets and push Installing the app and Web Push
Calls and screen sharing FLUX_CALLS=on: the media server, its address and the ports to open
Agent runtime People connect their own Claude or ChatGPT subscription in Connect AI, and Flux runs the CLI for their agents

Flux is operated with the ./flux launcher in the release folder. Everything runs in Docker: the launcher needs only POSIX sh, Docker with Compose, tar, curl or wget, and sha256sum or shasum. It never installs PostgreSQL or Node.js on the host and never touches another Compose project or a volume that is not this folder’s.

Task Command Guide
Back up database, files and settings ./flux backup [--output DIR] [--keep N] Backup and restore
Restore a backup, here or on a new machine ./flux restore <archive> [--migrate] [--revoke-agent-connections] [-y] Backup and restore
Export one space as open JSON plus files ./flux export <space id or exact name> [--as EMAIL], GET /api/v1/projects/:id/export Project export
Move to a newer release (v0.2 to later; v0.1 is refused) ./flux upgrade [VERSION | --file flux.tar.gz] [-y] Upgrade
Run encrypted spaces: restarts, backups, upgrades, swap and hibernation Nothing to switch on; owners and admins unlock after a restart Encrypted spaces
Let people sign in with your identity provider (OpenID Connect) FLUX_OIDC_* in docker/.env Single sign-on
Serve Flux through HTTPS, including MCP and WebSocket upgrades An https FLUX_PUBLIC_ORIGIN and its DNS (built-in Caddy); or your own proxy’s address in FLUX_TRUSTED_PROXIES HTTPS and reverse proxies
Turn on calls and screen sharing FLUX_CALLS=on in docker/.env, then ./flux up; open the ports it prints Calls and screen sharing
Install Flux on phones and tablets and send push notifications HTTPS at the origin root, FLUX_VAPID_*, outbound HTTPS to the push services Phones, tablets and push
Let people connect their own ChatGPT and Claude subscriptions (off by default) The first interactive ./flux up asks once; later ./flux ai on (or FLUX_AGENT_RUNTIME in docker/.env, then ./flux up); ./flux runtime status | release runtime-<n> | purge Agent runtime

./flux help prints every command; the configuration reference carries the same list.

Every command acts on this folder’s Compose project (FLUX_PROJECT in docker/.env) and uses the ownership check of ./flux up: it refuses a project that another folder created, or one with data but no owner record, unless --force-project is given. Commands that replace data (restore, upgrade, like reset and clean) ask for confirmation; -y answers yes for scripts.

Flux is in early development (project status). These tools make local and small self-hosted instances recoverable. v0.1 had no users, so nothing is converted from it; upgrades between v0.2 versions use ./flux upgrade, which takes a backup first.