Skip to main content
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. Pass --port and --data-dir before the subcommand so they apply globally:
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:
.flowfield/config.toml
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.
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: Commit all three files. guidance remove removes owned content that you have not locally edited and preserves any changes you have made.
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.