A new open-source tool called SmolFS tackles one of the more annoying problems in AI agent development: keeping files around after your agent process dies. Built by CelestoAI and posted to Hacker News on June 25, SmolFS provides a durable filesystem layer that lets agents write to workspace folders which persist across runtime restarts—without each agent instance managing its own storage setup.

The Persistence Problem

If you've been running AI agents locally or in the cloud, you know the drill. Your agent creates memory markdowns, context files, and working data during a session—but when that process terminates, all those artifacts evaporate. SmolFS solves this by letting you mount named volumes, write files normally through any tool that speaks filesystem paths, then unmount. Later, from another process or even another machine, you remount the same volume and pick up where you left off.

How It Works

The core is written in Rust for performance and safety. The installation script downloads prebuilt CLI binaries for Linux and macOS on x86_64 and arm64 architectures. A typical local workflow runs: smolfs doctor (checks mount support), smolfs init demo --dev (creates a SQLite-backed volume), smolfs mount demo ./workspace, then you use the directory normally before calling smolfs flush to sync writes and smolfs unmount demo. The next time you need those files, smolfs mount demo ./workspace brings them back.

SDK Bindings for Agent Runners

For developers integrating SmolFS into agent tooling, Python and TypeScript SDKs call the same Rust core without shelling out to a subprocess. The Python package installs via uv (uv add smolfs) and exposes SmolFS.from_env() for configuration management plus methods like ensure_volume(), mount(), flush(), and unmount(). The Node.js package ships prebuilt native bindings under @celestoai/smolfs for Linux and macOS. Both SDKs verify storage backend availability and mount support before attempting operations, throwing descriptive errors when prerequisites are missing.

Cloud Volumes with S3-Compatible Storage

Local dev mode uses SQLite for metadata and stores objects in the SmolFS home directory—perfect for single-machine iteration. For production workloads spanning multiple runtimes or machines, cloud volumes replace local storage with Redis for metadata (the file tree) and S3-compatible object storage for content. The project documentation walks through Cloudflare R2 setup: keep credentials in environment variables rather than command arguments to avoid leaking them into logs. Volume initialization takes a --metadata URL pointing to Redis and --storage s3 --bucket BUCKET_URL pointing to your object store.

Security Considerations

The README is explicit about treating SmolFS volumes like durable infrastructure: credentials, access keys, and Redis URLs with secrets should never appear in command arguments or logs. The design prefers explicit configuration over hidden global state—cloud metadata settings, bucket configurations, and storage credentials are all passed explicitly rather than discovered from ambient environment. Operations like mount and unmount aim for idempotency where feasible, and the tool fails loudly on missing prerequisites rather than silently degrading.

Current Status

SmolFS is at version 0.1.0 under Apache 2.0 licensing. The roadmap includes Python type stubs, a Linux CI job testing local volume mounting when mount support is available, and formal release notes before the first non-draft release. Prebuilt binaries exist for the CLI, wheels for Python (published to PyPI), and native npm packages for TypeScript on supported platforms.

Key Takeaways

  • SmolFS solves AI agent file persistence by mounting named volumes that survive process restarts
  • Rust core with Python (uv) and TypeScript (npm/@celestoai/smolfs) SDKs—no subprocess spawning required
  • Local dev mode uses SQLite; production workloads use Redis + S3-compatible storage like Cloudflare R2 or MinIO
  • Security design emphasizes explicit configuration, credential handling via environment variables, and loud failures on misconfiguration

The Bottom Line

SmolFS fills a real gap for developers building stateful agent workflows—it's the kind of infrastructure glue that usually requires cobbling together FUSE mounts, S3 sync scripts, and custom metadata handling. Worth evaluating if your agents need durable workspaces across ephemeral runtimes.