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 |
Commands
Section titled “Commands”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.