Skip to content

How-to: completing & cleanup

When a piece of work is merged or abandoned, tear the environment down. When you're done with a whole project — or want to uninstall — clean up the ~/.forge-fleet registry. For full flags see the command reference.

flowchart TD
    E[Environment done] -->|ffleet remove SLUG| R[Worktree deleted; ffleet-created branch deleted]
    R --> D{More environments in this project?}
    D -->|yes| E
    D -->|no| P[Project-level cleanup]
    P -->|ffleet project ls| L[See all known projects]
    P -->|ffleet project prune| PR[Drop stale entries + their ~/.forge-fleet home dirs]
    P -->|ffleet project rm ID| RM[Delete one project's ~/.forge-fleet/ID dir + registry entry]

Get your work out first

Forge Fleet manages environments, not your git workflow: it never pushes your branch or opens a PR for you. Landing the work is your job — or the agent's, from inside the container — and you must do it before remove, which deletes the branch Forge Fleet created.

Find the branch. A worktree environment lives on a branch named <project>-<slug> (the same name as its container). Confirm it with status:

$ ffleet status my-feature
...
branch: my-project-my-feature
worktree: ~/.forge-fleet/my-project/worktrees/my-feature

Push / open a PR — either ask the agent ("commit, push, and open a PR"), or do it yourself from the worktree:

$ ffleet goto my-feature
$ git push -u origin my-project-my-feature
$ gh pr create
$ exit

Push credentials are not mounted by default. The container knows your origin URL but has no push auth — no ~/.ssh, no gh/git token, no host git config. Provide credentials yourself, e.g. mount your SSH key:

extra_mounts = ["~/.ssh:/home/buddy/.ssh:ro"]

or supply a token via docker_env_file. Your commit identity (name/email) is forwarded automatically from [git] or your host git config — only push credentials need this. Prefer to stay fully local? git_local_main = true bases the branch on your local main so you can merge locally with no push at all.

Forge Fleet sandboxes your setup — it doesn't replace it. The real leverage is still your own prompts, your skills/subagents, and templates that wire an issue straight into a seeded session. Forge Fleet's job is to run all of that inside an isolated, disposable container — so you can let an agent work autonomously without it touching your host. It's the safe sandbox around your workflow, not a substitute for it.

Remove one environment

ffleet remove SLUG tears the environment down: it stops the container and deletes the worktree. If Forge Fleet created the branch, that branch is deleted too; a branch you brought in with --from is left alone.

$ ffleet remove my-feature
$ ffleet remove my-feature -y   # skip the confirmation prompt

remove surfaces unpushed/uncommitted work before deleting so you don't lose it by surprise. This is irreversible — if you only want the container gone, use ffleet stop instead.

The project registry (~/.forge-fleet)

Forge Fleet tracks the projects it knows about in ~/.forge-fleet/registry.json, with each project's home data under ~/.forge-fleet/{id}/. The ffleet project commands manage that registry — useful for multi-project cleanup and uninstalling.

  • ffleet project ls — list all known projects (add --json). Start here.
$ ffleet project ls
  • ffleet project prune — remove stale registry entries and delete their ~/.forge-fleet home directories. Good housekeeping after you've deleted repos. Prompts first; -y to skip.
$ ffleet project prune
  • ffleet project rm PROJECT_ID — permanently delete one project's ~/.forge-fleet/{id} directory and its registry entry. Prompts first; -y to skip.
$ ffleet project rm my-project

Uninstalling Forge Fleet

To leave no trace:

  1. ffleet remove every remaining environment (or ffleet ls per project to find them).
  2. ffleet project prune, or ffleet project rm ID for each project, to clear ~/.forge-fleet.
  3. Delete the ffleet binary from your PATH.

Removing environments deletes worktrees and ffleet-created branches — double-check nothing is unpushed first.