Use

Workspace and changes

Your project is copied into the sandbox, not mounted. The agent works on the copy. When it is done, the copy comes back to a staging folder, you read the diff, and nothing touches your repo until you apply it.

What goes in

fenzi run copies the folder you run it from to /sandbox/<folder>, and the agent starts there. It refuses your home folder, /, and any folder that holds your home folder.

• Files matched by .gitignore are left out. So are build output and dependencies, if your .gitignore lists them.
• .git is left out. The sandbox has no history, no remotes, and no Git credentials.
• If the copy includes files that look like secrets, such as .env or a private key, run names them before it creates anything. In a terminal it asks whether to copy them, and stops unless you say yes. --allow-secrets skips the question. Add them to .gitignore if the agent should not see them. The full list of names is under run.

Before the copy, Fenzi records a fingerprint of every file it sends. That is what the diff and the conflict check compare against later.

To start with an empty folder instead, use fenzi run --no-upload claude. Fenzi's own flags go before the agent's name.

What comes back

When the agent exits, or when you run fenzi stop, the project folder is copied out of the sandbox to ~/.cache/fenzi/staging/<sandbox>. run then shows the changes and asks what to do with them. The sandbox stays running, so fenzi connect can resume the agent; run --rm deletes it instead. Deleting the sandbox does not touch the staged copy. stop deletes it after asking. If the copy fails, the sandbox is kept, so nothing is lost.

Only the project folder comes back. The agent's own settings live in its home folder, /sandbox, outside the project, so they stay out of the diff.

Read the diff

■ 3 files changed from the agent  not applied yet

  deleted src/legacy-router.ts  −31
  new     src/routes.test.ts    +18
  edited  src/routes.ts         +2 −1
                                +20 −32 in total

── src/routes.ts  edited  +2 −1
    12   import { Router } from "./router";
    13 - import { legacy } from "./legacy-router";
    13 + import { health } from "./health";
    14 + import { users } from "./users";
    15
    16   export const routes = new Router();

Nothing in ~/src/web has changed. fenzi apply copies them in.

Added, edited, and deleted files are all listed with their line counts, then each file's changed lines with three lines around them. Removed lines are marked -, added lines +. Long output opens in your pager. Binary files and very large rewrites show their counts only. --stat prints the list without the lines. The comparison is built in; git is not needed.

Apply

Shows the list, then asks: apply them, show the changes, or keep them for later. Applying writes the changes into your repo and clears the staging folder. Keeping them changes nothing, and they stay staged until you apply. --yes applies without asking. It refuses if any of those files changed on your side since the agent started, and lists them, so you never lose your own edits to the agent's. Resolve them and run it again.

• Symbolic links and special files are not applied. A link could point outside the project.
• Nothing is written outside the project folder, whatever path the staged copy names.
• Each file is written in full and moved into place, so an interrupted apply does not leave half a file.

Then commit as you normally would. The agent does not commit or push. The changes arrive as files in your working tree, and your Git history is yours.

A change the agent made to fenzi.yaml is not flagged. The diff shows it like any other file, and apply writes it like any other file, so read it there. On Free, the next run in that folder uses the file you applied, and the policy check does not catch a host the agent added, because on Free the boundary comes from the same file. On a machine signed in to a team, the project file is not used. See The check before start.

Several runs on one project

Each sandbox has its own staging folder. diff and apply pick the latest sandbox for the folder you are in; pass --sandbox <name> for an earlier one. fenzi ps --all lists finished sandboxes whose changes you can still read.

On Team

The workspace never reaches our cloud. The control plane receives decision records and requests, not files. The model vendor still receives what the agent sends it: the files it read, command output, and your instructions. See What our cloud receives.

A team policy cannot forbid --allow-secrets today. The policy file has no setting for it, and the flag works the same on a machine signed in to a team. The warning that names the files is still printed, and the files are copied only into the sandbox on that developer's machine.