Workspaces

Added in: @mastra/core@1.1.0

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

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

How it works

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.

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

Usage

Creating a workspace

Create a workspace by instantiating the Workspace class with your desired features:

src/mastra/workspaces.ts

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

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

The skills array specifies paths to directories containing skill definitions, see Skills.

Global workspace

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

src/mastra/index.ts

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,
});

Agent-scoped workspace

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

src/mastra/agents/my-agent.ts

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,
});

Configuration patterns

Workspaces support several configuration patterns depending on what capabilities your agent needs. The two main building blocks are filesystem (file tools) and sandbox (command execution), with mounts as the way to bridge cloud storage into sandboxes.

Filesystem + sandbox (local)

For local development, pair a LocalFilesystem and LocalSandbox pointed at the same directory. Since both operate on the local machine, files written through the filesystem are immediately available to commands in the sandbox:

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

The agent receives both file tools and execute_command. This is the simplest full-featured setup.

Mounts + sandbox (cloud storage)

When you need cloud storage accessible inside a sandbox, use mounts. This FUSE-mounts the cloud filesystem into the sandbox so commands can read and write files at the mount path:

const workspace = new Workspace({
  mounts: {
    '/data': new S3Filesystem({
      bucket: 'my-bucket',
      region: 'us-east-1',
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    }),
    '/skills': new GCSFilesystem({
      bucket: 'agent-skills',
    }),
  },
  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
});

Under the hood, mounts creates a CompositeFilesystem that routes file tool operations to the correct provider based on path prefix. Commands in the sandbox access the mounted paths directly (e.g., ls /data).

You can mount multiple providers at different paths. Each mount path must be unique and non-overlapping.

note

filesystem and mounts are mutually exclusive — you cannot use both in the same workspace. Use filesystem for a single provider without a sandbox, or mounts when you need to combine cloud storage with a sandbox.

Filesystem only

Use a single filesystem when agents only need to read and write files. No command execution is available.

const workspace = new Workspace({
  filesystem: new S3Filesystem({
    bucket: 'my-bucket',
    region: 'us-east-1',
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  }),
});

The agent receives file tools (read_file, write_file, list_directory, etc.) that operate directly against the storage provider.

Sandbox only

Use a single sandbox when agents only need to execute commands. No file tools are added.

const workspace = new Workspace({
  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
});

The agent receives the execute_command tool.

Which pattern should I use?

Scenario	Pattern
Local development with files and commands	filesystem + sandbox (both local, same directory)
Cloud storage accessible inside a cloud sandbox	mounts + sandbox
Multiple cloud providers in one sandbox	mounts + sandbox (one mount per provider)
Agent reads/writes files, no command execution needed	filesystem only
Agent runs commands, no file tools needed	sandbox only

Tool configuration

Configure tool behavior through the tools option on the workspace. This controls which tools are enabled and how they behave.

src/mastra/workspaces.ts

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

Initialization

Calling init() is optional in most cases—some providers initialize on first operation. Call init() manually when using a workspace outside of Mastra (standalone scripts, tests) or when you need to pre-provision resources before the first agent interaction.

src/mastra/workspaces.ts

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

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

// Optional: pre-create directories and sandbox before first use
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 the working directory
• Search (if configured): Indexes files from autoIndexPaths, see Search and Indexing

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

Related

• Filesystem
• Sandbox
• Skills
• Search and indexing
• Workspace class reference