> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowfield.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Install Flowfield on macOS and Linux with uv or pip

> Install Flowfield using uv or pip on macOS or Linux with Python 3.12+. Includes start, stop, and upgrade instructions for the local service.

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.

<Note>
  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.
</Note>

## Install with uv (recommended)

`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.

<Steps>
  <Step title="Install uv">
    Follow the [uv installation instructions](https://docs.astral.sh/uv/getting-started/installation/) for your platform. On macOS and Linux the quickest path is:

    ```sh theme={null}
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```
  </Step>

  <Step title="Install Flowfield">
    Install `flowfield-core` as a uv tool, pinned to Python 3.12:

    ```sh theme={null}
    uv tool install --python 3.12 flowfield-core
    ```

    uv manages a dedicated environment for Flowfield and makes the `flowfield` command available globally.

    <Note>
      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.
    </Note>
  </Step>
</Steps>

## 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.

<Steps>
  <Step title="Create a virtual environment">
    ```sh theme={null}
    python3 -m venv ~/.local/share/flowfield-venv
    ```
  </Step>

  <Step title="Install Flowfield">
    ```sh theme={null}
    ~/.local/share/flowfield-venv/bin/python -m pip install flowfield-core
    ```
  </Step>

  <Step title="Run Flowfield">
    You can run Flowfield directly using the full path:

    ```sh theme={null}
    ~/.local/share/flowfield-venv/bin/flowfield serve
    ```

    Or activate the environment first to use the shorter command:

    ```sh theme={null}
    . ~/.local/share/flowfield-venv/bin/activate
    flowfield serve
    ```
  </Step>
</Steps>

## Start and stop

Start the local service by running:

```sh theme={null}
flowfield serve
```

Open [localhost:8765](http://127.0.0.1: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`:

```sh theme={null}
flowfield serve --port 8770
```

Any CLI command that communicates with the service must use the same port:

```sh theme={null}
flowfield --port 8770 project list
```

**Environment variables.** You can set defaults via environment variables instead of flags:

| Variable | Purpose | Default |
| - | - | - |
| `FLOWFIELD_PORT` | Port the service binds to | `8765` |
| `FLOWFIELD_DATA_DIR` | Directory for stored data | `~/.flowfield/` |
| `FLOWFIELD_UPDATE_CHECKS` | Set to `0` to disable automatic update checks | enabled |

## Upgrade

<Warning>
  **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.
</Warning>

Flowfield notifies you when a new version is available — check the Notifications panel in the browser UI. To upgrade with uv:

```sh theme={null}
uv tool upgrade flowfield-core
flowfield serve
```

To upgrade in a pip environment:

```sh theme={null}
~/.local/share/flowfield-venv/bin/python -m pip install --upgrade flowfield-core
~/.local/share/flowfield-venv/bin/flowfield serve
```

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:

```sh theme={null}
flowfield --version
```

For a machine-readable output:

```sh theme={null}
flowfield version --json
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.