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

# Flowfield Configuration: Projects, Workers, and Environment

> Configure Flowfield projects, workers, storage paths, ports, and update behavior using CLI flags, per-project config files, and environment variables.

Flowfield configuration spans three layers: environment variables and CLI flags for the service itself, a per-project config file for project identity, and worker integration settings that control how tasks execute in your codebase. Understanding each layer helps you tailor Flowfield to your team's environment without guesswork.

## Service configuration

These settings control the running service. CLI flags take precedence over environment variables.

| Setting | CLI flag | Environment variable | Default |
| - | - | - | - |
| Port | `--port` | `FLOWFIELD_PORT` | `8765` |
| Data directory | `--data-dir` | `FLOWFIELD_DATA_DIR` | `~/.flowfield/` |
| Disable update checks | — | `FLOWFIELD_UPDATE_CHECKS=0` | checks enabled |

Pass `--port` and `--data-dir` before the subcommand so they apply globally:

```sh theme={null}
flowfield --port 8770 --data-dir /my/workspace serve
```

Client commands like `flowfield task list` also respect `--port` (or `FLOWFIELD_PORT`) to reach a service running on a non-default port.

## Project config file

`flowfield project init` creates `.flowfield/config.toml` in your project directory. This file holds the project's identity and lets Flowfield auto-detect the project when you run commands from inside the directory.

The file contains three fields:

| Field | Description |
| - | - |
| `version` | Config format version |
| `project_id` | Unique project identifier used in all API and CLI calls |
| `name` | Human-readable display name |

```toml .flowfield/config.toml theme={null}
version = 1
project_id = "my-app"
name = "My App"
```

The task prefix (for example `APP` in `APP-1`) is derived from the project name at init time. You can override it with `--prefix` during `project init`. **The prefix locks permanently after the first task is created** — choose carefully before you start adding work.

Commit `.flowfield/config.toml` to your repository so that every team member's CLI resolves to the same project automatically.

## Worker and integration settings

You configure how workers execute tasks through `flowfield project integration configure` or through the Workers settings in the browser. The configurable fields are:

* **Target branch** — the branch where approved code is delivered.
* **Dependency setup** — a command to install dependencies before work starts, set with `--setup`.
* **Checks** — one or more verification commands run after implementation. Repeat `--check` for multiple commands.
* **Run command** — a command to start the application for inspection and testing during a worker session.
* **Worker model** — the AI model workers use. Set this explicitly; run `flowfield project workers models` to list available options.
* **Reasoning effort** — the reasoning level for workers. Set explicitly per project.
* **Maximum parallel workers** — 1 or 2 simultaneous workers. Configure this in the browser Workers settings.

```sh theme={null}
flowfield project integration configure \
  --target main \
  --setup "pip install -e ." \
  --check "make test" \
  --check "make lint"
```

Run `flowfield project integration show` to view the current settings for your project.

## Guidance files

`flowfield project guidance install` writes the coordinator instructions into your project. It creates or modifies three items:

| File | Purpose |
| - | - |
| `.agents/skills/flowfield-coordinator/SKILL.md` | Coordinator instructions for your AI agent |
| `AGENTS.md` | Updated with a reference to the coordinator skill |
| `.flowfield/guidance.json` | Tracks which content Flowfield owns versus your local edits |

Commit all three files. `guidance remove` removes owned content that you have not locally edited and preserves any changes you have made.

<Tip>
  Run `flowfield project guidance show` to see the currently installed guidance without modifying anything. Run `flowfield project guidance preview` to see exactly what would be written before you run `install`.
</Tip>


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