Skip to content

1. Basic flow

The shortest route from nothing to a coding agent working in its own isolated environment. Four commands. Details come later — this page is deliberately thin.

Prerequisite: Docker running and ffleet installed (see install).

1. Configure the project — once

From inside the git repository you want to work on:

$ ffleet init

init writes an ffleet.toml for this project (by default under ~/.forge-fleet/…, so nothing needs to be committed into the repo). It runs a short wizard for the few settings worth choosing up front — coding agent, base image, git mode, and whether sandboxes get host Docker access — each pre-selected at its default, so you can press enter straight through. In a real hurry, -y accepts every default with no prompts. You only do this once per project: init is create-only and won't overwrite an existing config, so change settings later by editing the ffleet.toml it points you at (see the config reference).

2. Start an environment

$ ffleet up

Bare up creates one isolated environment — a git worktree on a fresh branch, a container, and a coding-agent session — and then attaches you to that session so you can watch and steer it. Once attached you're at a normal terminal: you type your first message to the agent yourself.

With no slug, up is interactive (it needs a terminal). If you already have environments, it lists them and asks whether to reattach to one or create a new one. If you have none, it tells you so — "No environments found; creating a new one" — and prompts for a slug to name it. It never auto-creates one silently. Say the slug you pick here is my-feature — that's the environment the rest of this walkthrough follows.

Passing -p is a variation on that same start: instead of typing your first message once attached, -p "…" / --prompt (or --prompt-file <path>) pre-types it for you, so the agent begins working as soon as the session comes up:

$ ffleet up my-feature -p "Add a --verbose flag to the CLI and cover it with tests"

You can also skip the prompts by passing things up front:

  • Give the slug on the command line: ffleet up my-feature.
  • --no-attach leaves the environment running in the background instead of attaching.
  • -y / --yes skips only the image-freshness pull prompt (it warns about a stale image but never pulls) — it is not a general "do everything unattended" switch.

Detach from an attached session any time with tmux's Ctrl-B then D — the agent keeps running. For the full set of flags, see how-to/starting.md.

3. Check on it

$ ffleet status my-feature   # is the container up? is the agent live or done?
$ ffleet tail my-feature     # last lines of the agent's transcript
$ ffleet ls                  # all environments for this project

Re-attach whenever you like by running ffleet up my-feature again — same command, no flags needed. (That's the core idea: up is state-driven — see concepts.)

4. Tear it down

When the work is merged or abandoned:

$ ffleet remove my-feature

This stops the container and deletes the worktree — and the branch too, if Forge Fleet created it. It asks first; add -y to skip the prompt.

That's the loop

init once, then up → check → remove per piece of work. From here: