Skip to content

Releases

Flux v0.2.1

Choose a tag to compare

@github-actions github-actions released this 18 Nov 07:47
Immutable release. Only release title and notes can be modified.
f3b8ec5

Flux v0.2.1

Flux v0.2.1 is faster on a small server, fixes and finishes what people met in v0.2, and has AI working right after install.
Every agent now runs in Flux's agent runtime: your own Claude Code or Codex for a plan, and pi for every API key. Calls tell the
space and are easier to join, agents answer as they write and can search everything their owner may read, files and videos open
inside Flux, and search ranks by BM25 in Flux's own database image. It is the first release that installs one way: its flux
launcher pulls the release's images, and ./flux upgrade moves to the next release.

Documentation: https://coldphase.github.io/flux/. Flux is open source under the AGPL-3.0.

Read this first: install and upgrade

  • One install path (#1471, founder decision 5). Download flux.tar.gz,
    SHA256SUMS and its signature, check, unpack, ./flux up (installation). The
    release is a folder; its launcher pulls the release's images by digest, and nothing is built. Later releases install with
    ./flux upgrade, which always checks the download against SHA256SUMS and its signature first (with cosign on the host, or the pinned
    cosign image through Docker), and refuses and changes nothing when it cannot.

  • From v0.2.0: install fresh. v0.2.0 was installed from loose Compose files, so v0.2.1 brings no way to move that installation
    into the release folder. Its data would upgrade: this release was tested to upgrade the data of v0.2.0 (the "Upgrades from"
    line of the release page names what was tested).

  • Flux AI needs a recent Linux host. Every agent runs in the agent runtime, which needs Linux 6.7 or later and
    kernel.yama.ptrace_scope of 1 or higher on the host that runs Docker. The first ./flux up checks. Where the host cannot run it, AI
    stays off and one line says why (owners and admins read it in Settings › AI too). A kernel before 6.7 gets:

    AI agents stay off, as the agent runtime cannot run here: Flux AI needs a newer Linux (kernel 6.7 or later, e.g. Ubuntu 24.04 or Debian 13). See docs/operations/agent-runtime.md.
    

    A host with ptrace_scope 0 gets the fix in the same line: sudo sysctl -w kernel.yama.ptrace_scope=1, and to keep it after a restart
    echo 'kernel.yama.ptrace_scope = 1' | sudo tee /etc/sysctl.d/90-flux.conf. Docker Desktop on a Mac has no Yama, so AI stays off
    there and the rest of Flux runs (agent runtime).

  • HTTPS and calls come with ./flux up. With an https address in FLUX_PUBLIC_ORIGIN it starts its own Caddy, which gets and
    renews the certificate (open ports 80 and 443). FLUX_CALLS=on adds the media server, writes its keys and public address, and
    prints the ports to open. Your own reverse proxy still works: set FLUX_TRUSTED_PROXIES and Caddy is not started.

  • The database image changes. From v0.2.1 the database runs Flux's own image, ghcr.io/coldphase/flux-database: the official
    PostgreSQL 18 on Debian with the pg_search extension (BM25 search) and pgvector. The same PostgreSQL major reads your data
    directory as it is; the release names the new image. The image is about 500 MB larger.
    Migration 0065 builds the search index and recomputes what the old image (musl) computed differently for rare characters, and two
    later ones rebuild it; on 302,000 messages (2026-11-17, 44947da84, a busy 24-core host, so upper bounds) 0065 took 29 s, all
    migrations from 0054 to 0094 40 s, and the whole ./flux upgrade, with its images already built, 81 s and 107 s in two runs,
    while Flux was stopped. A
    database that is not Flux's image (your own PostgreSQL) stops the upgrade before anything changes, with FLUX_DATABASE_IMAGE …
    and what to do (upgrade notes).

  • FLUX_SIGNUP is removed. Accounts now come only from a link (below); ./flux upgrade names the
    old line, which you can delete. New: FLUX_SETUP_TOKEN (the setup link's token; ./flux up writes it, and an instance that
    already has its company never needs it), and, all optional, FLUX_VIDEO_MAX_MIB (200), FLUX_EMBEDDINGS (off) and
    FLUX_EMBEDDINGS_MEMORY (6g).

  • Your reverse proxy must now accept request bodies as large as the largest video you allow (FLUX_VIDEO_MAX_MIB, 200 MiB by
    default; nginx: client_max_body_size 210m) and pass Range requests and 206 Partial Content answers through, or videos fail to
    upload (413) or to seek (reverse proxy).

  • A downgrade is not supported. The way back is the backup you took before the upgrade.

Calls

  • Starting a call tells the space. The people of the space get an Inbox item with Join, the space shows a live dot, the call
    has Invite…, and a call nobody joins ends by itself.
  • One call per space. A call started from a conversation is the space's call, and while it runs every view of the space shows
    Join in its header. The call is one line in the conversation or task it started from: who was in it, how long, and Join while
    it runs.
  • One click on Call shows the call strip at once, saying it is connecting; a second click starts nothing more.
  • Audio settings. The microphone's arrow (and a row in ⋯) opens them: choose the microphone and the speakers, see a level meter
    before you unmute, set the microphone volume and what you hear, test the sound, and set each person's own volume or mute them for
    you only. They are remembered on this device.
  • Screen sharing. When someone shares a screen, the others' stage opens on it once and says who shares and when it stops. A
    screen stopped right after its mode changed no longer stays on the others' screens.
  • The first call invitation offers once to turn notifications on.

AI, agents and search

  • Every agent runs in the agent runtime. ./flux up turns it on where the host can run it, so AI works right after install: add a
    key in Settings › AI. A plan runs in its vendor's own program (Claude Code, Codex); every API key runs in pi (Anthropic, OpenAI,
    OpenRouter, Gemini, your own endpoint), with the same Flux tools. Each run has its own shell and files in a sandbox that lasts one run.
    A key never enters the sandbox: Flux's model gateway holds it and counts every request against the key's daily budget. The worker no
    longer has an agent loop of its own.
  • Only models that call tools are agents. When you add a key or choose a model, Flux sends one small check, a ping tool the model
    must call. A model that does not is refused with "This model can't use tools. Choose another." and the key stays for another model.
  • Prices update themselves. Flux reads model prices every day (Anthropic, OpenAI and Gemini from LiteLLM's public price list,
    OpenRouter from OpenRouter), and the release carries the list of its build day for a server without internet. Connect AI asks for a
    price only when no list has one.
  • Answers appear as they are written, only to the person who asked, with Stop, then Copy and Try again. Agents on an API
    key and your own Claude Code stream their words; Codex shows each message as it finishes.
  • Web search comes from the provider. An agent on an Anthropic or OpenAI key searches the web with that provider's own search,
    inside the key's daily budget, and lists what it searched; Claude Code and Codex use their own. Gemini and OpenRouter keys have no web
    search yet (planned for v0.2.2), and an endpoint of your own has none. Every agent can still open a public web page.
    FLUX_WEB_READS=off turns web search and reading off.
  • Agents work with files. In its sandbox an agent can convert, make a CSV or run a script, and attach what it made to its answer.
    Files, photos and videos can be sent in the chat with your agent: it looks at the photos and reads the files.
  • Ask me first is the one switch of an agent: your OK for changes in Flux (deleting and other people's things always wait). "Only
    read" is gone; an agent that had it is set to Ask me first.
  • Agents find what lies outside the conversation. flux_search ranks messages, Wiki pages, tasks, decisions and maps in every
    space the agent's owner may read, and flux_read_around reads the messages around a hit. Server agents, your own Claude Code and
    Codex get the same two tools. What may be found is checked on every call. For how, what and why, an agent looks in the Wiki first,
    and every answer links the pages, tasks, decisions and messages it used.
  • Search finds what is inside files. The text of a PDF, a Word document (DOCX), Markdown, plain text, CSV and TSV is read once when
    the file is sent, in a sandbox with no network, and found like a message by whoever may read the space; agents find it too and read an
    excerpt. No OCR, and nothing in an encrypted space.
  • Search ranks by BM25 in Flux's database: any of your words, Polish and English forms alike, accents ignored, best match first,
    and always only among what you may read. A word that occurs more often in a message ranks it higher.
  • Search finds every file by its name (a photo, a video, a spreadsheet), and a match with a typo shows only when nothing else
    matches
    : "price list" lists the price list, not a person named "Lis".
  • Optional local embeddings for a larger server: FLUX_EMBEDDINGS=on (or the release's compose.embeddings.yaml) adds one
    container that lets search also rank by meaning, so an English question finds a Polish message. It needs about 3.2 GiB of RAM more,
    downloads a 2.3 GB model on its first start, and embeds about 10,000 messages in 17 minutes of two cores. Off by default; encrypted
    spaces and spaces w...
Read more

Flux v0.2.0

Choose a tag to compare

@github-actions github-actions released this 10 Nov 17:38
Immutable release. Only release title and notes can be modified.
b396187

Flux v0.2.0 candidate

Source: b396187
OCI candidate image: ghcr.io/coldphase/flux@sha256:444cd188490760708d46e8be966ec5ad713414ce79bbf61178935054f580bd1d
Agent-runtime candidate image: ghcr.io/coldphase/flux-agent-runtime@sha256:022e39e1abadb95840670f05d32158e44ea4b171f64d2185aa966c1ed28e68f0
Platforms (both images): linux/amd64
Build: https://github.com/ColdPhase/flux/actions/runs/42860094553
Image scan: job "Scan the images for known vulnerabilities" of that run (Trivy; no HIGH/CRITICAL finding with a fix, except the reviewed exceptions of .github/security-allowlist.json)
Signatures: both digests are signed keylessly by this workflow (cosign, Sigstore, GitHub OIDC) after the scan and the packaged install pass; INSTALL.md shows how to verify them with cosign verify and the provenance with gh attestation verify before you pull
Integrated acceptance: #1181

Install with the attached version-matched compose.yaml, env.example and INSTALL.md; check every file with SHA256SUMS first.
The optional agent runtime is the attached compose.runtime.yaml with runtime.sh (off by default; Claude Code is not included in any image).
Calls and screen sharing: the attached compose.live.yaml, which pins the LiveKit SFU by digest (compose.live.turn.yaml adds TURN/TLS to it); see INSTALL.md.
This draft requires independent packaged install, upgrade and restore review before the version tag and release are published.

Flux v0.1.0

Choose a tag to compare

@github-actions github-actions released this 02 Nov 14:33
Immutable release. Only release title and notes can be modified.
113930e

Flux v0.1.0

This is the first release of Flux.

Flux is an open source workspace where people and AI agents work on the same projects: conversations,
and the tasks, decisions and documents that come out of them. You run it on your own server with
Docker Compose, and an agent sees only the projects and actions you give it.

Documentation: https://coldphase.github.io/flux/. Flux is open source under the AGPL-3.0.

Highlights

  • Conversation that turns into work. Make a message a task, a decision with its reason, or a result.
    Each stays linked to the message it came from. Decisions are accepted by a person who can edit the
    project, never by an agent.
  • Tasks. Criteria, an owner, a due date and a state you change in one tap. A blocked task names the
    person it waits for, and that person gets it in their Inbox.
  • Wiki and Map. A project Wiki with page history and Markdown import, and a Map of connected
    thoughts on an infinite canvas. Several people can edit a page or a map at the same time and see who
    is there. An operator can turn live editing off.
  • Inbox, "Needs you". One queue for the proposed decisions you can accept, the questions asked of
    you, your blocked tasks and your mentions. Home shows what changed since you left and the next step.
  • People and agents. Connect your own Claude Code, Codex or any MCP client to the projects you choose.
    It runs on your computer with your own model account. You grant exactly the actions it may use, and it
    is named as the author of what it does. Co-work Start and Resume prompts, hand-offs, pause and stop are
    built in. Flux was tested with the real Claude Code and Codex.
  • Phone and tablet. The same design on a computer and a phone. Install Flux as a web app (PWA) and
    get Web Push notifications, including on iPhone and iPad. Web Push needs HTTPS and the three
    FLUX_VAPID_* settings (guide).
  • Calls and screen sharing. Join a live session from a project, follow someone and share a screen.
    The media server is optional: add the release's compose.live.yaml (see Install).
  • Encrypted workspaces. When you create a workspace (a "space" in the app) you can encrypt it. Its
    content is encrypted in the database, the files and the search index, and the key lives only in memory.
    After every restart it stays locked until an owner or admin enters their unlock password. There is a
    recovery code, shown once. An encrypted workspace never has AI.
  • Backups. Back up and restore the database and the files together, and export a project as JSON
    plus files.
  • AI is optional. Flux is useful with no AI at all. A workspace owner or admin can turn AI off for the
    whole workspace, and the in-app assistant and the runtime that runs Claude Code or Codex on your server
    are off until the operator switches them on.
  • For operators. One Docker Compose stack, optional single sign-on with your OpenID Connect provider,
    one-time invite links for people without an account, and a configuration reference generated from the code.

Install

You need a Linux server with Docker Engine and the Compose plugin, about 4 GB of memory, and a domain name
for HTTPS. The full guide is
Install from a release; in short:

  1. Download every file of this release into an empty folder and check them with sha256sum -c SHA256SUMS.
  2. Run cp env.example .env && chmod 600 .env, then set POSTGRES_PASSWORD, FLUX_AUTH_SECRET,
    FLUX_PUBLIC_ORIGIN, FLUX_KEYRING_TOKEN and FLUX_KEY_PIN_SECRET (openssl rand -hex 32 for each secret;
    never change the pin secret and keep it with your .env backups).
  3. Run docker compose --env-file .env -f compose.yaml pull, then
    docker compose --env-file .env -f compose.yaml up -d --wait.
  4. Put an HTTPS reverse proxy in front of 127.0.0.1:8081 (tested
    Caddy, nginx and Traefik examples), open your
    address and create the first account.
  5. Optional, for calls and screen sharing: add the FLUX_LIVEKIT_* settings to .env, open UDP/7882,
    TCP/7881 and UDP/3478 to the server, and pass -f compose.live.yaml after -f compose.yaml in every
    command. For networks that allow only HTTPS, compose.live.turn.yaml adds TURN/TLS on TCP/443 of a
    second address. compose.live.yaml pins the LiveKit media server by digest; compose.live.turn.yaml only
    adds to that service and brings no image of its own. The steps are in INSTALL.md,
    section "Calls and screen sharing".

The same steps are in INSTALL.md, attached to this release. To look around first, clone the
repository and run ./flux up, then ./flux demo for sample data
(quick start). Connect your own agent with
Connect your own agent.

Back up your data

This is a 0.1 release, so back up from the start. A backup is the database and the files volume, taken
together while the API and worker are stopped, with your .env kept beside it. Copy it off the machine.
The commands are in INSTALL.md and in
Backup and restore. Check a backup by restoring
it somewhere else before you rely on it.

Platforms

  • Published image: linux/amd64 (x86_64) only. Run it on a Linux server with Docker Engine and Compose.
  • linux/arm64 follows in v0.1.1, after a test on real arm64 hardware. A source checkout (./flux up)
    builds on arm64 and was measured on a Mac, but Linux arm64 servers are not tested yet.
  • Browsers. Phones and tablets are tested in Chromium and WebKit emulation in Docker, not on physical
    devices. Web Push on iPhone and iPad works only from the Home Screen app, on iOS or iPadOS 16.4 or later.
  • Flux does not support Kubernetes or Helm yet. Docker Compose is the only supported install.

Known limits and what comes next

  • No linux/arm64 image yet. It comes in v0.1.1.
  • Calls and screen sharing need the optional compose.live.yaml of this release, public media ports and
    a public IPv4 address that browsers reach directly. Call quality was measured in a Docker simulation of a public host with
    Chromium, Firefox and WebKit, not on real networks or devices. Phone browsers cannot share their screen, and Flux says so.
    See live media.
  • Agents do not wake up by themselves. You start or resume work from your own Claude Code or Codex.
    Flux shows the requests that wait for an agent (#754).
  • GitHub. A project can link tasks to pull requests, tested with simulated GitHub events. Installing a
    real GitHub App and publishing reviews comes later (#755).
  • Sharing a Wiki page with people outside Flux comes later
    (#778).
  • Deleting your account, with a handover of your content, comes later
    (#775).
  • Encrypted workspaces protect a copy of the data or a server taken away switched off. They do not
    protect against someone who controls the running, unlocked server, and Flux is not end-to-end encrypted.
    Names, structure, times, task states and owners stay visible. If every unlock password and the recovery
    code are lost, nobody can recover the workspace. A host with swap needs it off or encrypted. See
    encrypted spaces.
  • Email works through any SMTP server you set in FLUX_SMTP_URL. It was tested against a test mail
    server, so set up SPF, DKIM and DMARC for your own domain.
  • Kubernetes and Helm are later.
  • There is no hosted service. Only the MCP tool contract 1 and the project export format 1 are public
    extension contracts: there is no REST API, webhook or plugin interface yet.

Check your download

SHA256SUMS lists every other file of the release. release.json names the source commit and the exact
image (ghcr.io/coldphase/flux@sha256:…). To check the build provenance of that image, run
gh attestation verify oci://ghcr.io/coldphase/flux@sha256:<digest from release.json> --repo ColdPhase/flux.

Full list of changes

The changelog lists everything in this release.