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| I[attached — steer the agent live]
    H -->|--no-attach| 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

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.
--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), and extra_args appended to its launch command. See the config reference.

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

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

Selecting a Claude Code subagent

--subagent NAME — launch a specific Claude Code subagent (e.g. code-reviewer), Claude-only. 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.

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 — a fresh clone instead of a worktree.
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.

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): advanced/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 advanced/container-config.md, advanced/secrets.md, and advanced/docker-dood.md.