@mastra/core/dist/docs/references/reference-file-based-agents-workspace.md

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

# Workspace

A [workspace](https://mastra.ai/docs/workspace/overview) gives an agent filesystem access and command execution. File-based agents get a default workspace automatically when discovered through `mastra dev` or `mastra build`, so they 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 [Workspaces](https://mastra.ai/docs/workspace/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.

## 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 [workspace overview](https://mastra.ai/docs/workspace/overview), [sandbox guide](https://mastra.ai/docs/workspace/sandbox), and [workspace search](https://mastra.ai/docs/workspace/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`; otherwise the default file-based workspace is used. See [`config.ts` precedence](https://mastra.ai/reference/file-based-agents/config) for the full merge table.