fs.mount() - Mesa Docs

mesa.fs.mount(...) is an async context manager that yields a MesaFileSystem. It mounts repositories at their canonical /<org>/<repo> paths. To mount them at paths you choose, call mesa.fs(layout=...) and mount the definition it returns.

import os
from mesa_sdk import Mesa

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

async with mesa.fs.mount(
    repos=["app"],
    authors=[{"name": "Mesa Bot", "email": "mesa-bot@example.com"}],
) as fs:
    data = await fs.read("/acme/app/README.md")
    print(data.decode())

Private-key clients sign a short-lived, repo-scoped token locally, while a client built from an access token forwards that token unchanged. Either way the mount keeps the token it started with for its whole lifetime; nothing refreshes it in the background.

Options

Sequence[str | RepoConfig]

required

Repositories to mount. Each entry can be a bare repo name such as app, a matching org/repo slug such as acme/app, or a RepoConfig for bookmark/change pinning and read-only control. The sequence must be non-empty.

list[SigningKeyAuthor] | None

Commit authors, in order, with at least one entry. Private-key mounts require this; access-token mounts reject it.

int | None

Lifetime of the mount, in seconds. Private-key mounts default to 900 and allow up to 14400. A client built from an access token cannot set ttl.

DiskCacheConfig | None

Optional on-disk cache. When omitted, the mount uses in-memory caching only.

RepoConfig

Open an existing revision, or fork a new named revision at mount time.

from mesa_sdk import RepoConfig

async with mesa.fs.mount(
    repos=[
        RepoConfig(
            name="app",
            mode="rw",
            branched_from={
                "bookmark": "main",
                "as": {"bookmark": "run-27", "describe": "initiate plan..."},
            },
        ),
        RepoConfig(
            name="docs",
            mode="ro",
            at={"bookmark": "main"},
        ),
    ],
    authors=[{"name": "Mesa Bot"}],
) as fs:
    ...

str

required

Repository name.

"rw" | "ro" | None

"rw" (default) or "ro". Read-only mounts cannot use branched_from.

dict | None

Existing revision to open: {"bookmark": str} or {"change_id": str}. Mutually exclusive with branched_from. When omitted, the repo default bookmark is used.

dict | None

Fork a new empty descendant from a parent tip and check it out. Optionally create as.bookmark and/or set as.describe. Omit as (or as.bookmark) for an anonymous tip. Requires mode="rw". Parent bookmark is not moved.

DiskCacheConfig

from mesa_sdk import DiskCacheConfig

cache = DiskCacheConfig(path="/tmp/mesa-cache", max_size_bytes=500_000_000)

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 filesystem paths include the organization and repository name:

/<org>/<repo>/README.md
/acme/app/src/main.py

Passing repos=["acme/app"] is accepted only when acme matches the resolved client organization. Cross-org mounts are rejected with InvalidOptionsError.

Layout definitions

Calling mesa.fs(layout=..., ttl=...) builds a LayoutDefinition: the prepared layout bundled with everything you can do with it. The call is synchronous, so the one-shot mount needs no extra await. A layout replaces the canonical browse tree entirely — the mount contains exactly the paths the layout declares. See Layouts for the layout format and its structural rules.

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", bookmark="main")},
    authors=[{"name": "Mesa Bot", "email": "mesa-bot@example.com"}],
).mount() as fs:
    await fs.readdir("/")  # ["workspace"]

Mapping[str, Repo | Sequence[Repo]]

required

Map of absolute mount path to one repo(...) declaration or a sequence of them. Built eagerly, so an invalid mapping raises at the mesa.fs(...) call.

int | None

Lifetime, in seconds, of every token the definition mints — through token() and under the hood in mount(). Same defaults and limits as fs.mount(...). Not accepted by access-token clients, whose token lifetime is already fixed.

list[SigningKeyAuthor] | None

Required for private-key clients, rejected for every other credential. Ordered commit attribution carried by the minted token.

Definition members

Layout

The prepared layout. str(definition.layout()) produces the JSON document mesa mount --layout reads.

async context manager -> MesaFileSystem

Mount the layout as the complete namespace. Accepts the non-token mount options; the mount’s token lifetime is the definition’s ttl.

async -> TokenCreateResult

Mint the layout-scoped, least-privilege access token: repositories collected from every declaration and scoped by name, ["read"] when every mode is "ro" and ["read", "write"] otherwise. Access-token clients cannot mint another token and raise InvalidOptionsError.

token() validates the layout structurally before minting, so an invalid layout fails there with the same error the mount would report. Repository names resolve only at mount time — a layout naming a nonexistent repository still mints a token and fails when the mount resolves it.

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", str(definition.layout()))
token = (await definition.token()).token

Response

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.mount(
    repos=["app"],
    authors=[{"name": "Mesa Bot"}],
) as fs:
    await fs.mkdir("/acme/app/src", recursive=True)
    await fs.write("/acme/app/src/main.py", b"print('hello')\n")
    data = await fs.read("/acme/app/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 /acme/app/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 namespace	Reference
`fs.bash(...)`	fs.bash()
`fs.changes`	fs.changes
`fs.bookmarks`	fs.bookmarks
`fs.subscribe(...)`	Advanced Realtime

Errors

Raises InvalidOptionsError for an empty repo list, a private-key ttl outside 1..14400, missing or rejected authors, invalid mode, or a mismatched org prefix. 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")

​Options

​RepoConfig

​DiskCacheConfig

​Paths

​Layout definitions

​Definition members

​Response

​MesaFileSystem

​Byte I/O

​Metadata and traversal

​Mutations

​Subscriptions

​FsStat

​Related filesystem methods

​Errors

​Multiprocessing

Options

RepoConfig

DiskCacheConfig

Paths

Layout definitions

Definition members

Response

MesaFileSystem

Byte I/O

Metadata and traversal

Mutations

Subscriptions

FsStat

Related filesystem methods

Errors

Multiprocessing