mesa.fs() - Mesa Docs

mesa.fs(layout=..., ttl=..., authors=...) builds a FilesystemDefinition: a raw Layout, its authors, and its token lifetime, bundled with layout(), mount(), and token(). Calling .mount() is an async context manager that yields a MesaFileSystem.

import os
from mesa_sdk import Mesa, repo

mesa = Mesa(private_key=os.environ["MESA_PRIVATE_KEY"])

async with mesa.fs(
    layout={"/workspace": repo("app", mode="rw", at={"bookmark": "main"})},
    authors=[{"name": "Mesa Bot", "email": "mesa-bot@example.com"}],
).mount() as fs:
    data = await fs.read("/workspace/README.md")
    print(data.decode())

Map repos.list() results into layout declarations when the repository set is dynamic:

result = await mesa.repos.list(
    tags={"$and": [{"environment": "prod"}, {"workload": {"$in": ["sync", "index"]}}]}
)

async with mesa.fs(
    layout={"/skills": [repo(r.name, mode="ro") for r in result.repos]},
    authors=[{"name": "Mesa Bot", "email": "mesa-bot@example.com"}],
).mount() as fs:
    ...

The private-key client signs a short-lived, layout-scoped token locally for the mount. The mount keeps that token for its whole lifetime; nothing refreshes it in the background. See Layouts for nesting, structural rules, and running a layout mount in a sandbox.

`mesa.fs(...)`

Synchronous. Builds the definition eagerly so invalid layouts raise at this call.

Layout

required

Map of absolute mount paths (/-prefixed) to one layout child. The mount contains exactly this visible path tree.

int | None

Lifetime, in seconds, of every token the definition mints, through token() and under the hood in mount(). Defaults to 900 and allows up to 14400.

list[Author]

required

Commit authors, in order, with at least one entry.

Definition members

Layout

An independent plain-dict snapshot of the validated layout. Pass it to json.dumps(...) to produce the document mesa mount --layout reads.

async context manager -> MesaFileSystem

Mount the layout as the complete visible path tree. Accepts only runtime options (disk_cache). The mount’s token lifetime is the definition’s ttl.

async -> AccessToken

Mint the layout-scoped, least-privilege access token. Each repository receives read only access for mode="ro" or read and write access for mode="rw".

mesa.fs(...) validates the layout structurally before returning the definition. Repository names resolve only at mount time — a layout naming a nonexistent repository still produces a definition and token, then fails when the mount resolves it.

import json
from mesa_sdk import repo

definition = mesa.fs(
    layout={"/workspace": repo("app", mode="rw")},
    authors=[{"name": "Mesa Bot", "email": "mesa-bot@example.com"}],
    ttl=3600,
)

sandbox.write_file("layout.json", json.dumps(definition.layout(), indent=2))
token = (await definition.token()).token

`repo(selector, *, mode, ...)`

Declare one repository in a layout. Do not construct Repo mappings by hand.

repo("app", mode="rw", at={"bookmark": "main"})
repo({"name": "app"}, mode="ro", at={"change_id": "zyxwvutsrqponmlkzyxwvutsrqponmlk"})
repo(
    "app",
    mode="rw",
    branched_from={
        "bookmark": "main",
        "as": {"bookmark": "run-27", "describe": "initiate plan..."},
    },
)

str | RepoName

required

Repository name within the client’s organization, as a string or {"name": "..."}.

"rw" | "ro"

required

Access mode. Always required — there is no default. "ro" rejects writes with EROFS.

Mapping[str, object] | None

Pin an existing revision: {"bookmark": ...} or {"change_id": ...}. Mutually exclusive with branched_from. When neither at nor branched_from is set, the repository’s default bookmark is used.

Mapping[str, object] | None

Fork a new empty descendant from a parent tip at cold open and check it out. Requires mode="rw". Shape: {"bookmark"|"change_id": ..., "as": {"bookmark"?: str, "describe"?: str}}. Omit as (or as.bookmark) for an anonymous tip. Parent bookmark is not moved. Mutually exclusive with at.

str | None

Directory-name override. Only valid when the declaration is an element of a sequence value in the layout.

Mapping[str, Repo | Sequence[Repo]] | None

Nested repository mounts declared beneath this repository’s mount path. Keys are relative paths.

Runtime mount options

Non-token options accepted by definition.mount(...).

DiskCacheConfig

from mesa_sdk import DiskCacheConfig

async with mesa.fs(
    layout={"/workspace": repo("app", mode="rw")},
    authors=[{"name": "Mesa Bot"}],
).mount(
    disk_cache=DiskCacheConfig(path="/tmp/mesa-cache", max_size_bytes=500_000_000),
) as fs:
    ...

