> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# Workspace

> **Beta:** Breaking changes may occur without a major version bump until the API is stable.

A [workspace](https://mastra.ai/docs/sandbox/overview) 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](https://mastra.ai/docs/sandbox/overview).

## Default workspace

Without `workspace.ts`, a file-based agent gets a default [`Workspace`](https://mastra.ai/reference/workspace/workspace-class) when the build provides a per-agent workspace path. The default workspace uses:

- [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) rooted at the agent's bundled workspace directory.
- [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) 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:

```typescript
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:

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

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

```typescript
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](https://mastra.ai/reference/workspace/workspace-class) 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](https://mastra.ai/docs/sandbox/overview) and [workspace search](https://mastra.ai/docs/sandbox/search).

## Runtime boundary

The workspace filesystem controls what file tools can read and write. The sandbox controls where shell commands run. Application runtime code, including code in [`tools/`](https://mastra.ai/reference/file-based-agents/tools), still runs in your app/server process unless it explicitly calls workspace or sandbox APIs.

## 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, so the agent starts with those files on disk.

```text
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](https://mastra.ai/reference/file-based-agents/config) for the full merge table.