Show HN: A durable filesystem layer for AI agents

SmolFS gives agents a workspace folder that can survive after the agent process stops. You mount it like a normal directory, write files into it, unmount it when the job is done, and mount it again later from another process.

SmolFS owns the developer experience around creating volumes, checking the machine, mounting, flushing, unmounting, and inspecting status. The storage backend is installed and managed for you.

| Agents can keep files across short-lived runtimes without each runtime managing storage setup directly. | Use | | Use Redis plus S3-compatible object storage when the same workspace needs to outlive one machine. | Run | | Python and TypeScript bindings call the same Rust core so agent tools can use SmolFS without shelling out. | Cloud metadata, buckets, and credentials stay explicit so durable agent data is easier to audit. |

Keep agent work across turns. Mount the same workspace again after an agent process exits.Share a workspace across runtimes. Put metadata in Redis and file contents in S3-compatible storage.Test locally before using cloud storage. Start with--dev

, then switch to explicit metadata and object storage settings.Wrap storage in agent tooling. Use the Python or TypeScript SDK from an agent runner instead of teaching every agent process about storage internals.

Install SmolFS:

curl -fsSL https://raw.githubusercontent.com/CelestoAI/smolfs/main/scripts/install.sh | sh

The installer downloads the latest CLI release asset for your platform and installs SmolFS' managed storage backend. If no release asset exists yet, use the source checkout flow in Development. Set SMOLFS_INSTALL_BACKEND=0

if you only want to install the CLI. Set SMOLFS_VERSION=dev

to try the latest successful build from main

; tagged v*

releases remain the stable channel.

Check the machine and try a local volume:

smolfs doctor
smolfs init demo --dev
smolfs mount demo ./workspace
echo hello > ./workspace/hello.txt
smolfs flush demo
smolfs unmount demo
smolfs mount demo ./workspace
cat ./workspace/hello.txt

SmolFS needs local mount support on the machine that mounts volumes. Mount support lets SmolFS provide a folder your tools can read and write.

Install the Python SDK with the CLI #

curl -fsSL https://raw.githubusercontent.com/CelestoAI/smolfs/main/scripts/install.sh | SMOLFS_INSTALL_PYTHON=1 sh

The installer runs uv add smolfs

from a directory with pyproject.toml

, or uv pip install smolfs

inside an active virtualenv. Set SMOLFS_PYTHON_MODE=user

to use uv pip install --user smolfs

.

The normal SmolFS flow is: check the machine, create a volume, mount it, use the directory, flush important writes, unmount it, and mount it again when you need the same files later.

Run doctor

before creating or mounting volumes:

smolfs doctor

doctor

checks whether SmolFS has its managed storage backend and whether the machine can mount local directories.

Useful options:

smolfs doctor --install

installs SmolFS' managed storage backend.smolfs doctor --json

prints the same report as JSON for scripts.

SmolFS looks for its home directory in SMOLFS_HOME

. If it is not set, SmolFS uses ~/.smolfs

. The home directory stores SmolFS config, volume records, logs, managed binaries, and local dev-volume data.

A volume is the named workspace that SmolFS can mount later.

smolfs init demo --dev

--dev

creates a local-only volume. It uses SQLite for metadata and local files for object data under the SmolFS home directory. This is the simplest path for trying SmolFS on one machine.

Cloud volumes need explicit metadata and object storage settings. Metadata stores the file tree. Object storage is where file contents live.

smolfs init agent-workspace \
  --metadata redis://localhost:6379/1 \
  --storage s3 \
  --bucket https://my-bucket.s3.us-east-2.amazonaws.com

You can pass object storage in either of these forms:

--store s3://bucket/prefix

,--store gs://bucket/prefix

, or--store file:///path/to/objects

.--storage TYPE --bucket BUCKET

, which is useful for S3-compatible services that expect an endpoint-style bucket URL.

For Cloudflare R2 or another S3-compatible service, keep credentials in the environment used by SmolFS. Do not put access keys in command arguments or logs.

set -a
. ./.env
set +a

export SMOLFS_HOME=/tmp/smolfs-r2-home
VOL="r2demo-$(date +%Y%m%d%H%M%S)"

