working

How-to: working with a running environment

Your environment is up. This page is about living with it day to day — attaching, detaching, inspecting, and parking it without losing work. For full flag detail see the command reference.

flowchart TD
    R[Running environment] -->|ffleet up SLUG| A[Attached to agent session]
    A -->|detach: Ctrl-B D| R
    R -->|ffleet goto SLUG| S[Shell in the worktree]
    S -->|exit| R
    R -->|ffleet ls / status / tail / path| I[Inspect: no state change]
    R -->|ffleet stop SLUG| P[Stopped: container gone, worktree+branch+metadata kept]
    P -->|ffleet up SLUG| A

Loading

Attach & detach

• Attach: ffleet up SLUG drops you into the agent's session (when it's live). That's the same command you used to start it.
• Detach: press tmux's Ctrl-B then D. This leaves the agent running — you're just stepping out. Re-attach later with ffleet up SLUG.
• Peek without risk: ffleet up SLUG --peek attaches only if the agent is already live and never relaunches anything.

goto — a shell in the worktree (not the agent)

ffleet goto SLUG opens a shell in the environment's worktree directory — distinct from attaching to the agent. Use it to inspect files, run a command, or make a manual edit alongside the agent. Leave it with exit.

$ ffleet goto my-feature   # you're now in the worktree
$ git log --oneline -5
$ exit

Related: ffleet path SLUG just prints the worktree path, so you can cd "$(ffleet path my-feature)" from your own shell.

Inspecting

None of these change state:

• ffleet ls — all environments for the project (add --json for scripts).
• ffleet status SLUG — live status: container up?, agent live/exited, blocked state.
• ffleet tail SLUG — the last lines of the agent's transcript (--lines N, default 100).
• ffleet path SLUG — the worktree/working-directory path.

stop — park it without losing work

ffleet stop SLUG removes the container but keeps the worktree, branch, and metadata. It's the safe "get this out of the way" move — reversible, unlike remove.

$ ffleet stop my-feature   # container gone, everything else preserved
$ ffleet up   my-feature   # revive: rebuilt from config, session resumed, no data loss

Because containers run with --rm, there's no lingering "stopped container" — a stop removes it, and up rebuilds a fresh one when you come back. Your work lives in the worktree and the saved session, not the container.

tmux model

Forge Fleet runs the agent inside tmux, kept deliberately simple:

• One tmux session per container.
• A single pane (0) is all you normally need. You can split extra panes yourself, but multiple tmux sessions are not supported (not developed yet).
• Detach is Ctrl-B D; that's the one tmux key you must know.

What can and can't change mid-life

When ffleet up rebuilds a stopped/broken environment, it refreshes config-derived settings from your current ffleet.toml/flags and saves them back. But identity/continuity settings are fixed at create time — to change those you must remove and recreate.

Refreshed on the next up (revive-time-mutable)	Fixed at create (need remove to change)
image	branch
extra_mounts	worktree
extra_hosts	in-place vs worktree mode
docker_env_file	git-mode
credential auth	coding agent
credential dirs (~/.claude / ~/.codex)	the session
agent cmd / extra_args

So: to pick up a new image, an added mount, or a changed env file, just ffleet stop then ffleet up. To change the branch, git-mode, or which agent runs, ffleet remove and start fresh. This is the practical face of config precedence.

Next

Done with the work? Completing / cleanup.