Skip to main content
Flowfield runs locally on macOS and Linux and requires Python 3.12 or newer. The flowfield-core package bundles the CLI, the local service, and the browser UI — no separate frontend install is needed. For managed work (running AI workers on your project), you also need Git and an installed, signed-in Codex CLI.
Flowfield runs on macOS and Linux only. Windows is not supported. The service binds to loopback (127.0.0.1) and never exposes itself to your network. Managed work additionally requires Git and an installed, signed-in Codex CLI.
uv is a fast Python package and tool manager that keeps Flowfield in its own isolated environment and exposes the flowfield command on your PATH. It is the recommended installation method.
1

Install uv

Follow the uv installation instructions for your platform. On macOS and Linux the quickest path is:
2

Install Flowfield

Install flowfield-core as a uv tool, pinned to Python 3.12:
uv manages a dedicated environment for Flowfield and makes the flowfield command available globally.
If the flowfield command is not found after installation, run uv tool update-shell to add the uv tools directory to your PATH, then open a new terminal.

​
Install with pip

If you prefer not to use uv, you can install Flowfield into a dedicated Python virtual environment using pip. Use Python 3.12 or newer.
1

Create a virtual environment

2

Install Flowfield

3

Run Flowfield

You can run Flowfield directly using the full path:
Or activate the environment first to use the shorter command:

​
Start and stop

Start the local service by running:
Open localhost:8765 in your browser. The service runs in the foreground — keep the terminal open. Press Ctrl-C to stop the service. Custom port. To run on a different port, pass --port:
Any CLI command that communicates with the service must use the same port:
Environment variables. You can set defaults via environment variables instead of flags:

​
Upgrade

Stop the service before upgrading. Press Ctrl-C in the terminal running flowfield serve before running an upgrade command. Upgrading while the service is running may leave stored data in an inconsistent state.
Flowfield notifies you when a new version is available — check the Notifications panel in the browser UI. To upgrade with uv:
To upgrade in a pip environment:
On restart, Flowfield automatically applies any supported upgrades to stored data after taking a verified snapshot. A failed upgrade rolls back and stops startup with recovery instructions — your data is not modified. The worker queue starts paused after every restart; review your board and pending work before re-enabling the queue.

​
Verify installation

Confirm Flowfield is installed and check the version:
For a machine-readable output: