AgentFS in the Browser

The filesystem is quickly becoming the de facto interface for agent execution. It is not hard to see why: centered around the “everything is a file” philosophy that started with Unix more than 40 years ago, we have decades of highly specialized tools and systems built around the file abstraction, as well as a never-ending amount of documentation and lore about how to best use them. An LLM’s wet dream!

But filesystems are unfortunately not available everywhere, especially not everywhere that modern agents want to run. This means browser-based agents can't use mkdir, touch, grep, git, or any of the thousands of CLI tools built around files. Tools that represent a huge portion of their training data. This is where a virtualized filesystem becomes essential.

AgentFS is a project that provides a filesystem abstraction for sandboxed agents. All the filesystem data is stored in a SQLite file powered by Turso, a full rewrite of SQLite in Rust. It allows agents to be isolated, snapshotted, audited, and seamlessly moved around. Because Turso has a WASM build that runs in the browser, we can use AgentFS to provide a filesystem abstraction for agents that are running in the browser.

In this article, we will see how it works, and close with an example that shows how one can clone and manipulate a git tree right in the browser!

#Basic AgentFS in the Browser

The simplest way to use AgentFS in the browser is with an in-memory database through @tursodatabase/database-wasm. This is perfect for applications that don't need persistence across sessions, like temporary workspaces or ephemeral agent environments.

Here's how to initialize AgentFS in a browser application:

import { AgentFS } from 'agentfs-sdk';
import { connect } from '@tursodatabase/database-wasm';

// Open an in-memory database
const db = await connect(':memory:');
const fs = await AgentFS.openWith(db);

// Now you have a complete filesystem in memory
await fs.fs.writeFile('/notes.txt', 'Hello from the browser!');
const content = await fs.fs.readFile('/notes.txt', 'utf8');

// Key-value storage for agent state
await fs.kv.set('session:id', { user: 'alice', started: Date.now() });
const session = await fs.kv.get('session:id');

// Track tool calls for observability
const callId = await fs.tools.start('web_search', { query: 'AgentFS' });
// ... perform the search ...
await fs.tools.success(callId, { results: [...] });

#Persistent Storage with OPFS

For applications that need data to persist across sessions, AgentFS can use the browser's Origin Private File System (OPFS). OPFS provides a private filesystem that's isolated per origin, with better performance than traditional browser storage APIs:

import { connect } from '@tursodatabase/database-wasm';

// Use OPFS for persistent storage
const db = await connect('agentfs.db');  // Path in OPFS
const fs = await AgentFS.openWith(db);

// Data persists across page reloads
await fs.fs.writeFile('/documents/resume.pdf', pdfBuffer);
const content = await fs.fs.readFile('/documents/resume.pd');

// Query filesystem state with SQL
const files = await db.execute(
  'SELECT path, size FROM inodes WHERE type = "file"'
);

All operations happen entirely in the browser, with no server required. This makes AgentFS perfect for privacy-sensitive applications where data should never leave the user's device.

#AgentFS with Turso Cloud Remote Sync

While local-only storage is powerful, many applications need to sync data across devices, collaborate with other users, or provide resumable agents.

Turso allows the database to be synced across multiple devices, and the Turso Cloud provides a turnkey solution to achieve that. The sync is intelligent: whenever possible, instead of downloading entire databases, it uses a query-based bootstrap strategy where only data accessed by your queries is pulled locally.

Here's how to set up AgentFS with remote sync (you will need a Turso Cloud account for that)

import { connect } from '@tursodatabase/sync-wasm';
import { AgentFS } from 'agentfs-sdk';

// Connect to a remote Turso database with sync
const db = await connect({
  path: ':memory:',
  url: 'libsql://<db>-<org>.turso.io',
  authToken: '<auth-token>',
});

const fs = await AgentFS.openWith(db);

// Operations work exactly the same
await fs.fs.writeFile('/shared/data.json', JSON.stringify(data));

await db.push(); // push changes to the remote

// now changes sync to the remote database
// and are accessible from other devices

The beauty of this approach is that the AgentFS API remains identical. Your application code doesn't need to know whether it's using a local-only database or one that syncs with a remote server. The sync happens transparently in the background.

#Example: Git in the Browser with AgentFS

One interesting use case for AgentFS in the browser is implementing Git functionality. The popular isomorphic-git library provides a pure JavaScript implementation of Git that can run in the browser, but it needs a filesystem abstraction. AgentFS is a perfect fit.

Git's storage model aligns naturally with AgentFS's filesystem interface. Git stores all its data in the .git directory using a specific structure:

• Objects: Commits, trees, and blobs stored in .git/objects/
• Refs: Branch and tag references in .git/refs/
• Index: The staging area in .git/index
• Pack files: Compressed object storage in .git/objects/pack/

All of these are just files and directories, exactly what AgentFS provides. Here's how to create a filesystem adapter for isomorphic-git:

import * as git from 'isomorphic-git';
import { AgentFS } from 'agentfs-sdk';

function agentfs(fs: AgentFS): git.PromiseFsClient {
  return {
    promises: {
      readFile: (path: string, options?: any) => fs.fs.readFile(path, options),
      writeFile: (path: string, content: any) => fs.fs.writeFile(path, content),
      readdir: (path: string) => fs.fs.readdir(path),
      stat: (path: string) => fs.fs.stat(path),
      ...
    },
  };
}

// Now use isomorphic-git with AgentFS
const db = await connect({
  path: ':memory:',
  url: 'libsql://<db>-<org>.turso.io',
  authToken: '<auth-token>',
});
const agentFS = await AgentFS.openWith(db);
const gitFS = agentfs(agentFS);

// All git operations work naturally
const commits = await git.log({ fs: gitFS, dir: '/repo', depth: 10 });
const { oid, filepath } = ...;
const tree = await git.readTree({ fs: gitFS, dir: '/repo', oid, filepath });

A live demo showing this working is available at https://agentfs-git.vercel.app/git. The demo clones a git tree containing the AgentFS source code into an in-memory database, so it starts fresh every time you reload the tab. All git commands work!

#Summary

AgentFS solves a critical limitation for browser-based agents: they can't access the thousands of CLI tools (mkdir, grep, git, etc.) that represent a huge portion of their training data. By providing a SQLite-powered virtualized filesystem that runs entirely in the browser via Turso’s WASM build. AgentFS lets agents use familiar file-based workflows without needing server infrastructure. Agents can be isolated, snapshotted, audited, and seamlessly moved between environments while maintaining the "everything is a file" philosophy they were trained on.

Check out the AgentFS repository on GitHub to explore the code, try the browser demos, and start building applications with filesystem abstractions that work seamlessly in the browser.