str

required

Directory for the on-disk cache.

int | None

Optional cache size cap. When omitted, the native extension auto-sizes the budget against system resources.

Paths

Mounted paths are whatever the layout declares:

/workspace/README.md
/workspace/src/main.py
/skills/code-review/SKILL.md

Response

definition.mount() yields a MesaFileSystem.

MesaFileSystem

The yielded fs object exposes async file I/O, metadata, traversal, mutation, Bash, and mounted-repo version-control helpers.

async with mesa.fs(
    layout={"/workspace": repo("app", mode="rw")},
    authors=[{"name": "Mesa Bot"}],
).mount() as fs:
    await fs.mkdir("/workspace/src", recursive=True)
    await fs.write("/workspace/src/main.py", b"print('hello')\n")
    data = await fs.read("/workspace/src/main.py")

Byte I/O

async -> bytes

Read a file as bytes.

async -> None

Replace file contents, creating the file if missing. Parent directories must already exist.

async -> None

Append bytes to a file, creating it if missing.

async -> bool

Return whether a path exists. Follows symlinks.

Metadata and traversal

async -> FsStat

Return metadata for a path, following symlinks.

async -> FsStat

Return metadata for a path without following symlinks.

async -> list[str]

Return entry names in a directory. Sort client-side if you need deterministic ordering.

async -> str

Resolve symlinks and .. segments to a canonical path.

async -> str

Return the target of a symlink.

str

Join and normalize a path against a base path without touching the filesystem.

Mutations

async -> None

Create a directory. With recursive=True, create missing parents and do nothing when the path already exists as a directory.

async -> None

Remove a file or directory. Use recursive=True for non-empty directories and force=True to ignore missing paths.

async -> None

Copy a file or directory. Use recursive=True for directories.

async -> None

Move or rename a file or directory.

async -> None

Set permission bits, such as 0o755.

async -> None

Create a symlink. Relative targets are stored verbatim and resolve against the parent of link at read time.

async -> None

Set access and modification times. Values are milliseconds since the Unix epoch, not seconds.

None

Hard links are not supported and this method raises NotImplementedError.

Subscriptions

MesaFS reads and writes are realtime by default. Use subscriptions only when your process needs an event stream that identifies which paths changed, such as to refetch data and rerender a frontend.

Subscribe to filesystem invalidation events. The handler is called after the changed state is visible through this filesystem instance.

async def on_change(event):
    if not event.recursive:
        content = await fs.read(event.path)
        print(event.path, content.decode())

subscription = fs.subscribe(on_change)
await subscription.unsubscribe()

Callable[[WatchEvent], None | Awaitable[None]]

Callback invoked for each filesystem invalidation.

str

Absolute MesaFS path that changed, such as /workspace/src/index.py.

bool

Whether descendants of path may have changed. Refresh any cached directory or subtree state below path when this is True.

async -> None

Stop receiving events and close the underlying watcher.

FsStat

stat(...) and lstat(...) return FsStat.

bool

Whether the path is a regular file.

bool

Whether the path is a directory.

bool

Whether the path is a symlink. This is False from stat(...) when the target exists because stat follows symlinks.

int

POSIX mode bits.

int

Size in bytes.

float

Modification time in milliseconds since the Unix epoch.

Method	Reference
`fs.bash(...)`	fs.bash()
`fs.changes`	fs.changes
`fs.bookmarks`	fs.bookmarks
`fs.subscribe(...)`	Advanced Realtime

Errors

Raises InvalidOptionsError for a missing or empty layout, a ttl outside 1..14400, missing or rejected authors, or invalid mode. A layout that breaks the structural rules raises at the mesa.fs(...) call rather than at mount. Token signing or VCS connection failures can raise ApiError subclasses or connection errors.

Multiprocessing

MesaFS is not fork-safe. If you use multiprocessing, set the start method to spawn or forkserver before creating Mesa objects.

import multiprocessing

multiprocessing.set_start_method("spawn")

​mesa.fs(...)

​Definition members

​repo(selector, *, mode, ...)

​Runtime mount options

​DiskCacheConfig

​Paths

​Response

​MesaFileSystem

​Byte I/O

​Metadata and traversal

​Mutations

​Subscriptions

​FsStat

​Related filesystem methods

​Errors

​Multiprocessing

`mesa.fs(...)`

Definition members

`repo(selector, *, mode, ...)`

Runtime mount options

DiskCacheConfig

Paths

Response

MesaFileSystem

Byte I/O

Metadata and traversal

Mutations

Subscriptions

FsStat

Related filesystem methods

Errors

Multiprocessing