Skip to main content
The SQL VFS keeps a filesystem in a database’s tables. It supports full read and write operations and needs no extra for a SQLite file: it uses Python’s own sqlite3.

Config

The tables are laid out as AgentFS’s:
  • fs_inode: one row per file and directory, with its size and mtime
  • fs_dentry: each entry’s name under its parent directory
  • fs_data: a file’s bytes, in rows of the database’s chunk size (4 KiB unless the database says otherwise)
  • fs_config: the chunk size
The TypeScript mount reads and writes the same tables, so a Python and a Node process on one file serve one filesystem.

Several mounts on one database

A mount serves one folder of its database, / by default. Hand two mounts one driver to serve the whole database at / and its /workspace folder as a mount of its own:
  • capacity counts every file in the database, whichever mount wrote it. Mounts on one driver with the same capacity share one count, so their writes together stay within it. Mounts on separate drivers count apart, even on one file, and together they can pass it.
  • get_state and load_state keep and replace the mount’s own folder. A restore leaves the rest of the database as it was.

VFS.md

The VFS.md an agent reads with SQL mounted at /<path>.

Virtual Filesystem

Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.

Cache

Index TTL is 0, so listings are read from the database every time. A workspace index: block still applies its ttl to this mount.

Example