How-to: starting an environment

Everything happens through ffleet up SLUG. This page covers the choices you make when creating an environment. For the exhaustive flag list see the command reference; for the equivalent ffleet.toml keys see the config reference.

flowchart TD
    A[ffleet up SLUG] --> B{git-mode?}
    B -->|auto / worktree / clone| C[new isolated worktree + branch]
    B -->|off, or --here| D[in-place: your current directory, no worktree]
    C --> E{seed a prompt?}
    D --> E
    E -->|-p / --prompt| F[fresh agent session, seeded]
    E -->|--prompt-file FILE| F
    E -->|no prompt| G[fresh agent session, empty]
    F --> H{attach?}
    G --> H
    H -->|default, or --attach| I[attached — steer the agent live]
    H -->|--no-attach, -y, or attach = false| J[running in the background]
    H -->|--peek| K[attach only if already live; never launch]

Seeding the work: prompts

-p / --prompt "…" — the initial message for a fresh session. On an existing/revived session the prompt is instead sent to the live agent.
--prompt-file PATH — read the prompt from a file (handy for long or multi-line instructions) instead of --prompt.

$ ffleet up my-feature -p "Refactor the auth module and add tests"
$ ffleet up my-feature --prompt-file ./task.md

Attach behaviour

Codex opens its interactive terminal interface even when you supply a prompt or use a template. After answering, it stays open for your reply. --no-attach leaves that same interface running in the background; it does not switch Codex to a text-only batch run.

Default: after starting, you're attached to the agent's tmux session.
--no-attach — start (or revive) but stay in your shell; good for background runs. Check in later with status / tail, or attach with a plain ffleet up.
--attach — attach explicitly. Only needed to override a project that defaults to not attaching (below), or a -y run; passing both flags is an error.
-y / --yes — unattended mode never attaches unless you pass --attach (or use --peek, which always attaches when the agent is live), so a scripted or CI run can't hang on an interactive session. It overrides attach = true and ATTACH=true too.
attach = false in ffleet.toml — make not attaching this project's default, for a repo you normally drive in the background. Either flag still wins per run, as does an ATTACH env var. See the config reference.
--peek — a strict, side-effect-free peek: attach only if the agent is already live, and never relaunch it. Use it to look without risk of starting anything.
--wait-timeout N — seconds to wait for the container/agent to become ready (default 300). Raise it for heavy first-time image pulls or slow setup.

In-place mode: `--here` (works without git)

--here starts (or revives) an agent over your current directory — no worktree, no branch. This is the "not only programming / works without git" case: point an agent at any folder.

$ cd ~/notes
$ ffleet up braindump --here -p "Organise these notes into a coherent outline"

Because there's no worktree isolation, the agent works directly in that directory. It's still a registered environment (shows in ls, revivable with up), and remove cleans up its metadata without touching your directory. It's the no-worktree, no-git case — closely related to running with --git-mode off.

Setting git_mode = "off" in ffleet.toml makes this the default for the project: ffleet up SLUG then runs in-place over the project root (from any subdirectory) with no worktree and no git repo required — you don't need to pass --here each time. This is the way to run Forge Fleet on a plain, non-git folder.

Choosing the coding assistant

--coding-agent claude|codex — which assistant to launch (default claude). The project default comes from default in ffleet.toml.
Per-agent config lives in the [claude] and [codex] tables of ffleet.toml: the credential/config directory (dir), the credential auth source, the binary (cmd), the default model and reasoning effort, and your own extra_args. See controlling the coding assistant.

$ ffleet up my-feature --coding-agent codex -p "…"

The chosen agent is fixed at create time — switching agents means a new environment.

Selecting a subagent

--subagent NAME — launch a specific custom agent (e.g. code-reviewer). Works with or without -t/--template: it no longer requires a template just to pick a subagent. If the template also configures a subagent, --subagent wins and a warning is printed when the two differ. See templates for the template-config equivalent.

$ ffleet up my-feature --coding-agent claude --subagent code-reviewer -p "…"

Like --coding-agent, the subagent is fixed at create time (reviving an existing environment always ignores --subagent).

Support differs by coding-agent:

Claude — deterministic. Translated straight into Claude Code's own --agent <name> flag, so the CLI itself enforces the agent exists and is used.
Codex — best-effort. The Codex CLI has no equivalent flag, so ffleet looks up NAME in ~/.codex/agents/*.toml (personal) or .codex/agents/*.toml in the repo (project) — matched on the file's name field, not the filename — and, once found, weaves a delegation instruction into the launch prompt (or sends it into the pane on an interactive launch with no prompt) asking Codex to use it. Codex decides for itself whether to follow that instruction — nothing in ffleet forces it, so treat it as a strong hint, not a guarantee.

Git modes

--git-mode auto|worktree|clone|off (default auto) decides how git is set up inside the container:

worktree — a git worktree on a new branch off the source repo (the isolated default; auto resolves to this in a normal repo).
clone — reserved for a fresh clone instead of a worktree; not implemented yet, so an environment configured with it fails to start.
off — no git integration; the agent works directly in the mounted directory (the same "works without git" case as --here). Set as git_mode = "off" in ffleet.toml, plain ffleet up SLUG runs in-place over the project root — no worktree, no git repo, and no --here needed.
auto — pick the sensible mode for the repo.

Full walkthrough, plus commit identity and denying the agent remote writes: git options.

Basing a worktree on an existing branch

--from BRANCH — base a first-time worktree on an existing branch instead of a new empty one (ignored once the environment exists).
--git-local-main — base the worktree on your local main and keep completion local-only (no push/PR). Pairs with git_local_main in config.

$ ffleet up hotfix --from release-2.3 -p "Cherry-pick the logging fix"

New to git worktrees? They let multiple branches be checked out at once in separate directories — see Git's own git worktree documentation.

Where worktrees are created

worktree_root controls where per-environment worktrees live. ffleet init proposes a default that follows the config location you chose:

Home mode (default) — a folder under ~/.forge-fleet/{project-id}/worktrees, keeping the setup fully local to your machine with nothing to commit into a shared project.
Local mode — .forge-fleet/worktrees inside the checkout, so config and state stay next to the repo (that directory is already added to .gitignore).

worktree_root is set once by ffleet init (it accepts --worktree-root to seed the value) and thereafter read straight from ffleet.toml. To change it, edit the config — there is no per-run override on the env commands.

Templates (brief)

-t / --template <id> seeds a fresh environment from a [templates.<id>] table in ffleet.toml — typically fetching an issue from your PM tool and rendering a prompt from it. In template mode the SLUG argument is the template ref (e.g. an issue number):

$ ffleet up -t task 123

Full guide, including PM-tool integration (GitHub Issues, Linear): templates.md.

Several flags shape the container: --image, --extra-mounts, --extra-hosts, --docker-env-file, --docker-host-bind, --uv-cache-dir, plus the credential dirs --claude-dir / --codex-dir / --claude-auth. They're summarized in the command reference; the full explanations are in container-config.md, secrets.md, and docker-dood.md.