2026 AI Agent Dateisystem-Design: Sandboxes, Schichtspeicher & vollständige Architektur

Bottom line: Giving an agent full-disk RW is the riskiest default. The 2026 pragmatic pattern is a four-layer Agent File System (AFS)—writable workspace, partitioned memory and artifacts, disposable tool cache—fronted by a Policy Gateway for path allowlists and audit. Solo devs: MCP filesystem; production teams: remote Mac workspaces with snapshots.

Last updated August 8, 2026. Layers and paths apply to Claude Code, Cursor Agent, LangGraph, and custom tool stacks; MCP server names vary by release, but the layering model transfers.

If you are wiring MCP into a coding agent or debating whether it should edit your laptop repo directly, the question is not “filesystem tool or not”—it is which paths are writable, how you roll back bad writes, and whether memory files live beside Git. Agent File System (AFS) is the policy-aware virtual tree between the agent and the OS.

Why agents must not “just read the disk” (Why)

Early demos point agents at ~ or a monorepo root. Three failure modes follow:

1. Over-read—.env, SSH keys, browser profiles land in context and leak via logs or PRs.
2. Non-rollback writes—mass renames, config deletes, staging secrets committed to source.
3. State/code coupling—summaries, vector indexes, and build logs mixed with tracked files—no TTL or per-user delete.

CI solved this with one job, one workspace (see our iOS CI vs remote Mac build guide). Agents need the same rule: execution boundary before model capability.

Four layers of Agent File System (What)

Asymmetric takeaway: Most incidents are L1/L2 mixing—user prefs committed to Git. Route memory through a dedicated Memory tier, not another folder in the repo.

Full architecture diagram

Production topology: the runtime talks only to the Policy Gateway; storage sits on local disk, container volumes, or a remote Cloud Mac node.

┌─────────────────────────────────────────────────────────────────────────────┐
│                    Agent Runtime (Claude Code / Cursor / LangGraph)          │
└───────────────────────────────────┬─────────────────────────────────────────┘
                                    │ tool calls (read/write/list/glob)
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│              Policy Gateway (path policy + audit + rate limits)              │
│   allow: /workspace/** RW   |   deny: ~/.ssh, /etc, ../outside-root          │
└───────────────────────────────────┬─────────────────────────────────────────┘
                                    │
          ┌─────────────────────────┼─────────────────────────┐
          ▼                         ▼                         ▼
┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐
│  L1 Workspace    │    │  L2 Memory Store │    │  L3 Artifacts    │
│  task RW sandbox │    │  summaries/embed │    │  builds/logs/RPT │
│  git clone here  │    │  SQLite/Redis/PG │    │  read-only / TTL │
└────────┬─────────┘    └────────┬─────────┘    └────────┬─────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 ▼
                    ┌────────────────────────┐
                    │  L4 Tool Cache         │
                    │  npm/pip/derived index │
                    │  rebuildable, wipe OK  │
                    └────────────┬───────────┘
                                 ▼
                    ┌────────────────────────┐
                    │  Host Volume / Remote  │
                    │  Mac Node (Cloud Mac)  │
                    └────────────────────────┘

• Gateway is the only door—no direct host open(); all IO via MCP or custom FS API.
• Split L1 and L3—build outputs never write back into the Git tree.
• L4 is disposable—exclude from nightly backup.
• Remote node = movable L1—on SSH Cloud Mac, /workspace is the whole blast radius.

Core compare: three AFS implementation paths

The divider is not “can list_dir” but whether policy is versioned, auditable, and destroyable in one action.

How to choose (decision matrix)

Recommended stacks

Stack A — fastest solo (1 day)

• MCP filesystem: allowed_directories = project root only
• .cursorignore / ignore files for .env*, *.pem
• Scratch memory in .agent/memory.json (gitignored)—solo only

Stack B — small team production

• Cloud Mac: /workspace/<job-id> + APFS snapshot per task
• Policy Gateway YAML for allow/deny prefixes
• L2 Postgres/Redis; L3 object store or /artifacts
• Audit every write: path, agent_id, diff_hash

Stack C — enterprise compliance

• L1 sparse checkout of customer-authorized paths only
• Secrets from vault—never in agent context
• Destroy workspace volume when task ends

Common pitfalls

1. MCP root = ~—hands the whole machine to the model.
2. Memory files in Git—merge pain, leaks, no per-user GDPR delete.
3. Artifacts beside source—glob **/* pulls gigabytes into context.
4. No snapshot before write—one bad rm -rf with no restore.
5. Cache treated as permanent—“amnesia” after cache wipe means path coupling.
6. Local vs remote path drift—/Users/foo/project vs /workspace configs diverge.

