FUSE is All You Need: Using Virtual Filesystems for AI Agents

Executive Summary

This document analyzes the use of FUSE (Filesystem in Userspace) as a bridge between domain data and AI agent sandboxes. The approach addresses a key challenge in building filesystem-based agents: how to materialize existing data sources (Postgres databases, object storage, APIs) into a sandbox filesystem without complex synchronization patterns.

1. Background

1.1 The Rise of Filesystem-Based Agents

Giving agents access to a sandboxed environment with a shell and a filesystem has emerged as a dominant pattern in agentic harnesses. Notable examples include:

• Turso's AgentFS
• Anthropic's Agent SDK (bringing Claude Code's harness to non-coding domains)
• Vercel's text-to-SQL agent built on a sandbox
• Anthropic's Agent Skills for filesystem-based progressive disclosure

Core Rationale: The major AI labs are investing heavily in reinforcement learning for coding tasks in these environments. Aligning with this paradigm allows leveraging gains from the coding domain in other problem spaces.

1.2 Advantages of the Filesystem Approach

2. The Core Problem

2.1 The Implementation Gap

While the filesystem-based approach has clear advantages, a fundamental question remains:

How do you actually materialize Postgres + object storage + APIs into a sandbox FS in a practical and scalable way?

Common concerns when bridging domain data to a filesystem:

• When do I copy over the files?
• Do I copy over everything?
• How do I write back updates that the agent made?
• When do I sync edits made by a human?
• How do I show folders/files progressively as the agent progresses?

2.2 Proposed Solution: FUSE

FUSE (Filesystem in Userspace) provides a mechanism to expose arbitrary data structures as files without copying or synchronization. Instead of preloading data into the sandbox, the filesystem operations are translated in real-time to queries against the backend.

3. Architecture

3.1 High-Level System Architecture

Traditional User Path (top row):

• Users interact through a UI
• UI communicates with a backend API
• Backend reads/writes to a database

Agent Path via FUSE (bottom row):

• Agent runs inside a sandbox environment
• Agent sees a mounted filesystem
• Filesystem operations are intercepted by FUSE
• FUSE translates operations to backend queries
• Both paths access the same underlying data

3.2 FUSE Operations Mapping

The FUSE layer implements standard filesystem operations that map to domain-specific actions:

4. Implementation Example: Email Agent

4.1 Filesystem Layout

/workspace/
  Inbox/
    Customer Inquiry - Size Chart (emily.wolfe@gmail.com)
    PO Confirmation #2026-0038 (supplierC@fabricdirect.com)
    Shipping Delay Notice (supplierA@logisticsco.com)
    Partnership Proposal - TrendCircle (marketing@trendcircle.io)
    Wholesale Inquiry - SilverLeaf Boutique (boutique@silverleaf.co)
    Missing Documents - Customs (carrier-support@airbridge.co)
    Last Call: VAT Filing Deadline (gov-tax@tradeportal.gov)

  Starred/
    --> Wholesale Inquiry - SilverLeaf Boutique (symlink)
    --> VAT Filing Deadline (symlink)

  Needs_Action/
    --> Missing Documents - Customs (symlink)
    --> VAT Filing Deadline (symlink)

  Orders/
    2026/Feb/
      PO Confirmation #2026-0038
      Shipping Delay Notice

  Customers/
    Returns/
      Return Request #8743

  Sent/
    Re: Customer Inquiry - Size Chart

4.2 Core FUSE Operations

readdir (Directory Listing)

export async function readdir(path: string, cb: (err: number, names?: string[]) => void) {
  // Find the folder by path
  const [folder] = await db.select().from(foldersTable)
    .where(eq(foldersTable.path, path));

  if (!folder) {
    return cb(Fuse.ENOENT);
  }

  // Get emails in this folder
  const emailsInFolder = await db.select({
    email: emailsTable,
    sender: contactsTable,
  }).from(emailsTable)
  .leftJoin(contactsTable, eq(emailsTable.sender, contactsTable.id))
  .where(eq(emailsTable.folderId, folder.id));

  const entries = new Set<string>();

  for (const {email, sender} of emailsInFolder) {
    entries.add(`${email.subject} (${sender.email}).eml`);
  }

  // Add subfolders
  const subfolders = await db.select().from(foldersTable)
    .where(like(foldersTable.path, sql`${path}/%`));
  for (const subfolder of subfolders) {
    entries.add(subfolder.path.split("/").pop() || "");
  }

  cb(0, Array.from(entries));
}

read (File Content)

export async function read(
  path: string,
  fd: number,
  buf: Buffer,
  len: number,
  pos: number,
  cb: (err: number) => void
) {
  const email = await getEmailById(fd);
  if (!email) {
    return cb(Fuse.ENOENT);
  }
  const content = emailToContent(email);
  const slice = content.slice(pos, pos + len);
  const bytesRead = buf.write(slice);
  cb(bytesRead);
}

