Mesa

Stores workspace files in Mesa repos through the standard Mastra WorkspaceFilesystem interface.

Use MesaFilesystem when agents need versioned file storage. For a local directory, use LocalFilesystem. For object storage, use S3Filesystem, GCSFilesystem, or AzureBlobFilesystem.

note

MesaFilesystem runs in the Mastra process.

Mesa's POSIX mount (for using a Mesa filesystem within a sandbox) isn't yet part of the @mastra/mesa package. Support is coming soon.

Installation

npm

npm install @mastra/mesa

pnpm

pnpm add @mastra/mesa

Yarn

yarn add @mastra/mesa

Bun

bun add @mastra/mesa

Usage example

Mount one Mesa repo and pass the filesystem to a workspace:

src/mastra/workspace.ts

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { MesaFilesystem, repo } from '@mastra/mesa'

const workspace = new Workspace({
  filesystem: new MesaFilesystem({
    privateKey: process.env.MESA_PRIVATE_KEY,
    authors: [{ name: 'File Agent', email: 'agent@example.com' }],
    layout: {
      '/docs': repo('docs', { mode: 'rw', at: { bookmark: 'main' } }),
    },
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'file-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})

privateKey falls back to MESA_PRIVATE_KEY when omitted. The layout uses repo(), re-exported from the Mesa SDK, to declare which repos to mount and where.

Constructor parameters

privateKey?:

string

Mesa private key. Falls back to MESA_PRIVATE_KEY when omitted.

authors:

[Author, ...Author[]]

Commit authors attributed to writes made through this filesystem.

layout:

Layout

Mesa mount layout mapping absolute paths to repos, built with repo().

cache?:

{ diskCache?: { path: string; maxSizeBytes?: number } }

Mesa filesystem cache configuration.

ttl?:

number

Mesa mount token lifetime in seconds.

readOnly?:

boolean

= false

Mount every repo in the layout as read-only.

Properties

id:

string

Filesystem instance identifier.

name:

string

Provider name ('MesaFilesystem').

provider:

string

Provider identifier ('mesa').

readOnly:

boolean | undefined

Whether write operations are blocked.

client:

Mesa | undefined

Mesa SDK client created by this provider. Undefined before initialization.

filesystem:

MesaFileSystem

Active Mesa filesystem. Access this after initialization when you need the raw Mesa SDK filesystem.

change:

MesaFileSystem["change"]

Mesa change management operations for the mounted filesystem.

bookmark:

MesaFileSystem["bookmark"]

Mesa bookmark management operations for the mounted filesystem.

Methods

MesaFilesystem implements the WorkspaceFilesystem interface.

File operations

readFile(path, options?)

Reads a file from Mesa.

const content = await filesystem.readFile('/docs/README.md', {
  encoding: 'utf-8',
})

Returns: Promise<string | Buffer>

writeFile(path, content, options?)

Writes a file to Mesa.

await filesystem.writeFile('/docs/report.md', '# Report')

Returns: Promise<void>

appendFile(path, content)

Appends content to a file.

await filesystem.appendFile('/docs/log.txt', 'new line\n')

Returns: Promise<void>

deleteFile(path, options?)

Deletes a file.

await filesystem.deleteFile('/docs/old-report.md')

Returns: Promise<void>

copyFile(src, dest, options?)

Copies a file.

await filesystem.copyFile('/docs/report.md', '/docs/archive/report.md')

Returns: Promise<void>

moveFile(src, dest, options?)

Moves or renames a file.

await filesystem.moveFile('/docs/draft.md', '/docs/final.md')

Returns: Promise<void>

Directory operations

mkdir(path, options?)

Creates a directory.

await filesystem.mkdir('/docs/reports', { recursive: true })

Returns: Promise<void>

rmdir(path, options?)

Removes a directory.

await filesystem.rmdir('/docs/reports', { recursive: true })

Returns: Promise<void>

readdir(path, options?)

Lists directory entries.

const entries = await filesystem.readdir('/docs', {
  recursive: true,
  extension: '.md',
})

Returns: Promise<FileEntry[]>

Path operations

exists(path)

Checks whether a path exists.

const exists = await filesystem.exists('/docs/README.md')

Returns: Promise<boolean>

stat(path)

Returns file or directory metadata.

const stat = await filesystem.stat('/docs/README.md')

Returns: Promise<FileStat>

realpath(path)

Returns the canonical path from Mesa.

const realPath = await filesystem.realpath('/docs/README.md')

Returns: Promise<string>

Mesa operations

bash(options?)

Creates a Mesa-backed Bash runtime for this filesystem.

const bash = await filesystem.bash({
  cwd: '/docs',
})

Returns: Promise<Bash>

Path semantics

Methods expect absolute paths. For MesaFilesystem, paths are rooted at the Mesa mount and start with a path from the layout:

await filesystem.readFile('/docs/README.md')

Don't omit the leading slash:

await filesystem.readFile('docs/README.md') // Incorrect
await filesystem.readFile('/docs/README.md') // Correct

When you mount multiple repos, each repo is available under its layout path:

const filesystem = new MesaFilesystem({
  authors: [{ name: 'File Agent' }],
  layout: {
    '/docs': repo('docs', { mode: 'rw', at: { bookmark: 'main' } }),
    '/website': repo('website', { mode: 'rw', at: { bookmark: 'main' } }),
  },
})

await filesystem.readFile('/docs/README.md')
await filesystem.readFile('/website/package.json')

Mesa versioning APIs

Access the underlying Mesa filesystem for Mesa-specific change and bookmark operations:

await filesystem.writeFile('/docs/draft.md', 'Draft')

const current = await filesystem.change.current({
  repo: 'docs',
})

await filesystem.bookmark.move({
  repo: 'docs',
  name: 'main',
  changeId: current.changeId,
})

More details on versioning semantics can be found in Mesa's docs.

Read-only mode

Set readOnly: true to mount every repo in the layout read-only and block write operations through Mastra:

const filesystem = new MesaFilesystem({
  authors: [{ name: 'File Agent' }],
  layout: { '/docs': repo('docs', { mode: 'ro', at: { bookmark: 'main' } }) },
  readOnly: true,
})

Read operations still work. Write operations throw WorkspaceReadOnlyError.

Concurrency

overwrite: false and expectedMtime use preflight checks before writing. These checks aren't atomic unless Mesa adds native conditional writes for app mounts.

Related

• WorkspaceFilesystem interface
• Filesystem docs
• Sandbox
• Mesa documentation