StorageWorkspaceRef

StorageWorkspaceRef is the discriminated union used to attach a workspace to a stored agent. It points at a workspace registered on the Mastra runtime by ID, embeds a workspace snapshot inline, or names a workspace provider registered on MastraEditor.workspaces that builds the workspace.

It's 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' },
            },
          },
        },
      },
    },
  },
})

// Variant 3 — build the workspace with a registered workspace provider
new MastraEditor({
  workspaces: { 'my-provider': myWorkspaceProvider },
  builder: {
    enabled: true,
    configuration: {
      agent: {
        workspace: {
          type: 'provider',
          provider: 'my-provider',
          config: { region: 'us-east-1' },
        },
      },
    },
  },
})

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.

{ type: 'provider'; provider: string; config: Record<string, unknown> }:

ProviderRef

Build the entire workspace with a workspace provider registered on MastraEditor.workspaces. The ref is stored as-is in the agent snapshot; no separate workspace record is persisted.

{ type: 'provider'; provider: string; config: Record<string, unknown> }

type:

'provider'

Discriminant. Must be the literal "provider".

provider:

string

Id of a workspace provider registered via new MastraEditor({ workspaces }).

config:

Record<string, unknown>

Provider-specific configuration passed to the provider's createWorkspace(config).

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. For { type: 'provider' } refs, the editor calls createWorkspace(config) on the provider registered on MastraEditor.workspaces. An unregistered provider throws an error.

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.