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 workspace 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 { 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.4',
  workspace,
  instructions: `You are a web automation assistant.
Use browser-use commands to navigate and interact with websites.`,
})

export const mastra = new Mastra({
  agents: { browserAgent },
})

When the agent runs a CLI command like browser-use open https://example.com, Mastra automatically launches Chrome, injects the CDP connection, and starts streaming the screencast to Studio.

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.

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

CDP flag: --cdp-url

browse-cli
Direct link to browse-cli

npm install -g @browserbasehq/browse-cli
npx skills add browserbase/skills

CDP flag: --ws

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

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

See BrowserViewer reference for all configuration options, advanced connection modes, and method details.

On this page