AgentHarborFS

AgentHarborFS is Agent Harbor’s cross-platform filesystem layer that provides copy-on-write snapshots and per-process isolation. It enables instant workspace branching, time-travel debugging, and parallel agent execution without filesystem conflicts.

Why AgentHarborFS?

Linux provides native copy-on-write filesystems (ZFS, Btrfs) and mount namespaces for process isolation. macOS and Windows lack these capabilities. AgentHarborFS provides a consistent experience across all platforms.

Key Capabilities

Copy-on-Write Snapshots

Create instant point-in-time snapshots of the entire filesystem state:

• No data duplication — snapshots share unchanged blocks
• Memory-efficient storage with transparent disk spillover
• Writable branches from any snapshot

Branch Directory Model

Each agent session gets its own filesystem branch:

/branches/
  ├── task-claude-1/    # First Claude agent's workspace
  ├── task-claude-2/    # Second Claude agent's workspace
  └── task-codex-1/     # Codex agent's workspace

• Path-based resolution (no kernel PID lookup)
• Different processes see different filesystem views
• No VFS cache pollution between branches

Overlay Mode

AgentHarborFS operates as an overlay over your existing workspace:

• Pass-through reads — Unmodified files served directly from host filesystem
• Copy-up on write — Only modified files stored in the branch
• Whiteouts for deletes — Deletions mask files without altering the host
• Metadata overlay — Permission changes captured without copying file content

Materialization Modes

AgentHarborFS supports two strategies trading off between performance and isolation:

Lazy Mode

Classic overlay behavior: reads pass through to host, writes trigger copy-up. Fast and efficient, but host filesystem changes after branch creation may be visible to agents that haven’t accessed those files yet.

Eager Mode

Materializes all files at branch creation, providing true point-in-time snapshot semantics — agents see exactly what existed when the branch was created, immune to subsequent host changes. When the backstore filesystem supports it, Eager mode automatically uses filesystem-native block cloning (APFS clonefile(), Btrfs/XFS reflink, ReFS block cloning) so unmodified blocks are shared at the filesystem level with minimal storage overhead. On filesystems without reflink support, Eager mode transparently falls back to byte-copy.

Platform Implementations

Linux (FUSE)

Native FUSE filesystem with optional passthrough mode for maximum performance:

# Passthrough mode on Linux 6.9+
AGENTHARBORFS_FUSE_PASSTHROUGH=1 ah agent start --agent claude --fs-snapshots agentharborfs

macOS (FSKit)

FSKit-based filesystem extension with per-task overlay. Agents are chrooted into their branch to maintain original project paths.

Windows (WinFsp)

WinFsp filesystem providing the same CoW overlay. Per-process drive letter mapping creates a chroot-like environment.

Path Policies

AgentHarborFS supports configurable policies for different path categories:

Usage

With ah agent start

# Auto-detect best provider (prefers native ZFS/Btrfs, falls back to AgentHarborFS)
ah agent start --agent claude --fs-snapshots auto --prompt "Add tests"
 
# Force AgentHarborFS
ah agent start --agent claude --fs-snapshots agentharborfs --prompt "Add tests"

Working Copy Modes

# Copy-on-write overlay (default with AgentHarborFS)
ah agent start --agent claude --working-copy cow-overlay --prompt "Task"
 
# Git worktree isolation
ah agent start --agent claude --working-copy worktree --prompt "Task"
 
# In-place (no isolation)
ah agent start --agent claude --working-copy in-place --prompt "Task"

Performance

AgentHarborFS provides several I/O optimization modes:

Kernel-Backstore Proxy (KBP)

Default mode where the adapter services I/O using hidden host filesystem handles. Provides good memory efficiency and works everywhere.

FUSE Passthrough

On Linux 6.9+, the kernel forwards read/write directly to backing files, completely bypassing the FUSE daemon for data I/O. Requires CAP_SYS_ADMIN.

Interpose Mode

On macOS, AgentHarborFS can inject a DYLD interposer shim (libagentharborfs_interpose_shim.dylib) that intercepts filesystem operations and receives real OS file descriptors from the daemon. Data I/O bypasses the adapter entirely while path operations still route through AgentHarborFS.

Comparison with Alternatives