Workspaces give your agents a place to actually do work, letting them read and write files, execute commands, search content, and follow reusable skills from configured environments. It's the difference between an agent that can only talk about tasks and one that can get sh*t done!
The best part is, you get fine-grained control over exactly what your agents can and can't do. Grant filesystem access but block deletes. Allow command execution but require approval. Share skills between agents with different permission levels for each.
The core concept
A Workspace can have up to four capabilities: filesystem access, command execution, search, and skills, but you only need to configure the ones your agent needs
1// src/mastra/workspace/diagram-workspace.ts
2
3import { Workspace, LocalFilesystem, LocalSandbox } from "@mastra/core/workspace";
4
5const DIAGRAMS_DIR = "./diagram-demo";
6
7export const diagramWorkspace = new Workspace({
8 id: "diagram-workspace",
9 name: "Diagram Rendering Workspace",
10 filesystem: new LocalFilesystem({ basePath: DIAGRAMS_DIR }),
11 sandbox: new LocalSandbox({ workingDirectory: DIAGRAMS_DIR }),
12 skills: ["/skills"],
13 bm25: true,
14 autoIndexPaths: ["/docs", "/skills"]
15});You can then add the workspace to your agent’s configuration giving the agent the capabilities defined by its workspace.
1// src/mastra/agents/diagram-agent.ts"
2
3import { Agent } from "@mastra/core/agent";
4import { diagramWorkspace } from "../workspace/diagram-workspace";
5
6export const diagramAgent = new Agent({
7 id: "diagram-agent",
8 name: "Diagram Agent",
9 model: "anthropic/claude-sonnet-4",
10 workspace: diagramWorkspace
11});The four capabilities
Filesystem gives agents access to files. With LocalFilesystem you point it at a directory and agents can read and write files in the defined location. If you only want them to read, set readOnly: true.
Sandbox is for running shell commands. LocalSandbox runs them locally with a configurable working directory and environment variables.
Skills are reusable instructions that follow the Agent Skills spec. Each skill is a SKILL.md file with optional reference docs and scripts. They teach agents how to do specific things like code review, design, or API interactions.
Search indexes content so agents can find things. You can use keyword search (BM25), semantic search (vector), or both. Point autoIndexPaths at directories you want indexed on startup.
For granular control, you can configure approval requirements per tool for example: WRITE_FILE or EXECUTE_COMMAND
1tools: {
2 [WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE]: {
3 requireApproval: true,
4 requireReadBeforeWrite: true,
5 },
6 [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
7 requireApproval: true,
8 },
9}See the permission controls docs for more details.
Diagram rendering demo
We put together a workspace demo to show how this all comes together.
It’s an agent with access to two skills: beautiful-mermaid teaches it to write Mermaid diagrams and convert them to SVGs using a render script, while mastra skills gives it framework knowledge so it can create diagrams about Mastra concepts. With additional docs files available to search which provide extra context.
The workspace has requireApproval enabled on EXECUTE_COMMAND, so the agent asks for permission before running the render script.
Workspace setup
Here's how the demo project is structured:
1diagram-demo/
2├── docs/ # Indexed for search
3├── skills/ # Indexed for search
4│ ├── beautiful-mermaid/
5│ │ ├── SKILL.md # Instructions for rendering diagrams
6│ │ ├── references/
7│ │ │ └── mermaid-syntax.md # Mermaid syntax reference
8│ │ └── scripts/
9│ │ └── render.ts # Script to convert .mmd to .svg
10│ └── mastra/
11│ ├── SKILL.md # Mastra framework knowledge
12│ └── references/
13│ └── ...
14└── svg/ # Output directory for rendered diagramsdiagram-demo/is the directory on disk the workspace allows access todocs/contains additional markdown files indexed for search to provide extra contextskills/contains the skills the agent can usebeautiful-mermaid/teaches agents how to write valid Mermaid syntax and run a render script to export to SVGmastra/provides framework knowledge so agents can create diagrams about Mastra concepts
svg/is where rendered diagrams are saved to disk
When you spin up Studio, you can also browse your workspace files and see which skills are available. The file browser shows the directory structure your agent has access to.
Same skills, different capabilities
In the demo we created two agents that have access to the same skills but with different permissions.
diagramWorkspace has a filesystem and sandbox permissions so it can execute scripts, but requires approval to do so.
1// src/mastra/workspace/diagram-workspace.ts
2export const diagramWorkspace = new Workspace({
3 id: "diagram-workspace",
4 name: "Diagram Rendering Workspace",
5 filesystem: new LocalFilesystem({ basePath: DIAGRAMS_DIR }),
6 sandbox: new LocalSandbox({ workingDirectory: DIAGRAMS_DIR }),
7 skills: ["/skills"],
8 bm25: true,
9 autoIndexPaths: ["/docs", "/skills"],
10 tools: {
11 [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
12 requireApproval: true
13 }
14 }
15});noSandboxWorkspace only has filesystem permissions.
1// src/mastra/workspace/no-sandbox-workspace.ts
2
3export const noSandboxWorkspace = new Workspace({
4 id: "no-sandbox-workspace",
5 filesystem: new LocalFilesystem({ basePath: DIAGRAMS_DIR }),
6 // No sandbox, can't execute scripts
7 skills: ["/skills"],
8 bm25: true,
9 autoIndexPaths: ["/docs", "/skills"]
10})If you ask both agents to create a diagram, diagramAgent reads the skills, asks for approval, then runs the render script to output an SVG. But noSandboxAgentcan only read skills and write files, but can't run the render script to produce SVGs.
The boundary is enforced by the workspace config, not by hoping the agent follows instructions. This lets you safely share skills across agents while giving each one only the capabilities it actually needs.
What's next?
We're working on remote sandboxes for running commands in isolated cloud environments, cloud filesystem providers like S3 and GCS, and workspace templates for common patterns.
Cloud sandboxes + multiple filesystems Run sandboxes in the cloud via providers like E2B. Compose multiple filesystems (S3, GCS, local) and mount them together so your agent sees one unified tree.
Scoped workspaces Give each conversation, or each user, their own isolated workspace. The agent's files, sandbox, and skills stay scoped to that session. Think Claude Desktop, but you control it.
Workspaces give your agents real guardrails so they can act safely, securely, and request approval when required. See the workspace documentation for more details.
