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

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

= Auto-generated

Unique identifier for the workspace

name?:

string

= workspace-{id}

Human-readable name

filesystem?:

WorkspaceFilesystem

Filesystem provider instance (e.g., LocalFilesystem)

sandbox?:

WorkspaceSandbox

Sandbox provider instance (e.g., LocalSandbox)

bm25?:

boolean | BM25Config

= undefined

Enable BM25 keyword search. Pass true for defaults or a config object.

vectorStore?:

MastraVector

Vector store for semantic search

embedder?:

(text: string) => Promise<number[]>

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<string[]>)

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

WorkspaceToolsConfig

enabled?:

boolean

Whether the tool is available to agents

requireApproval?:

boolean

Whether the tool requires user approval before execution

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.

requireReadBeforeWrite?:

boolean

For write tools: require reading the file first to prevent overwrites

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.

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 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.

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.

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.

await workspace.destroy()

Search operations

index(path, content, options?)

Index content for search.

await workspace.index('/docs/guide.md', 'Guide content...')

search(query, options?)

Search indexed content.

const results = await workspace.search('password reset', {
  topK: 10,
  mode: 'hybrid',
})

Utility

getInfo()

Get workspace information.

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.

const instructions = workspace.getInstructions()

Pass requestContext to enable per-request customization when a provider's instructions option is a function:

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 or LocalSandbox.

getToolsConfig()

Get the current tools configuration.

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).

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.

BackgroundProcessesConfig

onStdout?:

(data: string, meta: BackgroundProcessMeta) => void

Callback for stdout chunks from background processes.

onStderr?:

(data: string, meta: BackgroundProcessMeta) => void

Callback for stderr chunks from background processes.

onExit?:

(meta: BackgroundProcessExitMeta) => void

Callback when a background process exits. Meta includes pid, exitCode, stdout, and stderr.

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 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.