StorageWorkspaceRef

StorageWorkspaceRef is the discriminated union used to attach a workspace to a stored agent. It either points at a workspace registered on the Mastra runtime by ID, or embeds a workspace snapshot inline.

It is the type used by BuilderAgentDefaults.workspace and by stored agent records.

Usage example

src/mastra/index.ts

import { MastraEditor } from '@mastra/editor'

// Variant 1 — reference a runtime workspace by id
new MastraEditor({
  builder: {
    enabled: true,
    configuration: {
      agent: {
        workspace: { type: 'id', workspaceId: 'builder-workspace' },
      },
    },
  },
})

// Variant 2 — inline a workspace snapshot
new MastraEditor({
  builder: {
    enabled: true,
    configuration: {
      agent: {
        workspace: {
          type: 'inline',
          config: {
            name: 'inline-builder-workspace',
            filesystem: {
              provider: 'local',
              config: { basePath: './agent-files' },
            },
          },
        },
      },
    },
  },
})

Variants

{ type: 'id'; workspaceId: string }:

IdRef

Reference a workspace registered on the Mastra runtime via `new Mastra({ workspace })` or `mastra.addWorkspace()`. The id is the join key between admin config, stored agent record, and hydration.

{ type: 'id'; workspaceId: string }

type:

'id'

Discriminant. Must be the literal `"id"`.

workspaceId:

string

Id of a workspace registered on the Mastra runtime. Used by the Builder to snapshot, persist, and later hydrate the workspace.

{ type: 'inline'; config: StorageWorkspaceSnapshotType }:

InlineRef

Embed a workspace snapshot directly. The Builder derives a deterministic id of the form `inline-<sha256(config)[:12]>` and persists the snapshot, so identical inline configs are deduplicated across agents.

{ type: 'inline'; config: StorageWorkspaceSnapshotType }

type:

'inline'

Discriminant. Must be the literal `"inline"`.

config:

StorageWorkspaceSnapshotType

Serialized workspace configuration (filesystem, sandbox, mounts, search, skills, tools). See the `StorageWorkspaceSnapshotType` section below for the field list.

StorageWorkspaceSnapshotType

The shape embedded under { type: 'inline', config }. Defined in @mastra/core/storage.

name:

string

Display name of the workspace.

description?:

string

Purpose description shown in the workspace listing.

filesystem?:

StorageFilesystemConfig

Primary filesystem configuration. `provider` must match an id registered on `MastraEditor.filesystems` (built-in: `local`).

sandbox?:

StorageSandboxConfig

Sandbox configuration. `provider` must match an id registered on `MastraEditor.sandboxes` (built-in: `local`).

mounts?:

Record<string, StorageFilesystemConfig>

Additional filesystems mounted on the workspace, keyed by mount path.

search?:

StorageSearchConfig

Search configuration (vector provider, embedder, BM25 settings).

skills?:

string[]

Skill entity IDs assigned to this workspace.

tools?:

StorageWorkspaceToolsConfig

Workspace tool configuration (allowlists, defaults).

autoSync?:

boolean

= false

Auto-sync between filesystem and sandbox.

operationTimeout?:

number

Timeout for individual operations in milliseconds.

Hydration

StorageWorkspaceRef is resolved lazily on mastra.editor.agent.getById(), not on list(). The editor looks up filesystem and sandbox providers on MastraEditor.filesystems / MastraEditor.sandboxes and materializes a runtime Workspace. Missing providers surface as a warning and the workspace is omitted.

Related

• Workspace — concept and worked examples.
• BuilderAgentDefaults — where this type is pinned as the Builder default.
• MastraEditor class — registers filesystem and sandbox providers.
• StorageBrowserRef — sibling reference type for browser configuration.