← Amber 2.0

Workspace Isolation

1 Apr 2026 · Tristan Wright

The Problem

When multiple agents run against the same project, they step on each other. One agent edits a file while another is reading it. Uncommitted changes bleed between runs. Concurrent work becomes a race condition.

Workspace isolation solves this by giving each agent run its own copy of the project.

Three Modes

Every project has a workspace isolation setting in its settings panel. It controls what happens when an auto-mode run starts.

Auto (default)

The smart default. If the project is a git repo, Amber creates an isolated git worktree — a full, independent checkout of the repo on a temporary branch. If the project isn’t a git repo, it falls back to running directly in the project directory.

This is the right choice for most projects. Git repos get full isolation; non-git projects still work, just without concurrency safety.

Isolated

Forces worktree isolation with no fallback. If the project isn’t a git repo, the run fails rather than falling back to in-place execution.

Use this when concurrency safety is non-negotiable — you’d rather a run fail than risk two agents editing the same files.

In Place

No isolation at all. The agent reads and writes directly in the project directory. Concurrent runs can conflict with each other and with your own uncommitted changes.

Use this when you specifically need the agent to see your current working state — uncommitted changes, local config tweaks, files you’ve been editing by hand.

How It Works Under the Hood

When a run starts in Auto or Isolated mode, the system:

  1. Creates a branch named auto-mode/{projectId}-{timestamp}-{random} — unique per run, no collisions
  2. Adds a git worktree at /storage/users/{userId}/projects/{projectId}/.agent-loop/workspaces/{loopId}
  3. Symlinks node_modules from the main repo so the agent doesn’t need to reinstall dependencies
  4. The agent works entirely inside the worktree — it can’t see or modify the main checkout

When the run finishes:

  1. Any uncommitted changes in the worktree are staged and committed automatically
  2. The auto-mode branch is merged back into the project’s main branch using --no-ff
  3. If the merge has conflicts, it aborts and preserves the branch for manual resolution
  4. The worktree and branch are cleaned up (deleted) after a successful merge
Technical Detail — Merge Safety

The merge step runs git merge --abort if it encounters conflicts, so the main branch is never left in a dirty state. The auto-mode branch is preserved, so you can inspect it and resolve manually:

git log auto-mode/{projectId}-...
git merge auto-mode/{projectId}-...

The .gitignore is also patched automatically before the final commit to exclude node_modules/, .next/, dist/, and .turbo/ — preventing accidental staging of build artefacts if the symlink was replaced during the run.

What This Means in Practice

  • Multiple agents can work on the same project simultaneously without conflicts
  • Each agent sees a clean snapshot of the repo at the point its run started
  • Changes are merged back in order — if two agents edit the same file, the second merge may conflict, but neither run is lost
  • The setting is per-project, so you can use Isolated for critical repos and In Place for scratch projects

Limitations

  • Pipeline and agent team runs do not yet support workspace isolation — they always run in place
  • Worktree isolation requires the project to be a git repository
  • Very large repos may take longer to set up worktrees (the initial git worktree add can be slow)
  • The symlinked node_modules approach assumes dependencies don’t change between runs — if an agent runs npm install, the symlink may be replaced with a real directory (handled gracefully during merge)