Workspace

note

The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. Contact sales for more information.

A workspace gives agents filesystem access, command execution, and skill loading. The Agent Builder pins a default workspace onto every new agent through builder.configuration.agent.workspace. End users can still override the workspace per agent through the Builder UI.

Quickstart

Pin an inline workspace snapshot as the Builder default:

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraEditor } from '@mastra/editor'

export const mastra = new Mastra({
  editor: new MastraEditor({
    builder: {
      enabled: true,
      configuration: {
        agent: {
          workspace: {
            type: 'inline',
            config: {
              name: 'project-workspace',
              filesystem: {
                provider: 'local',
                config: { basePath: './workspace' },
              },
            },
          },
        },
      },
    },
  }),
})

The Builder derives a deterministic id from the inline config and persists the snapshot, so identical inline configs are deduplicated across agents.

Workspace references

configuration.agent.workspace accepts a StorageWorkspaceRef:

• { type: 'inline', config } — embeds a serialized workspace snapshot directly on the agent. Useful for per-agent, ad-hoc configurations.
• { type: 'id', workspaceId } — references a workspace already registered on the Mastra instance via new Mastra({ workspace }) or mastra.addWorkspace(...). Use this for shared, named workspaces.

See the StorageWorkspaceRef reference for both variants.

Filesystem and sandbox

A workspace combines a filesystem (file tools) and an optional sandbox (command execution). For local development, point both at the same directory so files written through the filesystem are immediately visible to commands in the sandbox.

For cloud deployments, swap LocalFilesystem / LocalSandbox for managed providers (e.g., S3, E2B). See Deploying for the cloud-swap pattern.

Related

• Workspace overview — the underlying workspace model.
• Filesystem and Sandbox — the building blocks.
• BuilderAgentDefaults reference — the full workspace field schema.
• Configuration — wire workspace alongside the rest of the Builder config.