Workspace Class

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 to auto-index on init()

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.

tools?:

WorkspaceToolsConfig

Per-tool configuration for enabling tools and setting safety options

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_TOOLS } from '@mastra/core/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.

Per-tool Options

Each tool can be configured with these options:

enabled?:

boolean

= true

Whether the tool is available to agents

requireApproval?:

boolean

= false

Whether the tool requires user approval before execution

requireReadBeforeWrite?:

boolean

= false

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

Properties

id:

string

Workspace identifier

name:

string

Workspace name

status:

WorkspaceStatus

'pending' | 'initializing' | 'ready' | '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: Only needed if the base directory doesn't exist yet.
• 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? }

getPathContext()

Get information about filesystem and sandbox paths, including instructions for agents.

const context = workspace.getPathContext();
// { filesystem?, sandbox?, instructions }

Returns: PathContext

interface PathContext {
  filesystem?: {
    provider: string;
    basePath?: string;
  };
  sandbox?: {
    provider: string;
    workingDirectory?: string;
  };
  instructions: string;
}

The instructions field contains provider-generated descriptions combined from the filesystem and sandbox. These instructions are included in tool descriptions to help agents understand the execution context.

getToolsConfig()

Get the tools configuration.

const config = workspace.getToolsConfig();

Agent Tools

A workspace provides tools to agents based on what is 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.
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.

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 with arguments. Returns stdout, stderr, and exit code. Supports timeouts and streaming output.

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.

Related

• Workspace Overview
• Search and Indexing
• Filesystem Reference
• Sandbox Reference