Programmable filesystems for Linux VMs and containers — define what the files are in code, and mount the result as an ordinary POSIX filesystem.
Most filesystems store bytes on a disk. MagicFS lets you describe a filesystem's contents in code — files that are generated on demand, backed by a git repo, a database, an HTTP API, or an AI agent's working context — and serves them to any Linux VM or container as a normal filesystem over FUSE, NFS, or virtio-fs. The programs reading it see plain files and directories and need no special client; you decide what those files are, and every access is observable.
If you've ever wanted "a filesystem, but the files come from my code," that's MagicFS. It's aimed at people building things like:
- AI-agent context as a filesystem — expose an agent's context, tools, or memory as files, and watch every read live as the agent works.
- A git repo mounted as a filesystem — browse or build any branch/revision without cloning; only the files you touch are ever materialized.
- Transparent change-tracking — wrap a real directory and record every access and write.
- Synthetic / dynamic filesystems — for sandboxes, CI, data pipelines, or anywhere a real directory is the wrong shape.
You write a provider — Express-style route handlers that describe directories and files. MagicFS runs it, caches the descriptions, and answers the kernel's filesystem calls, so a client mounts it like any other filesystem.
your provider (code) ──▶ MagicFS ──▶ FUSE · NFS · virtio-fs ──▶ your VM / container
describe files caches + the transport sees a normal
& directories serves of your choice POSIX filesystem
Install the SDK (@magicfs/sdk), write a provider, and mount it.
1. Describe a filesystem — provider.ts:
import { magicfs } from "@magicfs/sdk";
const fs = magicfs();
fs.dir("/", (ctx) =>
ctx.entries([{ name: "hello.txt", kind: "file", size: 12 }]),
);
fs.file("/hello.txt", (ctx) => ctx.bytes("hello world\n"));
await fs.serve();Handlers are Express-shaped: match a path, return what's there. Directories list entries; files return bytes (eagerly, lazily by range, or generated on the fly).
2. Mount it:
npx magicfs dev ./provider.ts --mount /tmp/mnt3. Use it like any filesystem:
$ ls /tmp/mnt
hello.txt
$ cat /tmp/mnt/hello.txt
hello worldThat's the local dev loop. In production the magicfsd daemon serves many
mounts at once over FUSE/NFS/virtio-fs with an HTTP control plane (tokens,
quotas, metrics, and a live access feed) — see the developer guide.
Mounting is Linux-only. On macOS or Windows, run the mount inside a Linux VM (Lima, OrbStack, WSL2, …); the SDK and providers develop natively.
One command boots the production daemon with two live mounts (NFS + FUSE), generated traffic, and the admin dashboard streaming it all in real time:
scripts/demo/up.sh # prints the dashboard URL + admin token
scripts/demo/down.sh # clean teardownSee scripts/demo/README.md for what it starts and
what it needs (on Linux: a Rust toolchain, node, /dev/fuse).
Early development — the core, all three transports, the provider SDK, and the control-plane daemon are working; APIs are still moving.
Building on MagicFS, or working inside a crate? Start with
docs/DEVELOPMENT.md — the workspace map, how to
build/run/test, the scripts/ci/ drill suite, and the milestone shorthand the
code comments are written in. The design itself, and the four hard problems it
is shaped around, is docs/ARCHITECTURE.md. Each
crate also has its own README.md.
Dual-licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
forks/nfsserve is a vendored, patched fork of
nfsserve and remains under its own
BSD-3-Clause license; see forks/nfsserve/PATCHES.md.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.