Filesystem for AI Agents: What I Learned Building One
Most agentic systems, like Claude Code, that run on laptops and servers, interact with files natively through bash. But building an agentic system that allows users to upload and work with files comes with its own limitations that make you unable to store files on the server the agent runs on, and give the agent the bash tool:
- The fact that it's exposed to users anywhere — bad actors can get it to run commands that can crash the server or exploit other stuffs, so you want only file operations
- Even if you allow only file operations, you can't store every user's files on the server due to storage limits, so you'll have to store files in remote storage like S3 or Azure — but mounting them will make native commands like grep slow, as it has to download the full file first
- Even if you had unlimited storage and didn't need mounting, you still need isolation — where the agent cannot access files uploaded by another user, or by the same user in another session
There are other solutions to these problems, but they each come with their own tradeoffs:
- VM/sandbox platforms (E2B, Northflank) — spin up an isolated environment per conversation, which solves security and isolation. But they have cold start latency, operational overhead, and cost that compound at scale. You're managing servers again, just indirectly.
- S3 mounting (mountpoint-s3, JuiceFS, s3fs) — mount remote object storage as a local filesystem. Grep and similar commands work, but inefficiently — each scan triggers sequential HTTP range requests that essentially download the whole file in chunks. Too slow for agent workloads.
- just-bash (Vercel Labs) — a TypeScript reimplementation of bash with a pluggable filesystem backend. Closest to what I wanted, but TypeScript only. My pipeline is Python.
- Localsandbox (CoPlane) — Python wrapper around just-bash, which would have solved the language problem. But it bridges Python to just-bash via a Deno runtime, adding a deployment dependency I didn't want in a Celery environment.
I ran into this problem recently while building a legal AI agentic system where users had to upload files for the agent to work with. The solution I needed had to be database-like storage that doesn't need to be spun up and down like a server, but supports native file operations that can be exposed as tools to the agent, with the agent unable to access anything outside its own scoped workspace.
Then I found AgentFS — a filesystem built specifically for AI agents, backed by Turso/SQLite. It provides scoped, isolated storage per user and session, with file operations that can be wired directly as agent tools.
Of the integration options — Python SDK, AgentFS + just-bash, AgentFS + FUSE — I went with the Python SDK. Unlike FUSE, which gives the agent a real mount but leaves the rest of the server exposed, the Python SDK puts you in full control. The agent can only do what you explicitly wire up as a tool. No shell escape, no arbitrary commands, no environment variable leaks. The isolation is in the design, not bolted on afterward.
The trade-off is that you're responsible for the tool surface. The SDK ships with the basics — read, write, list — but search operations were missing. No grep, no find, no wc. For an agent that needs to navigate files without dumping everything into context, those aren't optional. So I built them and raised a PR to have them integrated directly into the SDK.
AgentFS relies on Turso DB for hosted production use. Locally, the pattern already works — one SQLite file per user, each opened independently with full read-write access. But on a production server, you can't manage hundreds of separate database files manually. You need a single server process that can route connections to the right user's database.
Turso Cloud solves part of this — it supports creating thousands of separate databases and even lets you query across them using ATTACH. But attached databases are currently read-only. You can read from multiple user databases in one session, but you can't write to them. For an agentic system where the agent needs to create, modify, and delete files in a user's scoped workspace, read-only access isn't enough.
Turso has confirmed that full read-write ATTACH support is on their roadmap. On the AgentFS side, the open() call goes through a connect() function that can be pointed at a Turso-managed database instead of a local file — so the SDK integration path is straightforward once Turso ships the write support. Until then, full production multi-user AgentFS is blocked on this upstream feature.
Top comments (1)
The post’s strongest point is that “filesystem for agents” is really a trust-boundary and isolation problem, not just a convenience layer for file I/O. It compares sandboxes, mounted object storage, just-bash style approaches, and AgentFS with scoped storage, then argues for explicit tool surfaces over giving an agent a real shell. ([DEV Community][1])
This was a strong read because it stays anchored to the real problem instead of romanticizing agents.
A lot of people talk about agent tooling as if the question is just how to give the model more power. Your post makes the more important point: the moment users can upload files and an agent can act on them, the problem stops being convenience and becomes isolation, scope, and trust boundaries.
That is what I liked most here. You did not just list options. You actually walked through the tradeoffs. Sandboxes buy isolation but bring latency and cost. Mounted object storage looks convenient until native file operations become painfully inefficient. Shell-like approaches feel powerful until you remember what else a shell exposes. That is the kind of engineering reality too many agent posts skip.
The AgentFS angle is interesting precisely because it treats the filesystem less like a literal machine primitive and more like an application level control surface. That is the right instinct. In most production systems, giving an agent unrestricted bash is not sophistication. It is a liability disguised as flexibility.
Also appreciated the honesty about the downside: once you choose the safer path, you inherit responsibility for the tool surface. That is the real work. Safety is not free. It has to be designed, implemented, and maintained deliberately.
Good post. It frames agent infrastructure the way more people should: not as “how do I let the model do everything,” but “what is the narrowest, safest, most useful slice of capability I can expose without lying to myself about the risk.”