Skip to main content
mesa.fs.mount(...) returns a MesaFileSystem backed by Mesa’s native filesystem implementation. 
import { Buffer } from 'node:buffer';
import { Mesa } from '@mesadev/sdk';

const mesa = new Mesa({ org: 'acme' });
const fs = await mesa.fs.mount({ repos: [{ name: 'app' }] });

const data = await fs.readFileBuffer('/acme/app/README.md');
console.log(Buffer.from(data).toString('utf8'));
Under the hood, mount() signs a single short-lived, repo-scoped access token (JWT) locally from your API key and connects to the VCS backend. The token’s repo scope is encoded as full org/repo names, so signing does not resolve repository ids over the network. The mount uses that one token for its whole lifetime: there is no background refresh and no credential hot-swap, so once the token expires the mount stops authenticating. Choose a ttl that covers the mount’s work. No server-side credential is created or revoked.

​
Options

​
repos
RepoConfig[]
required
Repositories to mount. The array must be non-empty.
​
ttl
number | undefined
Lifetime of the mount, in seconds. The mount mints one access token with this TTL and uses it until it expires; there is no refresh. Defaults to 3600 (1 hour). Maximum 86400 (24 hours). A value outside 1..86400 throws InvalidOptionsError.
​
cache.diskCache
{ path: string; maxSizeBytes?: number } | undefined
Optional on-disk cache. When omitted, the mount uses in-memory caching only.
​
telemetry.logLevel
'error' | 'warn' | 'info' | 'debug' | undefined
Minimum native log level. Defaults to warn.
​
telemetry.onLog
(record: LogRecord) => void | undefined
Per-instance structured log callback from the native filesystem.

​
RepoConfig

Pin a repository to a bookmark or change at mount time. 
const fs = await mesa.fs.mount({
  repos: [
    { name: 'app', bookmark: 'main' },
    { name: 'docs', changeId: 'zyxwvutsrqponmlkzyxwvutsrqponmlk' },
  ],
});
​
RepoConfig.name
string
required
Repository name.
​
RepoConfig.bookmark
string | undefined
Bookmark to check out. Mutually exclusive with changeId.
​
RepoConfig.changeId
string | undefined
Change ID to check out. Mutually exclusive with bookmark.
​
RepoConfig.readOnly
boolean | undefined
When true, the mesa daemon rejects writes to this repo with EROFS, so a single mount can mix writable and read-only repos.

​
Disk cache

const fs = await mesa.fs.mount({
  repos: [{ name: 'app' }],
  cache: { diskCache: { path: '/tmp/mesa-cache', maxSizeBytes: 500_000_000 } },
});
​
cache.diskCache.path
string
required
Directory for the on-disk cache.
​
cache.diskCache.maxSizeBytes
number | undefined
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.ts

​
Response

Returns a Promise<MesaFileSystem>.

​
MesaFileSystem

The returned fs object implements the just-bash filesystem interface and exposes async file I/O, metadata, traversal, mutation, Bash, and mounted-repo version-control helpers. 
await fs.mkdir('/acme/app/src', { recursive: true });
await fs.writeFile('/acme/app/src/main.ts', 'console.log("hello")\n');
const data = await fs.readFile('/acme/app/src/main.ts', 'utf8');

​
Byte and text I/O

​
readFile(path, options?)
Promise<string>
Read a file as text using a Node-compatible encoding. The binary encoding follows the just-bash latin1 byte-string convention.
​
readFileBuffer(path)
Promise<Uint8Array>
Read raw file bytes.
​
writeFile(path, content, options?)
Promise<void>
Replace file contents, creating the file if missing. Parent directories must already exist.
​
appendFile(path, content, options?)
Promise<void>
Append text or bytes to a file, creating it if missing.
​
exists(path)
Promise<boolean>
Return whether a path exists. Follows symlinks.

​
Metadata and traversal

​
stat(path)
Promise<FsStat>
Return metadata for a path, following symlinks. mtime is a JavaScript Date.
​
lstat(path)
Promise<FsStat>
Return metadata for a path without following symlinks. mtime is a JavaScript Date.
​
readdir(path)
Promise<string[]>
Return entry names in a directory. Sort client-side if you need deterministic ordering.
​
readdirWithFileTypes(path)
Promise<Array<{ name: string; isFile: boolean; isDirectory: boolean; isSymbolicLink: boolean }>>
Return entry names with file type flags.
​
realpath(path)
Promise<string>
Resolve symlinks and .. segments to a canonical path.
​
readlink(path)
Promise<string>
Return the target of a symlink.
​
resolvePath(base, path)
string
Join and normalize a path against a base path without touching the filesystem.
​
getAllPaths()
string[]
Return a synchronous snapshot of paths known to the filesystem.

​
Mutations

​
mkdir(path, options?)
Promise<void>
Create a directory. With { recursive: true }, create missing parents and do nothing when the path already exists as a directory.
​
rm(path, options?)
Promise<void>
Remove a file or directory. Use { recursive: true } for non-empty directories and { force: true } to ignore missing paths.
​
cp(src, dest, options?)
Promise<void>
Copy a file or directory. Use { recursive: true } for directories.
​
mv(src, dest)
Promise<void>
Move or rename a file or directory.
​
chmod(path, mode)
Promise<void>
Set permission bits, such as 0o755.
​
symlink(target, linkPath)
Promise<void>
Create a symlink. Relative targets are stored verbatim and resolve against the parent of linkPath at read time.
​
utimes(path, atime, mtime)
Promise<void>
Set access and modification times with JavaScript Date values.
​
link(existingPath, newPath)
Promise<void>
Create a hard link if supported by the native filesystem implementation.

​
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(handler)
MesaFileSystemSubscription
Subscribe to filesystem invalidation events. The handler is called after the changed state is visible through this filesystem instance.
const subscription = fs.subscribe(async (event) => {
  if (!event.recursive) {
    const content = await fs.readFile(event.path, 'utf8');
    console.log(event.path, content);
  }
});

subscription.unsubscribe();
​
handler
(event: WatchEvent) => void | Promise<void>
Callback invoked for each filesystem invalidation.
​
WatchEvent.path
string
Absolute MesaFS path that changed, such as /acme/app/src/index.ts.
​
WatchEvent.recursive
boolean
Whether descendants of path may have changed. Refresh any cached directory or subtree state below path when this is true.
​
MesaFileSystemSubscription.unsubscribe()
void
Stop receiving events and close the underlying watcher.

​
FsStat

stat(...) and lstat(...) return FsStat.
​
isFile
boolean
Whether the path is a regular file.
​
isDirectory
boolean
Whether the path is a directory.
​
isSymbolicLink
boolean
Whether the path is a symlink. This is false from stat(...) when the target exists because stat follows symlinks.
​
mode
number
POSIX mode bits.
​
size
number
Size in bytes.
​
mtime
Date
Modification time.
Method namespaceReference
fs.bash(...)fs.bash()
fs.changefs.change
fs.bookmarkfs.bookmark
fs.subscribe(...)Advanced Realtime

​
Errors

Throws InvalidOptionsError for an empty repo list or a ttl outside 1..86400. Token signing or VCS connection failures can throw API errors or connection errors.