Skip to content

Quick start

Prerequisites: Docker Engine 25 or newer (or Docker Desktop) with Compose, curl and tar. No host Node.js or PostgreSQL (requirements).

Terminal window
curl -fLO https://github.com/ColdPhase/flux/releases/latest/download/flux.tar.gz
curl -fLO https://github.com/ColdPhase/flux/releases/latest/download/SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS # flux.tar.gz: OK (macOS: shasum -a 256 --ignore-missing -c SHA256SUMS)
tar -xzf flux.tar.gz && cd flux
./flux up # creates docker/.env with random secrets once, pulls the release's images, migrates, starts, prints the URL
./flux demo # optional: a sample company with a space, conversation, Map and Wiki page; prints two logins

Then open the URL that ./flux up prints, http://127.0.0.1:8081/ by default. If port 8081 is taken, start the first time with another free port, for example FLUX_PORT=8090 ./flux up. The first ./flux up downloads the release’s images, pinned by digest; nothing is built on your machine. On a server, also check the release’s signature first (installation). To connect your own MCP client, such as Claude Code or Codex, follow Connect your own agent.

AI works right after install: people connect their own API key or their Claude or ChatGPT subscription in Settings › AI. ./flux up makes the key file that seals API keys, in ~/.local/state/flux/<project>/, outside the backups (back it up), sets FLUX_PERSONAL_RUNS=on and starts the agent runtime, in which every agent runs. That needs a Linux host with kernel 6.7 or later and ptrace_scope of 1 or higher (requirements); a host that cannot run it gets one line saying why, and AI stays off. In a terminal the first ./flux up also asks once whether people may sign in with their own subscriptions (Enter means yes, for Codex; Claude Code needs a typed y to Anthropic’s Commercial Terms). Without a terminal nothing is asked and Codex is on, Claude Code off. ./flux ai on asks later and only adds (operator guide). ./flux up never overwrites an existing docker/.env.

Other commands: ./flux down, ./flux logs, ./flux upgrade (to the next release), ./flux reset (deletes data after confirmation), ./flux clean and ./flux help. To work on Flux itself, clone this repository: a source checkout builds Flux with the same launcher (development).