Workspace

A workspace gives agents a persistent environment for storing files and executing commands. Agents use workspace tools to read and write files, run shell commands, and search indexed content.

How Workspaces Work

A workspace supports the following features:

• Filesystem - File storage (read, write, list, delete)
• Sandbox - Command execution (shell commands)
• Search - BM25, vector, or hybrid search over indexed content
• Skills - Reusable instructions for agents

When you assign a workspace to an agent, Mastra includes the corresponding tools in the agent's toolset. The agent can then use these tools to interact with files and execute commands as part of its task.

You can create a workspace with any combination of these features. The agent receives only the tools relevant to what's configured.

Creating a Workspace

import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace';

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
  }),
  sandbox: new LocalSandbox({
    workingDirectory: './workspace',
  }),
  skills: ['/skills'],
});

Global Workspace

Set a workspace on the Mastra instance. All agents inherit this workspace unless they define their own:

import { Mastra } from '@mastra/core';
import { Workspace, LocalFilesystem } from '@mastra/core/workspace';

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
});

const mastra = new Mastra({
  workspace,
  agents: { myAgent },
});

Agent-scoped Workspace

Assign a workspace directly to an agent to override the global workspace:

import { Agent } from '@mastra/core/agent';
import { Workspace, LocalFilesystem } from '@mastra/core/workspace';

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './agent-workspace' }),
});

export const myAgent = new Agent({
  id: 'my-agent',
  model: 'openai/gpt-4o',
  workspace,
});

Initialization

You can optionally call init() to initialize the workspace before use:

import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace';

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
});

await workspace.init();

What init() does

Initialization runs setup logic for each configured provider:

• LocalFilesystem: Creates the base directory if it doesn't exist
• LocalSandbox: Creates working directory
• Search (if configured): Indexes files from autoIndexPaths — see Search and Indexing

External providers may perform additional setup like establishing connections or authenticating.

Tool Configuration

Configure tool behavior through the tools option on the Workspace. This controls which tools are enabled and their safety settings.

import { Workspace, LocalFilesystem, LocalSandbox, WORKSPACE_TOOLS } from '@mastra/core/workspace';

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  tools: {
    // Global defaults
    enabled: true,
    requireApproval: false,

    // Per-tool overrides
    [WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE]: {
      requireApproval: true,
      requireReadBeforeWrite: true,
    },
    [WORKSPACE_TOOLS.FILESYSTEM.DELETE]: {
      enabled: false,
    },
    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
      requireApproval: true,
    },
  },
});

Tool Options

Option	Type	Description
enabled	boolean	Whether the tool is available (default: true)
requireApproval	boolean	Whether the tool requires user approval before execution (default: false)
requireReadBeforeWrite	boolean	For write tools: require reading the file first (default: false)

Read-before-write

When requireReadBeforeWrite is enabled on write tools, agents must read a file before writing to it. This prevents overwriting files the agent hasn't seen:

• New files - Can be written without reading (they don't exist yet)
• Existing files - Must be read first
• Externally modified files - If a file changed since the agent read it, the write fails

Related

• Filesystem
• Sandbox
• Skills
• Search and Indexing
• Workspace Class Reference