Skip to main content
AgentFS uses an overlay filesystem to provide copy-on-write isolation. This lets agents freely modify files while keeping your original data safe.

​
How Overlay Works

An overlay filesystem combines two layers: 
┌────────────────────────────────────┐
│         Merged View (what you see) │
├────────────────────────────────────┤
│  Delta Layer (AgentFS database)    │  ← Writes go here
├────────────────────────────────────┤
│  Base Layer (original directory)   │  ← Read-only
└────────────────────────────────────┘
Reading a file:
  1. Check delta layer first
  2. If not found, read from base layer
Writing a file:
  1. Copy file to delta layer (if from base)
  2. Write changes to delta layer
  3. Base layer is never modified
Deleting a file:
  1. Create a “whiteout” marker in delta layer
  2. File appears deleted in merged view
  3. Original file in base layer is untouched

​
Creating an Overlay Filesystem

​
With agentfs run

The simplest way - automatically creates an overlay over your current directory: 
cd /path/to/project
agentfs run /bin/bash

​
With agentfs init --base

Create an overlay explicitly: 
agentfs init my-overlay --base /path/to/project
Then mount it: 
agentfs mount my-overlay ./workspace
Or run a command in it: 
agentfs run --session my-overlay /bin/bash

​
Viewing Changes

See what’s different from the base: 
agentfs diff my-overlay

​
Practical Examples

​
Safe Refactoring

Let an agent refactor your code without risk: 
cd my-project
agentfs run --session refactor python3 refactor_agent.py

# Review what changed
agentfs diff refactor

# Happy? Apply changes manually or via script
# Not happy? Just delete the session
rm .agentfs/refactor.db

​
Testing Destructive Operations

Try something dangerous safely: 
agentfs run --session test /bin/bash
$ rm -rf src/  # Yikes!
$ exit

# Original files are fine
ls src/  # Still there!

# Only the overlay was affected
agentfs fs ls test  # Shows the deletion

​
Parallel Experiments

Run multiple experiments on the same codebase: 
# Experiment A
agentfs run --session exp-a python3 approach_a.py

# Experiment B (same base, different changes)
agentfs run --session exp-b python3 approach_b.py

# Compare results
agentfs diff exp-a
agentfs diff exp-b

​
Storage Efficiency

The overlay only stores:
  • Modified files - Full copy after first write
  • New files - Stored entirely in delta
  • Deleted files - Small whiteout marker
Original files are never duplicated. A 10GB project with 1MB of changes only uses ~1MB in the delta layer.

​
Technical Details

​
File Operations

OperationBehavior
Read existing filePass through to base
Write existing fileCopy to delta, then write
Create new fileWrite directly to delta
Delete fileCreate whiteout in delta
Rename fileDelete old + create new

​
Whiteouts

When you delete a base file, AgentFS creates a “whiteout” - a marker that hides the file: 
-- Whiteouts in the database
SELECT * FROM fs_inode WHERE whiteout = 1;

​
Database Schema

The delta layer is stored in SQLite: 
-- Files and directories
CREATE TABLE fs_inode (
    ino INTEGER PRIMARY KEY,
    parent_ino INTEGER,
    name TEXT,
    mode INTEGER,
    size INTEGER,
    ...
    whiteout INTEGER DEFAULT 0
);

-- File contents
CREATE TABLE fs_block (
    ino INTEGER,
    block_num INTEGER,
    data BLOB
);
See the AgentFS Specification for the complete schema.

​
Next Steps

Sessions

Share state between agents

Syncing

Sync overlays to Turso Cloud