StorageBrowserRef

StorageBrowserRef is the inline browser configuration attached to a stored agent. The provider id is resolved at hydration time against the BrowserProvider registered on MastraEditor.browsers.

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

Usage example

src/mastra/index.ts

import { MastraEditor } from '@mastra/editor'
import { stagehandBrowserProvider } from '@mastra/stagehand'

new MastraEditor({
  browsers: { [stagehandBrowserProvider.id]: stagehandBrowserProvider },
  builder: {
    enabled: true,
    configuration: {
      agent: {
        browser: {
          type: 'inline',
          config: {
            provider: 'stagehand',
            headless: true,
            viewport: { width: 1280, height: 720 },
          },
        },
      },
    },
  },
})

Type

type StorageBrowserRef = { type: 'inline'; config: StorageBrowserConfig }

There is no { type: 'id' } variant for browsers — they are always inlined.

Properties

type:

'inline'

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

config:

StorageBrowserConfig

Provider id and per-instance browser configuration. See the section below.

StorageBrowserConfig

The shape embedded under config. Defined in @mastra/core/storage.

provider:

string

Provider identifier (for example, `"stagehand"`). Must match a `BrowserProvider.id` registered on `MastraEditor.browsers`. There are no built-in providers.

headless?:

boolean

= true

Run the browser in headless mode (no visible UI).

viewport?:

{ width: number; height: number }

Browser viewport dimensions. Controls window size and how pages render.

timeout?:

number

= 10000

Default timeout in milliseconds for browser operations.

screencast?:

ScreencastOptions

Screencast options for streaming browser frames to the UI.

ScreencastOptions

format?:

'jpeg' | 'png'

Image format.

quality?:

number

JPEG quality 0–100.

maxWidth?:

number

Max width in pixels.

maxHeight?:

number

Max height in pixels.

everyNthFrame?:

number

Capture every Nth frame.

Hydration

StorageBrowserRef is resolved lazily on mastra.editor.agent.getById(). The editor looks up config.provider on MastraEditor.browsers and calls provider.createBrowser(config). If the provider is not registered, the editor logs a warning and returns undefined — the agent still loads, but without a browser.

Related

• Browser — concept and worked examples.
• BrowserProvider — implementer-facing provider interface.
• BuilderAgentDefaults — where this type is pinned as the Builder default.
• StorageWorkspaceRef — sibling reference type for workspace configuration.