config precedence

Advanced: config precedence

When a setting could come from more than one place, Forge Fleet resolves it in a fixed order. Understanding this explains two things that surprise people: why a flag sometimes "wins" over your config, and why some settings only take effect after a remove.

The order (highest wins)

1. CLI flag — e.g. --image, --git-mode, -p. Explicit on the command line; applies to this run.
2. Environment variable / dotenv — e.g. IMAGE_NAME, GIT_MODE, or an entry in .env.forge-fleet / .forge-fleet/.env. See the env-var mapping.
3. ffleet.toml — the project's configured value.
4. Built-in default — what ffleet uses when none of the above is set (e.g. image = forge-fleet:latest, git_mode = auto, wait-timeout = 300).

So a flag overrides an env var / dotenv entry, which overrides the config file, which overrides the default. Nothing exotic — the twist is when the resolved value gets applied.

Why some settings only apply after remove

An environment's settings split into two groups, and ffleet up treats them differently on a revive/rebuild (this is stated in ffleet up --help):

• Config-derived (refreshed every up) — image, extra_mounts, extra_hosts, docker_env_file, credential auth, credential dirs (~/.claude / ~/.codex), agent cmd / extra_args. These are re-read from your current config/flags each time and saved back. Change one, then ffleet stop SLUG + ffleet up SLUG to apply it.
• Identity/continuity (fixed at create) — branch, worktree, in-place vs worktree mode, git-mode, which coding agent, and the session. These are pinned when the environment is first created and do not change on revive, because changing them would mean a different environment. To change one you must ffleet remove SLUG and recreate.

flowchart TD
    F[CLI flag] --> R{resolve}
    E[env var / dotenv] --> R
    T[ffleet.toml] --> R
    D[built-in default] --> R
    R --> V[effective value for this run]
    V --> K{which kind of setting?}
    K -->|config-derived| RE[applied now; refreshed on every up]
    K -->|identity/continuity| FX[fixed at create; needs remove to change]

Loading

Practical rules of thumb

• Passed a flag and it did what you expected → good, flags are top of the order.
• Changed image/mounts/env-file and want it live → stop then up.
• Need a different branch, git-mode, or agent → remove and start fresh; there's no in-place way to change identity.
• Not sure which bucket a setting is in → check the table in how-to/working.md.