config

Config reference (ffleet.toml)

Every ffleet.toml setting. This file is a per-project, personal dev-tool preference — not team config. ffleet init writes it by default under ~/.forge-fleet/{project-id}/ffleet.toml ("home mode"), so nothing needs to be committed into the repo it configures. In-repo ("local mode") is supported as an explicit opt-in.

Most CLI flags mirror a key here; where they overlap the flag wins for that run (see config precedence). The canonical, fully-commented template is ffleet.toml.example at the repo root.

Global keys

Key	Type	Default	Meaning
project_name	string	— (required)	Logical project name; used to name containers and worktrees.
source_dir	string	—	Absolute path to the source repo. Required in home mode; in local mode it's derived from where this file lives (set it only if the file isn't colocated with the repo).
worktree_root	string	— (required)	Where per-environment worktrees are created (absolute, or relative to the repo root). Inside the checkout (e.g. .forge-fleet/worktrees) or a separate folder under $HOME.
image	string	ghcr.io/grzegorz-aniol/forge-fleet-python:latest	Docker image the agent container runs. Use ghcr.io/grzegorz-aniol/forge-fleet-go:latest for the Go-dev variant.
git_mode	string	auto	Git integration: auto | off | worktree | clone. See git modes.
git_local_main	bool	false	Base the worktree on the local main branch and keep completion local-only (no push/PR).
docker_host_bind	bool	false	Let the agent inside the container drive the host Docker daemon (binds the host docker socket; agent-started containers become siblings). See DooD.
uv_cache_dir	string	~/.cache/uv	Shared uv cache mounted into the container for faster installs.
extra_mounts	list	—	Extra bind mounts as source:target[:ro|:rw]. Target must be an absolute container path; a relative source resolves against the repo root; ~ expands to the host home. An optional :ro/:rw suffix sets the mode (default read-write).
extra_hosts	list	— (may be omitted)	Host-to-address mappings passed to docker run --add-host, each host:address. host-gateway resolves to the host itself.
docker_env_file	string	—	Additional env file passed to docker run --env-file (runtime secrets/keys). A relative path resolves against this config file's own directory.
copy_files	list	—	Gitignored files to snapshot from the main repo into each new worktree (globs allowed), so e.g. .env appears at the same relative path inside. One-time copy at creation, not a live link.
default	string	—	Which coding-agent ffleet up runs when none is named on the CLI. Must be one of the [section] names below (e.g. claude, codex).
pm	string	github	Issue tracker for -t templates: github (via gh CLI) | linear (needs LINEAR_API_KEY) | none (don't fetch; raw ref exposed as {id}). On any fetch failure ffleet warns and continues as pm=none.

[git] — identity injected into the container

Both keys must be set together; otherwise identity resolves from host git config.

Key	Type	Meaning
user_name	string	Git author/committer name inside the container.
user_email	string	Git author/committer email inside the container.

[claude] / [codex] — per-coding-agent config

Key	Type	Default	Meaning
dir	string	~/.claude / ~/.codex	Host directory mounted as the agent's config/credentials, so it's authenticated inside the container.
auth	string	auto	(Claude) Credential source ffleet injects. See the table below.
cmd	string	the section name	Override the binary invoked in the container (e.g. claude).
extra_args	list	—	Flags appended to the agent's launch command, after ffleet's own flags (e.g. ["--agent", "myagent"]).

[claude].auth values

Value	Behaviour
auto	Try keychain, then token, then api-key, then credentials-file; first available wins (default).
keychain	macOS only; pin the Keychain-derived credential (fails fast if the lookup fails).
token	Pin CLAUDE_CODE_OAUTH_TOKEN (from claude setup-token).
api-key	Pin ANTHROPIC_API_KEY (API billing, not subscription).
credentials-file	Pin the ~/.claude mount's .credentials.json (Linux only).
external	Skip the auth preflight entirely — you provide credentials another way (e.g. docker_env_file).

See container configuration for how these mounts and credentials fit together.

[templates.<id>] — prompt templates

Looked up by ffleet up -t <id> <ref>: ffleet fetches issue <ref> from the configured pm source, derives the slug from the issue title, and renders prompt_template with the issue's fields.

Key	Type	Meaning
prompt_template	string	Template rendered with {number}, {title}, {body}, {url}, {id} (raw ref), plus any extra key=value tokens passed on the CLI.
subagent	string	Optional subagent for envs seeded from this template. Translated to the agent's own subagent flag (Claude only: --agent <name>; using it with another agent errors).

Full walkthrough: advanced/templates.md.

Environment variables and dotenv

Most ffleet.toml keys have an environment-variable equivalent, and Forge Fleet also loads a dotenv file from the current working directory if present. An env var (or dotenv entry) overrides the matching ffleet.toml key; a CLI flag overrides both (see config precedence).

Dotenv discovery order in the current working directory (only the first existing file is loaded):

1. .env.forge-fleet
2. .forge-fleet/.env

Env var mapping:

Env var	Maps to
PROJECT_NAME	--project-name
SLUG	slug positional argument
SOURCE_DIR	--source-dir
WORKTREE_ROOT	--worktree-root
IMAGE_NAME	--image
CODING_AGENT	--coding-agent (on up; set only when first creating an env). The legacy AGENT / --agent names still work, each with a one-time deprecation notice.
CLAUDE_DIR	--claude-dir
CLAUDE_AUTH	--claude-auth (auto, keychain, token, api-key, credentials-file, external)
CODEX_DIR	--codex-dir
UV_CACHE_DIR	--uv-cache-dir
EXTRA_MOUNTS	--extra-mounts (source:target,source:target)
EXTRA_HOSTS	--extra-hosts (host:address,host:address; each becomes a docker run --add-host, e.g. host.docker.internal:host-gateway)
DOCKER_ENV_FILE	--docker-env-file
GIT_MODE	--git-mode (auto, off, worktree, clone)
GIT_LOCAL_MAIN	local-branch mode when first creating an env (true/false)
DOCKER_HOST_BIND	--docker-host-bind (true/false)
FORGE_FLEET_GIT_USER_NAME	explicit git identity name override
FORGE_FLEET_GIT_USER_EMAIL	explicit git identity email override
LINEAR_API_KEY	Linear personal API key, read directly when pm = "linear"; no CLI flag equivalent

Example .env.forge-fleet:

PROJECT_NAME=creator-ai
SOURCE_DIR=/path/to/repo
WORKTREE_ROOT=/path/to/worktrees
IMAGE_NAME=forge-fleet:latest
CODING_AGENT=claude
CLAUDE_DIR=~/.claude
CODEX_DIR=~/.codex
UV_CACHE_DIR=~/.cache/uv
EXTRA_MOUNTS=~/.agents:/home/buddy/.agents,~/.ssh:/home/buddy/.ssh:ro
DOCKER_ENV_FILE=/path/to/docker.env
GIT_MODE=auto
DOCKER_HOST_BIND=false
FORGE_FLEET_GIT_USER_NAME=Jane Developer
FORGE_FLEET_GIT_USER_EMAIL=jane@example.com
# Only needed when pm = "linear":
LINEAR_API_KEY=lin_api_xxxxxxxx

EXTRA_MOUNTS format rules:

• comma-separated entries: <source>:<target>[:ro|:rw]
• source supports ~ expansion
• relative source is resolved from the current working directory
• target must be an absolute container path (start with /)
• an optional trailing :ro or :rw sets the mount mode (default is read-write); any other trailing segment is rejected
• entries are bind-mounted as -v <source>:<target> (read-write) or -v <source>:<target>:ro (read-only)
• if an extra mount uses the same target as an existing mount, the later extra mount can shadow the earlier one

Config discovery order

For a given directory, Forge Fleet locates the ffleet.toml to use in this order:

1. an explicit config path (FFLEET_CONFIG env var)
2. an explicit project config dir (FFLEET_PROJECT_DIR env var)
3. the ~/.forge-fleet/registry.json lookup by the directory's project id
4. legacy in-repo search: ffleet.toml, then .forge-fleet/ffleet.toml

The project id is derived from git structure — the main checkout's git rev-parse --git-common-dir plus its origin remote, or a path hash when there is no remote — never from the current directory's name. That's why every worktree of a project resolves to the same config.

Related

• Full command/flag list: command reference.
• Why some keys only apply after remove: config precedence.