monkeyfs 🐒

Filesystem interception via monkey-patching.

Patches open(), os.listdir(), os.stat(), and 30+ other stdlib functions to route through a virtual or isolated filesystem. Patches are applied lazily on first patch() call and are inert outside the context. Uses contextvars for async-safe isolation between concurrent tasks. Zero dependencies.

Install

pip install monkeyfs

Quick example

from monkeyfs import VirtualFS, patch

vfs = VirtualFS({})

with patch(vfs):
    with open("data.csv", "w") as f:
        f.write("name,score\nalice,98\nbob,87\n")

    import os
    print(os.listdir("/"))        # ['data.csv']
    print(os.path.getsize("data.csv"))  # 30

    with open("data.csv") as f:
        print(f.read())           # name,score\nalice,98\nbob,87\n

Not a security boundary

monkeyfs is a cooperative routing layer, not a sandbox. It rebinds stdlib functions so that Python code asking for a file gets the one the active filesystem holds -- and that is the whole of it. Only Python-level file operations are intercepted: ctypes, subprocess, socket, mmap, sqlite3 and any C extension talk to the OS directly and reach the host filesystem untouched. monkeyfs.suspend() is an ordinary importable that turns the routing off from inside a patched block.

So the PermissionError -- outside root below is a routing decision, not a wall -- useful for keeping cooperative code inside its lane, and worth nothing against code that is trying to leave. Confining untrusted code is the job of whatever controls the import surface around it -- sandtrap in this stack -- or of an OS-level boundary such as a container or a VM. monkeyfs is what those hand the confined code to read and write; it is not what keeps the code confined.

IsolatedFS

Restricts file operations to a root directory on the real filesystem:

from monkeyfs import IsolatedFS, patch

isolated = IsolatedFS(root="/tmp/sandbox")

with patch(isolated):
    with open("notes.txt", "w") as f:
        f.write("hello")          # Written to /tmp/sandbox/notes.txt

    open("/etc/passwd")           # PermissionError -- outside root

ReadOnlyFS

Wraps any filesystem and blocks all write operations:

from monkeyfs import VirtualFS, ReadOnlyFS, patch

vfs = VirtualFS({})
vfs.write("data.csv", b"a,b,c")

ro = ReadOnlyFS(vfs)
with patch(ro):
    print(open("data.csv").read())  # a,b,c
    open("new.txt", "w")           # PermissionError

MountFS

Routes operations to different filesystems by path prefix:

from monkeyfs import VirtualFS, MountFS, ReadOnlyFS, patch

base = VirtualFS({})
overlay = VirtualFS({})
overlay.write("summary.md", b"# Chapter 1")

fs = MountFS(base, {"/chapters": ReadOnlyFS(overlay)})

with patch(fs):
    # Writes go to base
    with open("app.py", "w") as f:
        f.write("print('hi')")

    # Reads from /chapters go to the overlay
    print(open("/chapters/summary.md").read())  # # Chapter 1

    # Writes to /chapters are blocked (read-only)
    open("/chapters/new.md", "w")  # PermissionError

The backend protocol

A backend is any object with the right methods -- no inheritance, no base class. monkeyfs's backend protocol and termish's FileSystem protocol are the same sixteen methods with the same signatures, including the ranged read(path, offset=0, size=-1). open() is what monkeyfs provides over a backend rather than something it asks for -- a file object synthesized from read, write and stat, lazy in binary read modes -- and a backend that has a better one (a real directory, where fileno() and mmap work) may offer its own, which monkeyfs prefers. The agreement between the two libraries is a convention enforced by tests in both, not a shared import: a third package would cost both of them their zero-dependency line for twenty lines of protocol.

So a filesystem written for either library works under the other, and under monkeyfs it is a Python open() for free. The conformance kit says whether yours is one:

from monkeyfs import check_filesystem

check_filesystem(MyFileSystem())   # an empty one; it writes and cleans up

It raises AssertionError naming the method and what was expected of it -- including the ranged-read cases a backend that accepts offset and size and quietly ignores them would otherwise pass.

Part of the agex stack

monkeyfs provides filesystem interception for sandtrap and agex, giving sandboxed agent code an isolated virtual filesystem. VirtualFS accepts any dict-like backing store -- including a kvgit worktree for a versioned filesystem with commit/rollback. A store that offers get_many(*keys), as kvgit worktrees do, has its metadata read in one batched call rather than one per file.

Documentation

• API Reference -- public API, FileSystem protocol, patched functions

Development

uv sync --extra dev
uv run pytest

License

MIT