Rollout (7 steps)

1. Map four layers—absolute paths and owners for L1–L4.
2. Author policy YAML—allow/deny prefixes, max bytes, extension blocklist.
3. Route all tools through Gateway—no bypass FS calls.
4. Split Memory—remove committed .agent/*; migrate to L2.
5. Snapshots or git worktrees—recovery point before each L1 task.
6. Artifacts read-only—CI writes L3; agent reads only.
7. 7-day red team—probe ../.ssh and /etc writes; verify deny.

Policy Gateway sample

# afs-policy.yaml
version: 1
workspace_root: /workspace
rules:
  - action: allow
    paths: ["/workspace/**"]
    modes: [read, write, list]
  - action: allow
    paths: ["/memory/**"]
    modes: [read]
  - action: allow
    paths: ["/artifacts/**"]
    modes: [read]
  - action: allow
    paths: ["/cache/**"]
    modes: [read, write, delete]
  - action: deny
    paths: ["**/.env", "**/.env.*", "**/id_rsa", "**/.ssh/**"]
  - action: deny
    paths: ["../**", "/etc/**", "/var/**"]
max_file_bytes: 5242880
audit_log: /var/log/afs-audit.jsonl

FAQ

How does AFS relate to the OS filesystem?

AFS is a logical view + policy layer on top of APFS, ext4, or network volumes. Agents should see only the virtual tree the gateway exposes.

Is MCP filesystem enough for production?

Fine for individuals and betas; production needs audit, snapshots, multi-tenant isolation, and centralized policy—usually a custom gateway or remote workspace.

Can L2 Memory live in Git LFS?

No—memory needs per-user delete, encryption, and TTL; use a database or object store.

How do remote Mac nodes map to AFS?

Make /workspace the only RW area per session; clone inside it; destroy or snapshot-revert after the task. See help center and pricing.

How to stop agents from reading the whole tree into context?

Cap list results, block unbounded ** globs, and budget cumulative read tokens at the gateway.

Conclusion

Designing Agent File System in 2026 is about four layers plus a Policy Gateway, not sprinkling read_file on tools. Start with MCP allowlists solo; move L1 to snapshot-backed remote Mac workspaces for teams; never mix Memory or Artifacts with Git.

Before ship, ask: if the agent writes right now, what is the worst layer it can destroy? If the answer is “the whole machine,” you still need AFS.

Remote Mac workspace checklist

When you map AFS to a Cloud Mac node, treat the session like a disposable CI runner:

• Provision /workspace on a dedicated volume—not the system data partition.
• Run git clone --depth 1 inside the workspace; never mount the operator laptop over SSHFS.
• Snapshot before the first agent write; tag snapshots with task_id for support replay.
• Stream audit logs off-node; assume the workspace volume may be wiped hourly.
• Keep L2 Memory on a regional database—do not store user embeddings only inside the Mac volume.

Teams pairing this layout with OpenClaw remote builds often reuse the same snapshot discipline for compile jobs and agent edit sessions, which cuts “works on my Mac” drift across environments.

Further reading

• Self-Hosted vs SaaS Agent Memory →
• OpenClaw Cloud-Automatisierung →