01 basic flow

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). Accept the defaults with -y if you're in a hurry. You only do this once per project.

2. Start an environment

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

This creates an isolated environment named by its slug (my-feature): a git worktree on a fresh branch, a container, and a coding-agent session seeded with your prompt. By default it then attaches you to the agent's session so you can watch and steer it.

• -p / --prompt seeds the session with an initial message.

• Prefer to let it run in the background? Add --no-attach:

  $ ffleet up my-feature --no-attach -p "…"

Detach from an attached session any time with tmux's Ctrl-B then D — the agent keeps running.

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:

• Understand the mental model → concepts.
• Do more when starting → how-to/starting.md.
• Keep a container out of the way without losing work → ffleet stop (see how-to/working.md).