WorkspaceFilesystem

Added in: @mastra/[email protected]

The WorkspaceFilesystem interface defines how workspaces interact with file storage.

Methods

readFile(path, options?)

Read file contents.

const content = await filesystem.readFile('/docs/guide.md')
const buffer = await filesystem.readFile('/image.png', { encoding: 'binary' })

Parameters:

<PropertiesTable content={[ { name: 'path', type: 'string', description: 'File path relative to basePath', }, { name: 'options', type: 'Options', description: 'readFile options.', isOptional: true, properties: [ { type: 'Options', parameters: [ { name: 'encoding', type: "'utf-8' | 'binary'", description: 'Text or binary encoding', isOptional: true, defaultValue: "'utf-8'", }, ], }, ], }, ]} />

Returns: Promise<string | Buffer>

writeFile(path, content, options?)

Write file contents.

await filesystem.writeFile('/docs/new.md', '# New Document')
await filesystem.writeFile('/nested/path/file.md', content, { recursive: true })

Parameters:

<PropertiesTable content={[ { name: 'path', type: 'string', description: 'File path relative to basePath', }, { name: 'content', type: 'string | Buffer', description: 'File content', }, { name: 'options', type: 'Options', description: 'Configuration options.', isOptional: true, properties: [ { type: 'Options', parameters: [ { name: 'recursive', type: 'boolean', description: "Create parent directories if they don't exist", isOptional: true, defaultValue: 'false', }, { name: 'overwrite', type: 'boolean', description: 'Overwrite existing file', isOptional: true, defaultValue: 'true', }, { name: 'expectedMtime', type: 'Date', description: "If provided, the write fails with a StaleFileError when the file's current modification time doesn't match. Use this for optimistic concurrency control to detect external modifications between read and write.", isOptional: true, }, ], }, ], }, ]} />

deleteFile(path, options?)

Delete a file.

await filesystem.deleteFile('/docs/old.md')
await filesystem.deleteFile('/docs/maybe.md', { force: true }) // Don't throw if missing

Parameters:

<PropertiesTable content={[ { name: 'path', type: 'string', description: 'File path', }, { name: 'options', type: 'Options', description: 'Configuration options.', isOptional: true, properties: [ { type: 'Options', parameters: [ { name: 'force', type: 'boolean', description: "Don't throw error if file doesn't exist", isOptional: true, defaultValue: 'false', }, ], }, ], }, ]} />

appendFile(path, content)

Append content to a file, creating it if it doesn't already exist. Parent directories are created automatically.

await filesystem.appendFile('/logs/app.log', 'New log entry\n')

Parameters:

<PropertiesTable content={[ { name: 'path', type: 'string', description: 'File path', }, { name: 'content', type: 'string | Buffer', description: 'Content to append', }, ]} />

copyFile(src, dest, options?)

Copy a file to a new location.

await filesystem.copyFile('/docs/template.md', '/docs/new-doc.md')

Parameters:

<PropertiesTable content={[ { name: 'src', type: 'string', description: 'Source file path', }, { name: 'dest', type: 'string', description: 'Destination file path', }, { name: 'options', type: 'Options', description: 'Configuration options.', isOptional: true, properties: [ { type: 'Options', parameters: [ { name: 'overwrite', type: 'boolean', description: 'Overwrite destination if it exists', isOptional: true, defaultValue: 'true', }, ], }, ], }, ]} />

moveFile(src, dest, options?)

Move or rename a file.

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

Parameters:

<PropertiesTable content={[ { name: 'src', type: 'string', description: 'Source file path', }, { name: 'dest', type: 'string', description: 'Destination file path', }, { name: 'options', type: 'Options', description: 'Configuration options.', isOptional: true, properties: [ { type: 'Options', parameters: [ { name: 'overwrite', type: 'boolean', description: 'Overwrite destination if it exists', isOptional: true, defaultValue: 'true', }, ], }, ], }, ]} />

readdir(path, options?)

List directory contents.

const entries = await filesystem.readdir('/docs')
// [{ name: 'guide.md', type: 'file' }, { name: 'api', type: 'directory' }]

Returns: Promise<FileEntry[]>

interface FileEntry {
  name: string
  type: 'file' | 'directory'
  size?: number
  isSymlink?: boolean
  symlinkTarget?: string
}

mkdir(path, options?)

Create a directory.

await filesystem.mkdir('/docs/api')
await filesystem.mkdir('/deeply/nested/path', { recursive: true })

Parameters:

<PropertiesTable content={[ { name: 'path', type: 'string', description: 'Directory path', }, { name: 'options', type: 'Options', description: 'Configuration options.', isOptional: true, properties: [ { type: 'Options', parameters: [ { name: 'recursive', type: 'boolean', description: 'Create parent directories', isOptional: true, defaultValue: 'false', }, ], }, ], }, ]} />

rmdir(path, options?)

Remove a directory.

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

Parameters:

<PropertiesTable content={[ { name: 'path', type: 'string', description: 'Directory path', }, { name: 'options', type: 'Options', description: 'Configuration options.', isOptional: true, properties: [ { type: 'Options', parameters: [ { name: 'recursive', type: 'boolean', description: 'Remove contents recursively', isOptional: true, defaultValue: 'false', }, { name: 'force', type: 'boolean', description: "Don't throw if directory doesn't exist", isOptional: true, defaultValue: 'false', }, ], }, ], }, ]} />

exists(path)

Check if a path exists.

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

Returns: Promise<boolean>

stat(path)

Get file or directory metadata.

const stat = await filesystem.stat('/docs/guide.md')
// { name: 'guide.md', path: '/docs/guide.md', type: 'file', size: 1234, createdAt: Date, modifiedAt: Date }

Returns: Promise<FileStat>

interface FileStat {
  name: string // File or directory name (basename only)
  path: string // Path relative to the filesystem basePath
  type: 'file' | 'directory'
  size: number
  createdAt: Date
  modifiedAt: Date
  mimeType?: string
}

Optional methods

init()

Initialize the filesystem. Called by workspace.init().

await filesystem.init?.()

destroy()

Clean up resources. Called by workspace.destroy().

await filesystem.destroy?.()

getInfo()

Get filesystem metadata.

const info = await filesystem.getInfo?.()
// { id, name, provider, basePath, readOnly, status, storage? }

Returns: Promise<FilesystemInfo>

interface FilesystemInfo {
  id: string
  name: string
  provider: string
  basePath?: string
  readOnly?: boolean
  status?: string
  storage?: {
    totalBytes?: number
    usedBytes?: number
    availableBytes?: number
  }
}

getInstructions(opts?)

Returns a description of how this filesystem works. Injected into the agent's system message when the workspace is assigned to an agent.

const instructions = filesystem.getInstructions?.()
// 'Local filesystem at "/workspace". Files at workspace path "/foo" are stored at "/workspace/foo" on disk.'

Parameters:

<PropertiesTable content={[ { name: 'opts.requestContext', type: 'RequestContext', description: 'Forwarded to the instructions function if one was provided in the constructor.', isOptional: true, }, ]} />

Returns: string

Related

• Workspace Class
• Sandbox Interface