export function emailToContent(email: EmailWithSender): string {
  return `From: ${email.senderEmail}
Date: ${email.sentAt.toISOString()}
Subject: ${email.subject}
X-Folder: ${email.folderPath}
X-Starred: ${email.starred}
X-Needs-Action: ${email.needsAction}

${email.body}
`;
}

4.3 Virtual Folders

The implementation introduces virtual folders that don't exist in the traditional sense:

• Starred: Contains symlinks to emails with the starred flag
• Needs_Action: Contains symlinks to emails requiring user attention

Additional FUSE operations implemented:

• readlink: Read symlink target
• symlink: Create a symlink (stars an email)
• unlink: Remove a symlink (unstars an email)

5. Agent Integration

5.1 System Prompt Design

You are an email assistant helping the user manage their inbox.

You have access to a filesystem at /workspace representing their email:

- Folders: Inbox, Sent, Orders, Customers, etc.
- Emails: .eml files named "Subject (sender@email.com).eml"
- Filenames contain spaces (from email subjects), so always quote paths in shell commands
- Starred/Needs_Action: contain symlinks to flagged emails

Commands you use internally:
- ls, cat, find -> browse emails
- mv -> move emails between folders
- ln -s <email> /Starred/ -> star an email
- rm /Starred/<email> -> unstar an email
- mkdir -> create folders

When responding to the user:
- Describe emails by subject and sender, not filenames
- Say "starred" not "created symlink"
- Say "moved to Orders" not "mv to /Orders/"
- Summarize what you found/did in plain language

5.2 Example Interactions

Query: "Which emails do I have in my Inbox?"

Agent Behavior:

ls -la /workspace/Inbox/

Response:

You have 6 emails in your Inbox:

1. "Missing Documents - Customs" from carrier-support@airbridge.co (Jan 4)
2. "PO Confirmation #2026-0038" from supplierC@fabricdirect.com (Jan 9)
3. "Partnership Proposal - TrendCircle" from marketing@trendcircle.io (Jan 7)
4. "Re: Restock ETA For Red Jackets" from supplierA@logisticsco.com (Jan 5)
5. "Shipping Delay Notice" from supplierA@logisticsco.com (Jan 8)
6. "Wholesale Inquiry - SilverLeaf Boutique" from boutique@silverleaf.co (Jan 6)

Query: "Organize my Inbox"

Agent Behavior:

# Move customer-related emails
mv "/workspace/Inbox/Customer Inquiry..." /workspace/Customers/
mv "/workspace/Inbox/Wholesale Inquiry..." /workspace/Customers/

# Move order-related emails
mv "/workspace/Inbox/PO Confirmation..." /workspace/Orders/
mv "/workspace/Inbox/Shipping Delay..." /workspace/Orders/

# Create new folder for business opportunities
mkdir -p /workspace/Business_Opportunities
mv "/workspace/Inbox/Partnership Proposal..." /workspace/Business_Opportunities/

6. Key Design Principles

6.1 On-Demand Loading

Data is only loaded when accessed, eliminating the need to preload entire databases into the sandbox. This approach:

• Reduces memory footprint
• Eliminates synchronization concerns
• Provides real-time access to current data

6.2 No Copying, No Sync

Since the FUSE layer reads directly from the database:

• No risk of data going out of sync
• No write-back logic required
• Single source of truth maintained

6.3 Context Engineering Balance

The filesystem mapping is a context engineering challenge. Key considerations:

• Leverage familiar filesystem semantics
• Avoid over-abstracting to the point of confusion
• Map domain concepts intuitively to filesystem concepts

7. Future Outlook

7.1 Potential Improvements

1. Context Compaction: Include old conversations as files on the filesystem
2. Result Caching: Make old tool call results appear as files after compacting context
3. Enhanced Operations: Additional domain-specific filesystem operations

7.2 Ideal API Vision

A sandbox provider could offer an API like:

new Agent({
  tools: [...],
  sandbox: {
    filesystem: {
      '/emails': (folder) => listEmails(folder),
      '/old_conversations': () => listOldConversations(),
    }
  }
});

This would abstract away FUSE, sandbox management, and execution details, making virtual filesystems accessible to all developers.

8. Conclusion

FUSE provides an elegant solution to bridging domain data and AI agent sandboxes. By implementing a small, well-defined interface, any data source can be exposed as a filesystem, allowing agents to leverage familiar Unix paradigms for browsing, reading, and organizing data.

The key insight is that the filesystem serves as a UI layer for the agent, analogous to how a frontend presents data to human users. This approach:

• Eliminates synchronization complexity
• Provides on-demand data access
• Leverages existing agent training on filesystem operations
• Reduces tool space complexity

References

• Original Article: https://jakobemmerling.de/posts/fuse-is-all-you-need/
• GitHub Implementation: https://github.com/Jakob-em/agent-fuse
• Anthropic Agent SDK: https://docs.anthropic.com/
• fuse-native (TypeScript bindings): https://github.com/fuse-bindings/fuse-native