# Workspace class **Added in:** `@mastra/core@1.1.0` The `Workspace` class combines a filesystem and sandbox to provide agents with file storage and command execution capabilities. It also supports BM25 and vector search for indexed content. ## Usage example ```typescript import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace' const workspace = new Workspace({ id: 'my-workspace', name: 'My Workspace', filesystem: new LocalFilesystem({ basePath: './workspace', }), sandbox: new LocalSandbox({ workingDirectory: './workspace', }), bm25: true, autoIndexPaths: ['/docs'], }) ``` ## Constructor parameters **id** (`string`): Unique identifier for the workspace (Default: `Auto-generated`) **name** (`string`): Human-readable name (Default: `workspace-{id}`) **filesystem** (`WorkspaceFilesystem`): Filesystem provider instance (e.g., LocalFilesystem) **sandbox** (`WorkspaceSandbox`): Sandbox provider instance (e.g., LocalSandbox) **bm25** (`boolean | BM25Config`): Enable BM25 keyword search. Pass true for defaults or a config object. (Default: `undefined`) **vectorStore** (`MastraVector`): Vector store for semantic search **embedder** (`(text: string) => Promise`): Embedder function for generating vectors. Required when vectorStore is provided. **autoIndexPaths** (`string[]`): Paths or glob patterns to auto-index on init(). Supports glob patterns like '\*\*/\*.md' for selective indexing. **skills** (`string[] | ((context: SkillsContext) => string[] | Promise)`): Paths where SKILL.md files are located. This can be a static array or an async function that resolves paths dynamically. Supports glob patterns like './\*\*/skills' for discovery. **skillSource** (`SkillSource`): Custom skill source for skill discovery. When provided, this source is used instead of the workspace filesystem. Use VersionedSkillSource to serve published skill versions from a content-addressable blob store. **onMount** (`OnMountHook`): Pre-mount hook called for each filesystem before mounting into a sandbox. Return false to skip mounting, or return { success: true } if the hook handled the mount. Return undefined to use the default mount behavior. **searchIndexName** (`string`): Custom index name for the vector store. Must be a valid SQL identifier (start with a letter or underscore, contain only letters, numbers, or underscores, max 63 characters). Defaults to a sanitized version of '{id}\_search'. **tools** (`WorkspaceToolsConfig`): Per-tool configuration for enabling tools and setting safety options **tools.enabled** (`boolean`): Whether the tool is available to agents **tools.requireApproval** (`boolean`): Whether the tool requires user approval before execution **tools.name** (`string`): Custom name to expose this tool as. Replaces the default \`mastra\_workspace\_\*\` name. The config key must still use the original \`WORKSPACE\_TOOLS\` constant. **tools.requireReadBeforeWrite** (`boolean`): For write tools: require reading the file first to prevent overwrites **tools.maxOutputTokens** (`number`): Maximum tokens for tool output. Output exceeding this limit is truncated using tiktoken. **operationTimeout** (`number`): Timeout for operations in milliseconds ## Tool configuration The `tools` option accepts a `WorkspaceToolsConfig` object that controls which workspace tools are enabled and their safety settings. ```typescript import { Workspace } from '@mastra/core/workspace' import { WORKSPACE_TOOLS } from '@mastra/core/workspace' const workspace = new Workspace({ id: 'my-workspace', name: 'My Workspace', tools: { // Global defaults (apply to all tools) enabled: true, requireApproval: false, // Per-tool overrides using WORKSPACE_TOOLS constants [WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE]: { requireApproval: true, }, }, }) ``` The config object has two parts: - **Global defaults** (`enabled`, `requireApproval`): Apply to all tools unless overridden - **Per-tool overrides** - Use `WORKSPACE_TOOLS` constants as keys to configure individual tools See [workspace overview](https://mastra.ai/docs/workspace/overview) for more examples. ### Tool name remapping Rename workspace tools by setting the `name` property on individual tool configs. The config key remains the original constant — only the name exposed to the agent changes. ```typescript import { Workspace } from '@mastra/core/workspace' import { WORKSPACE_TOOLS } from '@mastra/core/workspace' const workspace = new Workspace({ id: 'my-workspace', name: 'My Workspace', tools: { [WORKSPACE_TOOLS.FILESYSTEM.READ_FILE]: { name: 'view' }, [WORKSPACE_TOOLS.FILESYSTEM.GREP]: { name: 'search_content' }, }, }) ``` Tool names must be unique across all workspace tools. Setting a custom name that conflicts with another tool's default or custom name throws an error. ## Properties **id** (`string`): Workspace identifier **name** (`string`): Workspace name **status** (`WorkspaceStatus`): 'pending' | 'initializing' | 'ready' | 'paused' | 'error' | 'destroying' | 'destroyed' **filesystem** (`WorkspaceFilesystem | undefined`): The filesystem provider **sandbox** (`WorkspaceSandbox | undefined`): The sandbox provider **skills** (`WorkspaceSkills | undefined`): Skills interface for accessing SKILL.md files **canBM25** (`boolean`): Whether BM25 search is available **canVector** (`boolean`): Whether vector search is available **canHybrid** (`boolean`): Whether hybrid search is available ## Methods ### Lifecycle #### `init()` Initialize the workspace and prepare resources. ```typescript await workspace.init() ``` Calling `init()` is optional in most cases: - **Sandbox**: Auto-starts on first `executeCommand()` call. Use `init()` to avoid first-command latency. - **Filesystem**: Creates the base directory and runs any provider-specific setup. Some providers auto-create the directory on first operation. - **Search**: Required only if using `autoIndexPaths` for auto-indexing. Initialization performs: - Starts the filesystem provider (creates base directory if needed) - Starts the sandbox provider (creates working directory, sets up isolation if configured) - Indexes files from `autoIndexPaths` for search #### `destroy()` Destroy the workspace and clean up resources. ```typescript await workspace.destroy() ``` ### Search operations #### `index(path, content, options?)` Index content for search. ```typescript await workspace.index('/docs/guide.md', 'Guide content...') ``` #### `search(query, options?)` Search indexed content. ```typescript const results = await workspace.search('password reset', { topK: 10, mode: 'hybrid', }) ``` ### Utility #### `getInfo()` Get workspace information. ```typescript const info = await workspace.getInfo() // { id, name, status, createdAt, lastAccessedAt, filesystem?, sandbox? } ``` #### `getInstructions(opts?)` Returns combined instructions from the filesystem and sandbox providers. Injected into the agent's system message to help it understand the execution context. ```typescript const instructions = workspace.getInstructions() ``` Pass `requestContext` to enable per-request customization when a provider's `instructions` option is a function: ```typescript const instructions = workspace.getInstructions({ requestContext }) ``` **Parameters:** **opts.requestContext** (`RequestContext`): Forwarded to the \`instructions\` function on the filesystem or sandbox provider, if one is configured. **Returns:** `string` To override the default output, pass an `instructions` option to [LocalFilesystem](https://mastra.ai/reference/workspace/local-filesystem) or [LocalSandbox](https://mastra.ai/reference/workspace/local-sandbox). #### `getToolsConfig()` Get the current tools configuration. ```typescript const config = workspace.getToolsConfig() ``` **Returns:** `WorkspaceToolsConfig | undefined` #### `setToolsConfig(config?)` Replace the per-tool configuration at runtime. This performs a full replacement — it doesn't merge with the previous config. Pass `undefined` to reset to defaults. Changes take effect on the next agent interaction (the next `createWorkspaceTools()` call). ```typescript import { WORKSPACE_TOOLS } from '@mastra/core/workspace' // Disable write tools for read-only mode workspace.setToolsConfig({ [WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE]: { enabled: false }, [WORKSPACE_TOOLS.FILESYSTEM.EDIT_FILE]: { enabled: false }, }) // Reset to defaults workspace.setToolsConfig(undefined) ``` **Parameters:** **config** (`WorkspaceToolsConfig | undefined`): New tool configuration to apply. Pass undefined to reset to defaults. ## Agent tools A workspace provides tools to agents based on what's configured. ### Filesystem tools Added when a filesystem is configured: | Tool | Description | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mastra_workspace_read_file` | Read file contents. Supports optional line range for reading specific portions of large files. | | `mastra_workspace_write_file` | Create or overwrite a file with new content. Creates parent directories automatically. | | `mastra_workspace_edit_file` | Edit an existing file by finding and replacing text. Useful for targeted changes without rewriting the entire file. | | `mastra_workspace_list_files` | List directory contents as a tree structure. Supports recursive listing with depth limits, glob patterns, and `.gitignore` filtering (enabled by default). | | `mastra_workspace_delete` | Delete a file or directory. Supports recursive deletion for directories. | | `mastra_workspace_file_stat` | Get metadata about a file or directory including size, type, and modification time. | | `mastra_workspace_mkdir` | Create a directory. Creates parent directories automatically if they don't exist. | | `mastra_workspace_grep` | Search file contents using regex patterns. Supports glob filtering, context lines, and case-insensitive search. | Write tools (`write_file`, `edit_file`, `delete`, `mkdir`) are excluded when the filesystem is in read-only mode. ### Sandbox tools Added when a sandbox is configured: | Tool | Description | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `mastra_workspace_execute_command` | Execute a shell command. Returns stdout, stderr, and exit code. When the sandbox has a process manager, accepts `background: true` to spawn a long-running process and return a PID. | | `mastra_workspace_get_process_output` | Get stdout, stderr, and status of a background process by PID. Accepts `tail` to limit output lines and `wait: true` to block until exit. Only available when the sandbox has a process manager. | | `mastra_workspace_kill_process` | Kill a background process by PID. Returns the last 50 lines of output. Only available when the sandbox has a process manager. | The `execute_command` tool accepts a `backgroundProcesses` option for lifecycle callbacks on background processes: **backgroundProcesses** (`BackgroundProcessesConfig`): Configuration for handling background processes. Only applicable if the sandbox supports background execution. **backgroundProcesses.onStdout** (`(data: string, meta: BackgroundProcessMeta) => void`): Callback for stdout chunks from background processes. **backgroundProcesses.onStderr** (`(data: string, meta: BackgroundProcessMeta) => void`): Callback for stderr chunks from background processes. **backgroundProcesses.onExit** (`(meta: BackgroundProcessExitMeta) => void`): Callback when a background process exits. Meta includes pid, exitCode, stdout, and stderr. **backgroundProcesses.abortSignal** (`AbortSignal | null | false`): Abort signal for background processes. undefined (default) uses the agent's signal. null or false disables abort — processes persist after agent shutdown. See [Background process callbacks](https://mastra.ai/docs/workspace/sandbox) for usage examples. ### Search tools Added when BM25 or vector search is configured: | Tool | Description | | ------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `mastra_workspace_search` | Search indexed content using keyword (BM25), semantic (vector), or hybrid search. Returns ranked results with scores. | | `mastra_workspace_index` | Index content for search. Associates content with a path for later retrieval. | The `index` tool is excluded when the filesystem is in read-only mode. ### Skill tools Added when skills are configured: | Tool | Description | | -------------- | --------------------------------------------------------------------------------------------------------- | | `skill` | Activate a skill by name or path. Returns the skill's full instructions, references, scripts, and assets. | | `skill_search` | Search across skill content. Accepts an optional list of skill names to filter and a `topK` parameter. | | `skill_read` | Read a specific file (reference, script, or asset) from a skill directory. | When multiple skills share the same name, `list()` returns all of them. `get()` with a name applies tie-breaking (local > managed > external). If two skills share the same name _and_ source type, `get()` throws an error. Pass a skill's full path to `get()` to bypass tie-breaking. See [Same-named skills](https://mastra.ai/docs/workspace/skills) for details.