packages/core/src/workspace/README.md
The Workspace module provides agents with filesystem access and code execution capabilities through a unified interface.
import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace';
const workspace = new Workspace({
filesystem: new LocalFilesystem({
basePath: './workspace',
}),
sandbox: new LocalSandbox({
workingDirectory: './workspace',
}),
bm25: true,
});
await workspace.init();
// File operations
await workspace.writeFile('/docs/guide.md', '# Guide');
const content = await workspace.readFile('/docs/guide.md', { encoding: 'utf-8' });
// Command execution
const result = await workspace.executeCommand('echo', ['hello world']);
// Search
await workspace.index('/docs/guide.md', content as string);
const results = await workspace.search('guide');
import { Agent } from '@mastra/core/agent';
const agent = new Agent({
id: 'my-agent',
workspace: workspace,
// Agent receives workspace tools when a workspace is provided
});
const workspace = new Workspace({
filesystem: new LocalFilesystem({
basePath: './workspace',
readOnly: true, // Block all write operations (default: false)
}),
sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
tools: {
// Top-level defaults for all tools
requireApproval: true,
// Per-tool overrides
mastra_workspace_write_file: {
requireReadBeforeWrite: true, // Require reading files before writing
},
mastra_workspace_execute_command: {
requireApproval: true,
},
},
});
workspace.ts - Main Workspace classfilesystem.ts - WorkspaceFilesystem interface and typeslocal-filesystem.ts - LocalFilesystem implementationsandbox.ts - WorkspaceSandbox interface and typeslocal-sandbox.ts - LocalSandbox implementationtools.ts - Workspace tool generation for agentssearch-engine.ts - BM25 and vector searchbm25.ts - BM25 algorithm implementationskills/ - Skills system for SKILL.md filesfile-read-tracker.ts - Read-before-write trackingline-utils.ts - Line number utilities for search results