Skip to content

starting

Jump to bottom
github-actions[bot] edited this page Aug 12, 2026 · 3 revisions

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]
Loading

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.

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.

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).
  • 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. You have a choice:

  • Inside the checkout (e.g. .forge-fleet/worktrees) — everything stays next to the repo.
  • A separate folder under $HOME — keeps the setup fully local to your machine, with nothing to commit into a shared project (the default "home mode" philosophy). Override per-run with --worktree-root.

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.

Docker-related start options (brief)

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.

Next

Once it's running: working with a running environment.

Clone this wiki locally