AI Agent File Isolation: Developer Best Practices

Conclusion: how to choose isolation tiers

There is no single scheme for every case. One agent on a laptop: path allowlists plus .gitignore discipline often suffice. Multiple agents on one repo: git worktree plus separate tmux sessions are mandatory. Customer data or production keys: dedicated Cloud Mac nodes or container sandboxes are the baseline.

In August 2026, kvmboot support tickets about agents committing .env or two CLIs editing package.json were 90% wrong isolation tier, not "too smart models." Most teams should stop at allowlists + worktree before adding containers or separate nodes.

Asymmetric takeaway: file isolation governs where writes go; memory isolation governs what gets remembered — both required, neither substitutes the other.

1. Why AI agents need file isolation (Why)

Agents differ from autocomplete because they execute autonomously: read trees, edit many files, run shell, reach Git and DBs via MCP. Without boundaries, typical failures include:

• Cross-contamination: Agent A on feature/auth while Agent B formats on main — package-lock.json gets silently overwritten.
• Secret leakage: Agent reads ~/.aws/credentials or .env to "fix config"; snippets appear in context or logs without allowlists.
• Over-privileged writes: MCP Filesystem rooted at /Users — one bad tools/call can delete home.
• No rollback path: direct working-tree edits without worktree/branch — no "discard entire workspace" escape hatch.

Same root cause as Cloud Mac dual-agent architecture: cloud host solves uptime; file isolation solves write sovereignty. References: Claude Code IAM, Cursor Agent security.

2. Six file isolation schemes (What)

2.1 Path allowlists (tool tier, fastest)

Declare allowedDirectories in Claude Code settings.json or project .claude/settings.json. Cursor uses Rules plus workspace root. Zero infra; relies on config discipline; does not stop reads of mounted secrets in-process.

2.2 Separate HOME and working directories (process tier)

HOME=/opt/agents/claude vs HOME=/opt/agents/codex — configs, caches, local MCP state stay separate. Pair with tmux for dual CLI on one machine.

2.3 git worktree (repo-tier hard isolation)

git worktree creates multiple checkouts — agents bind to different paths/branches. Cross-write is filesystem-impossible unless misconfigured. See remote Mac M4 worktree guide.

2.4 Container sandbox (execution tier)

Docker/Podman bind mounts — read-only source, writable /tmp/agent-out. Good for CI agents and untrusted scripts. On Apple Silicon watch image arch and Docker security; native macOS agents often prefer worktree + user separation.

2.5 MCP tool scope (service tier)

Each MCP Server exposes minimal tools and roots — Git Server limited to repo root; Filesystem Server never mounts $HOME. When multiple clients share one Server, paths must align with each client's worktree cwd.

2.6 Dedicated Cloud Mac node (host tier)

One Cloud Mac mini per agent or tenant — SSH keys, Keychain, clones physically separated. Highest cost, simplest acceptance — zero cross-writes at infrastructure layer.

3. Five-dimension comparison

4. Three-layer stacked topology

kvmboot default topology (24GB Cloud Mac, dual agents):

L1 Tool: per-CLI allowedDirectories; deny ~/.ssh, .env
L2 Repo: git worktree add ../wt-claude feature/x ; git worktree add ../wt-codex feature/y
L3 Session: tmux claude → wt-claude ; tmux codex → wt-codex
L4 Service: single MCP Git Server on monorepo root; each client cwd = its worktree
L5 (optional) Host: sensitive tenants → dedicated Cloud Mac, no co-tenancy

Probe tests: peer worktree should be unreadable or read-only; write to ../wt-other/README must fail; git status shows only local worktree changes.

5. Developer best practices

1. Deny first, then allow: default deny ~, /etc, .env*, *.pem; whitelist project subtrees.
2. Never run agents as root: dedicated Unix user, umask 027, separate log dir.
3. Worktree naming: wt-{agent}-{branch-slug} — avoid human clone collisions.
4. Single MCP + path contract: document "client cwd must equal allowed subpath"; restart client session when switching worktrees.
5. CI/human gate before merge: agents push branches only; pre-commit secret scan.
6. Temp files in worktree tmp/: periodic git clean.
7. Always-on Cloud Mac: laptop sleep breaks MCP long connections — colocate isolation config on 7×24 nodes (MCP on Cloud Mac).

6. Scenario matrix

7. Recommended stacks

Stack A — Solo: Cursor rules + feature branch + no .env in repo
Stack B — Dual CLI: separate HOME + dual worktree + single MCP Git + 24GB Cloud Mac
Stack C — Team CI agent: Docker sandbox + read-only source mount + Cloud Mac sign/notarize
Stack D — Multi-tenant prod: per-tenant Cloud Mac + unique SSH keys + no shared MCP
Stack E — OpenClaw: Gateway + per-task worktree + launchd tmp cleanup

8. Common mistakes

• Mistake 1: "Branch isolation" without worktree — npm install in one agent still mutates shared lockfile.
• Mistake 2: MCP Filesystem mounted above project root.
• Mistake 3: Shared ~/.claude or ~/.codex state — hooks and caches cross-wire.
• Mistake 4: Prompt-only "don't touch other dirs" — config and OS boundaries beat prompts.
• Mistake 5: Isolation without acceptance tests — quantify cross-writes and denied probes.

9. Seven-step rollout & acceptance

1. Inventory write surfaces: repo, ~/ config, MCP roots, /tmp.
2. Configure L1 allowlists: deny sensitive paths; document in docs/agent-isolation.md.
3. Create worktrees: one directory per parallel agent; CI checks git worktree list.
4. Bind tmux + HOME: session names match directories; script startup.
5. Align MCP: single Server, paths match worktrees; tools/list smoke test.
6. 48h parallel soak: metrics — zero cross-writes, tools/call ≥95% success, 100% denied unauthorized probes.
7. Move to always-on Cloud Mac: laptop becomes SSH remote only.

10. FAQ

Q1: File isolation vs sandbox?

A: Sandbox limits execution environment (container, Seatbelt); file isolation governs path sovereignty. Stack both in containers with correct mounts.

Q2: Worktree with only one agent?

A: Feature branches suffice; if you often open a second CLI, pre-create worktrees — low cost.

Q3: One MCP Server per agent?

A: Possible but doubles memory/port cost; dual agents on one host usually use one Server + aligned client cwd.

Q4: Docker isolation for agents on macOS?

A: Solid for CI; daily Claude Code native flow prefers worktree + user separation.

Q5: How to quantify acceptance?

A: kvmboot internal trio: zero cross-writes, 100% denied probe rate, memory_pressure yellow ≤2h in 48h parallel soak (see dual-agent article).

11. Summary

AI Agent file isolation puts every write in a declared, auditable, disposable boundary. Best practice is tiered stacking — allowlists as baseline, worktrees for parallel repo edits, dedicated Cloud Mac for tenants and customer data. Chain with dual-agent isolation, worktree farm, and MCP deployment for a reproducible production topology.