smolfs init "$VOL" \
  --metadata "$SMOLFS_R2_METADATA" \
  --storage s3 \
  --bucket "$SMOLFS_R2_BUCKET_URL"

Mounting makes the volume appear as a normal local directory:

smolfs mount demo ./workspace
echo hello > ./workspace/hello.txt
cat ./workspace/hello.txt

SmolFS creates the mount directory if it does not exist. After the mount succeeds, programs can read and write files through that directory.

Useful options:

--check-storage

asks SmolFS to test object storage access before the mount completes.--foreground

runs the mount process in the foreground instead of starting it in the background.

Run flush

when you want a best-effort check that recent writes have reached the mounted filesystem:

smolfs flush demo

Run status

to see known volumes:

smolfs status
smolfs status demo
smolfs status --json

Unmount when the job is done:

smolfs unmount demo

unmount

asks SmolFS to flush before detaching the mountpoint. Use smolfs umount demo

if you prefer the shorter alias. Add --force

when the mountpoint is busy and you want SmolFS to force the unmount.

After unmounting, you can mount the same volume again and read the files:

smolfs mount demo ./workspace
cat ./workspace/hello.txt

Command	What it does
smolfs doctor
Checks SmolFS storage, local mount support, and configuration.
smolfs init NAME --dev
Creates a local development volume.
smolfs init NAME --metadata URL --storage TYPE --bucket BUCKET
Creates a cloud volume with explicit metadata and object storage.
smolfs mount NAME PATH
Mounts a volume at a local directory.
smolfs flush NAME
Probes the mounted volume and syncs a small file through it.
smolfs status [NAME]
Shows known volumes and current mountpoints.
smolfs unmount NAME
Unmounts a mounted volume and asks SmolFS to flush.
smolfs umount NAME
Alias for smolfs unmount NAME .

Every command has its own help page:

smolfs help
smolfs init --help

The Python package is SDK-only. Install it with uv

:

uv add smolfs

For local development from this checkout:

uv run --isolated --with-editable ./bindings/python python -c "from smolfs import doctor; print(doctor())"

Use the SDK from any Python agent runner:

from pathlib import Path

from smolfs import SmolFS, doctor

report = doctor()
if not report["storage_backend"]["found"] or not report["mount_support"]["found"]:
    raise RuntimeError(f"SmolFS is not ready: {report}")

fs = SmolFS.from_env()
volume = fs.ensure_volume("demo", dev=True)
mount = fs.mount(volume.name, "./workspace")

workspace = Path(mount.mountpoint)
(workspace / "hello.txt").write_text("hello from SmolFS\n")

try:
    fs.flush(volume.name)
finally:
    fs.unmount(volume.name)

Cloud volumes use the same API with explicit metadata and object storage:

fs.ensure_volume(
    "agent-workspace",
    metadata="redis://localhost:6379/1",
    storage="s3",
    bucket="https://my-bucket.s3.us-east-2.amazonaws.com",
)

For S3-compatible services such as MinIO or Cloudflare R2, pass the service bucket URL and provide ACCESS_KEY

and SECRET_KEY

in the environment used by SmolFS.

The TypeScript package is a native Node.js binding over the same Rust core. The npm package ships prebuilt native bindings for Linux and macOS on x86_64 and arm64.

Install it with npm:

npm install @celestoai/smolfs

For local development from this checkout, use Node.js 18 or newer:

cd bindings/node
npm ci
npm run build:debug
npm test

Use the SDK from a Node.js agent runner:

import { SmolFS, doctor } from "@celestoai/smolfs";
import { writeFile } from "node:fs/promises";
import { join } from "node:path";

const report = doctor();
if (!report.storageBackend.found || !report.mountSupport.found) {
  throw new Error(`SmolFS is not ready: ${JSON.stringify(report)}`);
}

const fs = SmolFS.fromEnv();
const volume = fs.ensureVolume({ name: "demo", dev: true });
const mount = fs.mount({ name: volume.name, path: "./workspace" });

try {
  await writeFile(join(mount.mountpoint, "hello.txt"), "hello from SmolFS\n");
  fs.flush(volume.name);
} finally {
  fs.unmount(volume.name);
}

