Skip to main content

BrowserViewer

The @mastra/browser-viewer package provides browser automation for CLI-based tools like agent-browser, browser-use, and browse. BrowserViewer launches Chrome via Playwright, exposes a Chrome DevTools Protocol (CDP) URL, and automatically injects it into CLI commands run through sandbox tools.

When to use BrowserViewer
Direct link to When to use BrowserViewer

Use BrowserViewer when your agent drives a browser through a CLI tool rather than an SDK. BrowserViewer handles:

  • Launching and managing Chrome for CLI tools to connect to
  • Automatic CDP URL injection into workspace_execute_command calls
  • Live screencast streaming to Studio
  • Thread-scoped browser isolation

For SDK-based browser automation, use AgentBrowser or Stagehand instead.

Quickstart
Direct link to Quickstart

Install @mastra/browser-viewer and the CLI tool your agent will use. BrowserViewer manages Chrome, but the CLI tool itself must be installed separately.

npm install @mastra/browser-viewer

Install the CLI tool in your workspace environment. This example uses browser-use:

pip install browser-use

Install the corresponding skill so the agent knows how to use the CLI:

npx skills add browser-use/browser-use --skill browser-use

Create a workspace with BrowserViewer and assign it to an agent:

src/mastra/index.ts
import { Mastra } from '@mastra/core/mastra'
import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'
import { LibSQLStore } from '@mastra/libsql'
import { Workspace, LocalSandbox } from '@mastra/core/workspace'
import { BrowserViewer } from '@mastra/browser-viewer'

const workspace = new Workspace({
  sandbox: new LocalSandbox({
    workingDirectory: './workspace',
  }),
  browser: new BrowserViewer({
    cli: 'browser-use',
    headless: false,
  }),
})

const browserAgent = new Agent({
  id: 'browser-agent',
  model: 'openai/gpt-5.6-sol',
  workspace,
  instructions: `You are a web automation assistant.
Use browser-use commands to navigate and interact with websites.`,
  memory: new Memory(),
})

export const mastra = new Mastra({
  agents: { browserAgent },
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
})

When the agent runs a browser CLI command, Mastra automatically launches Chrome, passes the CDP connection to the CLI, and starts streaming the screencast to Studio. For Browser Use, the agent can pass Python through stdin:

browser-use <<'PY'
print("Connected to the managed browser")
PY

How it works
Direct link to How it works

  1. The agent calls workspace_execute_command with a browser CLI command.
  2. Mastra detects the CLI command and launches Chrome via Playwright (if not already running).
  3. The CDP URL is injected into the command so the CLI connects to the managed browser.
  4. Screencast frames stream from page-level CDP sessions to Studio.

Supported CLIs
Direct link to Supported CLIs

BrowserViewer supports three CLI providers. Each CLI must be installed separately in your workspace environment. Each CLI also publishes a skill that teaches the agent its commands and workflows.

Set the cli option to match the CLI your agent uses:

const viewer = new BrowserViewer({
  cli: 'browser-use',
  headless: false,
})

agent-browser
Direct link to agent-browser

npm install -g agent-browser
npx skills add vercel-labs/agent-browser

CDP flag: --cdp

browser-use
Direct link to browser-use

pip install browser-use
npx skills add browser-use/browser-use --skill browser-use

For direct stdin invocations (browser-use, browseruse, browser, or bu, optionally followed by < redirection or a heredoc), Mastra sets BU_CDP_WS to the managed browser's CDP URL and BU_NAME to a stable daemon name. The name is unique to the thread and browser endpoint, so repeated calls reuse the same daemon while different threads or endpoints stay isolated. Mastra preserves the stdin script without adding CLI arguments.

Legacy subcommands retain --cdp-url and --session injection for compatibility. These flags aren't added to stdin invocations.

browse
Direct link to browse

npm install -g browse
browse skills install

CDP flag: --ws See BrowserViewer reference for all configuration options, advanced connection modes, and method details.

On this page