Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mesa.dev/llms.txt

Use this file to discover all available pages before exploring further.

mesa.fs.mount(...) is an async context manager that yields a MesaFileSystem. 
from mesa_sdk import Mesa

mesa = Mesa(org="acme")

async with mesa.fs.mount(repos=["app"]) as fs:
    data = await fs.read("/acme/app/README.md")
    print(data.decode())
Under the hood, mount() mints a scoped API key for the mounted repos, connects to the VCS backend, and revokes the key when the context exits. The scoped key also has a one-hour server-side TTL.

​
Options

​
repos
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. The sequence must be non-empty.
​
mode
'ro' | 'rw'
Access mode. Defaults to rw. Read-only mounts mint a read scoped key and reject write operations with PermissionError.
​
disk_cache
DiskCacheConfig | None
Optional on-disk cache. When omitted, the mount uses in-memory caching only.

​
RepoConfig

Pin a repository to a bookmark or change at mount time. 
from mesa_sdk import RepoConfig

async with mesa.fs.mount(
    repos=[
        RepoConfig(name="app", bookmark="main"),
        RepoConfig(name="docs", change_id="zyxwvutsrqponmlkzyxwvutsrqponmlk"),
    ]
) as fs:
    ...
​
RepoConfig.name
str
required
Repository name.
​
RepoConfig.bookmark
str | None
Bookmark to check out.
​
RepoConfig.change_id
str | None
Change ID to check out.

​
DiskCacheConfig

from mesa_sdk import DiskCacheConfig

cache = DiskCacheConfig(path="/tmp/mesa-cache", max_size_bytes=500_000_000)
​
DiskCacheConfig.path
str
required
Directory for the on-disk cache.
​
DiskCacheConfig.max_size_bytes
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.

​
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"]) 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

​
read(path)
async -> bytes
Read a file as bytes.
​
write(path, content)
async -> None
Replace file contents, creating the file if missing. Parent directories must already exist.
​
append(path, content)
async -> None
Append bytes to a file, creating it if missing.
​
exists(path)
async -> bool
Return whether a path exists. Follows symlinks.

​
Metadata and traversal

​
stat(path)
async -> FsStat
Return metadata for a path, following symlinks.
​
lstat(path)
async -> FsStat
Return metadata for a path without following symlinks.
​
readdir(path)
async -> list[str]
Return entry names in a directory. Sort client-side if you need deterministic ordering.
​
realpath(path)
async -> str
Resolve symlinks and .. segments to a canonical path.
​
readlink(path)
async -> str
Return the target of a symlink.
​
resolve_path(base, path)
str
Join and normalize a path against a base path without touching the filesystem.

​
Mutations

​
mkdir(path, recursive=None)
async -> None
Create a directory. With recursive=True, create missing parents and do nothing when the path already exists as a directory.
​
rm(path, recursive=None, force=None)
async -> None
Remove a file or directory. Use recursive=True for non-empty directories and force=True to ignore missing paths.
​
cp(src, dest, recursive=None)
async -> None
Copy a file or directory. Use recursive=True for directories.
​
mv(src, dest)
async -> None
Move or rename a file or directory.
​
chmod(path, mode)
async -> None
Set permission bits, such as 0o755.
​
symlink(target, link)
async -> None
Create a symlink. Relative targets are stored verbatim and resolve against the parent of link at read time.
​
utimes(path, atime_ms, mtime_ms)
async -> None
Set access and modification times. Values are milliseconds since the Unix epoch, not seconds.
​
link(existing, new)
None
Hard links are not supported and this method raises NotImplementedError.

​
FsStat

stat(...) and lstat(...) return FsStat.
​
is_file
bool
Whether the path is a regular file.
​
is_directory
bool
Whether the path is a directory.
​
is_symbolic_link
bool
Whether the path is a symlink. This is False from stat(...) when the target exists because stat follows symlinks.
​
mode
int
POSIX mode bits.
​
size
int
Size in bytes.
​
mtime_ms
float
Modification time in milliseconds since the Unix epoch.
Method namespaceReference
fs.bash(...)fs.bash()
fs.changesfs.changes
fs.bookmarksfs.bookmarks

​
Errors

Raises InvalidOptionsError for an empty repo list, invalid mode, or a mismatched org prefix. API key minting, repo lookup, 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")