@mastra/core
Version:
Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.
271 lines (172 loc) • 6 kB
Markdown
# WorkspaceFilesystem
**Added in:** `@mastra/core@1.1.0`
The `WorkspaceFilesystem` interface defines how workspaces interact with file storage.
## Methods
### `readFile(path, options?)`
Read file contents.
```typescript
const content = await filesystem.readFile('/docs/guide.md')
const buffer = await filesystem.readFile('/image.png', { encoding: 'binary' })
```
**Parameters:**
**path** (`string`): File path relative to basePath
**options** (`Options`): readFile options.
**options.encoding** (`'utf-8' | 'binary'`): Text or binary encoding
**Returns:** `Promise<string | Buffer>`
### `writeFile(path, content, options?)`
Write file contents.
```typescript
await filesystem.writeFile('/docs/new.md', '# New Document')
await filesystem.writeFile('/nested/path/file.md', content, { recursive: true })
```
**Parameters:**
**path** (`string`): File path relative to basePath
**content** (`string | Buffer`): File content
**options** (`Options`): Configuration options.
**options.recursive** (`boolean`): Create parent directories if they don't exist
**options.overwrite** (`boolean`): Overwrite existing file
**options.expectedMtime** (`Date`): 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.
### `deleteFile(path, options?)`
Delete a file.
```typescript
await filesystem.deleteFile('/docs/old.md')
await filesystem.deleteFile('/docs/maybe.md', { force: true }) // Don't throw if missing
```
**Parameters:**
**path** (`string`): File path
**options** (`Options`): Configuration options.
**options.force** (`boolean`): Don't throw error if file doesn't exist
### `appendFile(path, content)`
Append content to a file, creating it if it doesn't already exist. Parent directories are created automatically.
```typescript
await filesystem.appendFile('/logs/app.log', 'New log entry\n')
```
**Parameters:**
**path** (`string`): File path
**content** (`string | Buffer`): Content to append
### `copyFile(src, dest, options?)`
Copy a file to a new location.
```typescript
await filesystem.copyFile('/docs/template.md', '/docs/new-doc.md')
```
**Parameters:**
**src** (`string`): Source file path
**dest** (`string`): Destination file path
**options** (`Options`): Configuration options.
**options.overwrite** (`boolean`): Overwrite destination if it exists
### `moveFile(src, dest, options?)`
Move or rename a file.
```typescript
await filesystem.moveFile('/docs/draft.md', '/docs/final.md')
```
**Parameters:**
**src** (`string`): Source file path
**dest** (`string`): Destination file path
**options** (`Options`): Configuration options.
**options.overwrite** (`boolean`): Overwrite destination if it exists
### `readdir(path, options?)`
List directory contents.
```typescript
const entries = await filesystem.readdir('/docs')
// [{ name: 'guide.md', type: 'file' }, { name: 'api', type: 'directory' }]
```
**Returns:** `Promise<FileEntry[]>`
```typescript
interface FileEntry {
name: string
type: 'file' | 'directory'
size?: number
isSymlink?: boolean
symlinkTarget?: string
}
```
### `mkdir(path, options?)`
Create a directory.
```typescript
await filesystem.mkdir('/docs/api')
await filesystem.mkdir('/deeply/nested/path', { recursive: true })
```
**Parameters:**
**path** (`string`): Directory path
**options** (`Options`): Configuration options.
**options.recursive** (`boolean`): Create parent directories
### `rmdir(path, options?)`
Remove a directory.
```typescript
await filesystem.rmdir('/docs/old')
await filesystem.rmdir('/docs/nested', { recursive: true })
```
**Parameters:**
**path** (`string`): Directory path
**options** (`Options`): Configuration options.
**options.recursive** (`boolean`): Remove contents recursively
**options.force** (`boolean`): Don't throw if directory doesn't exist
### `exists(path)`
Check if a path exists.
```typescript
const exists = await filesystem.exists('/docs/guide.md')
```
**Returns:** `Promise<boolean>`
### `stat(path)`
Get file or directory metadata.
```typescript
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>`
```typescript
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()`.
```typescript
await filesystem.init?.()
```
### `destroy()`
Clean up resources. Called by `workspace.destroy()`.
```typescript
await filesystem.destroy?.()
```
### `getInfo()`
Get filesystem metadata.
```typescript
const info = await filesystem.getInfo?.()
// { id, name, provider, basePath, readOnly, status, storage? }
```
**Returns:** `Promise<FilesystemInfo>`
```typescript
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.
```typescript
const instructions = filesystem.getInstructions?.()
// 'Local filesystem at "/workspace". Files at workspace path "/foo" are stored at "/workspace/foo" on disk.'
```
**Parameters:**
**opts.requestContext** (`RequestContext`): Forwarded to the \`instructions\` function if one was provided in the constructor.
**Returns:** `string`
## Related
- [Workspace Class](https://mastra.ai/reference/workspace/workspace-class)
- [Sandbox Interface](https://mastra.ai/reference/workspace/sandbox)