Workspace

A workspace assembles capabilities such as filesystem access and command execution. The configured backends determine which tools are available. File-based agents get a default workspace automatically when discovered through mastra dev or mastra build. This default includes filesystem access and command execution, so agents can read and write files and run shell commands without extra configuration.

Use this page for the file-based convention. For workspace providers, tools, search, lifecycle, and sandbox details, see Sandbox.

Default workspace

Without workspace.ts, a file-based agent gets a default Workspace when the build provides a per-agent workspace path. The default workspace uses:

• LocalFilesystem rooted at the agent's bundled workspace directory.
• LocalSandbox with the same working directory.

This gives the agent file tools and shell tools automatically. The default workspace is per agent. Subagents get nested workspace directories under their parent agent's workspace path.

Disable the default workspace

Set workspace to undefined in config.ts to create the agent without a workspace:

src/mastra/agents/weather/config.ts

import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5.6-sol',
  workspace: undefined,
})

The agent doesn't receive the automatic file and shell tools when you disable the workspace.

Quickstart

For the default workspace, don't add a file. Start with an agent directory like this:

Default workspace

src/mastra/agents/weather/
├── config.ts
└── instructions.md

Add workspace.ts only when you need to customize the workspace:

src/mastra/agents/weather/workspace.ts

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

export default new Workspace({
  name: 'weather-workspace',
  filesystem: new LocalFilesystem({ basePath: './data/weather' }),
  sandbox: new LocalSandbox({ workingDirectory: './data/weather' }),
})

Visit the Workspace reference for the full config.

When to customize the workspace

Customize the workspace when the default local directory isn't enough. Common reasons include:

• Point file tools at a different filesystem root.
• Run shell commands in a different sandbox provider.
• Add workspace search with BM25 or vector search.
• Share one workspace across multiple agents.

For provider patterns and runtime behavior, see the sandbox guide and workspace search.

Runtime boundary

The workspace filesystem controls file-tool access, and the sandbox determines where shell commands run. Unless it explicitly calls workspace or sandbox APIs, application runtime code still runs in your app or server process, including code in tools/.

Seed files

Add a workspace/ directory to include starting files with the agent. Mastra mirrors files under workspace/ into the agent's default runtime workspace at build time. The agent starts with those files on disk.

Seed files

src/mastra/agents/weather/
├── config.ts
└── workspace/
    ├── README.md
    └── data/
        └── cities.json

The files are copied into the bundled workspace path, where workspace file tools and sandbox commands can read them. Symlinked seed files are skipped during mirroring.

Precedence with config

config.workspace wins over workspace.ts, including when you set it to undefined. Otherwise, Mastra uses the default file-based workspace. See config.ts precedence for the full merge table.