Cloud volumes use the same options object:

fs.ensureVolume({
  name: "agent-workspace",
  metadata: "redis://localhost:6379/1",
  storage: "s3",
  bucket: "https://my-bucket.s3.us-east-2.amazonaws.com"
});

Work from a source checkout when you are changing SmolFS itself or when a CLI release asset has not been published yet.

Build and check the CLI:

cargo build -p smolfs-cli
./target/debug/smolfs doctor

Run the normal quality checks:

cargo fmt --all -- --check
cargo clippy --workspace -- -D warnings
cargo test --workspace

Run the R2-style lifecycle from this checkout:

cargo build -p smolfs-cli

set -a
. ./.env
set +a

export SMOLFS_HOME=/tmp/smolfs-r2-home
VOL="r2demo-$(date +%Y%m%d%H%M%S)"
MOUNT="/tmp/smolfs-r2-workspace"

./target/debug/smolfs init "$VOL" \
  --metadata "$SMOLFS_R2_METADATA" \
  --storage s3 \
  --bucket "$SMOLFS_R2_BUCKET_URL"

./target/debug/smolfs mount "$VOL" "$MOUNT"
echo "hello from smolfs r2" > "$MOUNT/hello.txt"
./target/debug/smolfs flush "$VOL"
./target/debug/smolfs unmount "$VOL"
./target/debug/smolfs mount "$VOL" "$MOUNT"
cat "$MOUNT/hello.txt"

Run the MinIO integration test path when the SmolFS storage backend, Redis, and a MinIO bucket are available:

SMOLFS_RUN_INTEGRATION=1 cargo test --workspace -- --nocapture

Build the Python wheel:

uvx maturin build --manifest-path bindings/python/Cargo.toml --interpreter python

Develop the Python binding locally:

uvx maturin develop --manifest-path bindings/python/Cargo.toml

Test the TypeScript SDK:

cd bindings/node
npm ci
npm test

SmolFS stores agent workspace data outside the sandbox lifecycle. Treat it like durable infrastructure.

• Do not log credentials, S3 access keys, Redis URLs with secrets, or mount tokens.
• Prefer explicit object-store configuration over hidden global state.
• Make mount and unmount behavior idempotent where possible.
• Fail loudly on missing storage backend, missing metadata URLs, missing object-store config, or missing local mount support.
• Avoid changes that weaken persistence guarantees without calling them out.

The smolfs

command is built from the Rust CLI crate. The GitHub workflow at .github/workflows/publish-cli.yml

builds Linux and macOS release binaries for x86_64 and arm64 targets, smoke-tests smolfs --help

, and attaches tarballs to v*

GitHub releases. Pushes to main

publish a rolling dev

prerelease after deleting the previous dev

release and tag, so the dev channel only exposes the latest successful main build.

Python packaging uses uv

and maturin

. The GitHub workflow at .github/workflows/publish-python.yml

builds wheels for Linux and macOS, builds an sdist, and publishes to PyPI when a v*

tag is pushed.

Node.js packaging uses npm

and napi-rs

. The GitHub workflow at .github/workflows/publish-node.yml

builds native TypeScript SDK bindings for Linux and macOS, checks the npm package contents, and publishes to npm when a v*

tag is pushed.

Before the first Python release, configure PyPI Trusted Publishing:

• Create or claim the smolfs

project on PyPI. - Add a trusted publisher for repository CelestoAI/smolfs

. - Set the workflow name to publish-python.yml

. - Set the environment name to pypi

.

Before the first npm release, configure npm trusted publishing for @celestoai/smolfs

:

• Add a trusted publisher for GitHub Actions.
• Set the organization or user to CelestoAI

. - Set the repository to smolfs

. - Set the workflow filename to publish-node.yml

. - Set the environment name to npm

. - Allow npm publish

.

Release:

git tag v0.1.0
git push origin v0.1.0

• Add type stubs for the Python package.
• Add a Linux CI job that mounts a local dev volume when mount support is available.
• Add release notes and a changelog before the first non-draft release.

Apache 2.0.

Celesto AI

source & further reading

github.com — original article