@mastra/core/dist/docs/references/reference-editor-storage-workspace-ref.md

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

# 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's the type used by [`BuilderAgentDefaults.workspace`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) and by stored agent records.

## Usage example

```typescript
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".

**{ type: 'id'; workspaceId: string }.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".

**{ type: 'inline'; config: StorageWorkspaceSnapshotType }.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`): Auto-sync between filesystem and sandbox. (Default: `false`)

**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](https://mastra.ai/docs/agent-builder/workspace) — concept and worked examples.
- [BuilderAgentDefaults](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) — where this type is pinned as the Builder default.
- [MastraEditor class](https://mastra.ai/reference/editor/mastra-editor) — registers filesystem and sandbox providers.
- [StorageBrowserRef](https://mastra.ai/reference/editor/storage-browser-ref) — sibling reference type for browser configuration.