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

# Browser

Browser support enables agents to move through websites, interact with page elements, fill forms, and extract data. Mastra provides browser capabilities through SDK providers that wrap browser automation libraries and a CLI provider for agents that drive browsers through command-line tools.

Mastra supports three SDK providers and one CLI provider:

- [**AgentBrowser**](https://mastra.ai/integrations/browsers/agent-browser): A Playwright-based provider with accessibility-first element targeting. Best for general web automation and scraping.
- [**Stagehand**](https://mastra.ai/integrations/browsers/stagehand): A Browserbase provider with AI-powered element detection. Best for complex interactions that benefit from natural language selectors.
- [**FirecrawlBrowser**](https://mastra.ai/integrations/browsers/firecrawl): A Firecrawl Browser Sandbox provider that runs AgentBrowser tools against hosted browser sessions. Best for running automation on hosted browser sessions without managing local browser infrastructure.
- [**BrowserViewer**](https://mastra.ai/integrations/browsers/browser-viewer): A CLI provider that launches Chrome and injects CDP URLs into CLI tools like agent-browser, browser-use, and browse. Best for workspace agents that drive browsers through shell commands.

## When to use browser

Use browser when your agent needs to:

- Navigate websites and interact with page elements
- Fill out forms and submit data
- Extract structured data from web pages
- Automate multi-step web workflows
- Take actions that require a real browser (JavaScript rendering, authentication flows)

## How it works

When you assign a browser to an agent, Mastra includes the provider's tools in the agent's toolset. The agent uses these tools to control the browser. It can open URLs and select elements. It can also type text and read page content.

Each provider offers a different set of tools optimized for its approach.

## Quickstart

Install your provider of choice, for this example you'll use the AgentBrowser provider.

**npm**:

```bash
npm install @mastra/agent-browser
```

**pnpm**:

```bash
pnpm add @mastra/agent-browser
```

**Yarn**:

```bash
yarn add @mastra/agent-browser
```

**Bun**:

```bash
bun add @mastra/agent-browser
```

Create a new browser instance:

```typescript
import { AgentBrowser } from '@mastra/agent-browser'

export const browser = new AgentBrowser({
  headless: false,
})
```

Assign the browser to an agent:

```typescript
import { Agent } from '@mastra/core/agent'
import { browser } from '../browsers'

export const webAgent = new Agent({
  id: 'web-agent',
  name: 'Web Agent',
  description: 'A web automation assistant that can navigate websites and complete tasks.',
  model: 'openai/gpt-5.6-sol',
  browser,
  instructions:
    'You are a web automation assistant. Use browser tools to navigate websites and complete tasks.',
})
```

The agent automatically receives all browser tools from the provider.

## Cloud providers

All SDK providers support connecting to cloud browser services instead of launching a local browser.

### Firecrawl Browser Sandbox (FirecrawlBrowser native)

FirecrawlBrowser provisions hosted sessions through the Firecrawl API:

```typescript
import { FirecrawlBrowser } from '@mastra/browser-firecrawl'

const browser = new FirecrawlBrowser({
  apiKey: process.env.FIRECRAWL_API_KEY,
})
```

### Browserbase (Stagehand native)

Stagehand has native Browserbase integration:

```typescript
import { StagehandBrowser } from '@mastra/stagehand'

const browser = new StagehandBrowser({
  env: 'BROWSERBASE',
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
})
```

### CDP URL (any provider)

Connect to any browser exposing a Chrome DevTools Protocol (CDP) endpoint:

```typescript
import { AgentBrowser } from '@mastra/agent-browser'

const browser = new AgentBrowser({
  cdpUrl: process.env.BROWSER_CDP_URL,
  headless: true,
})
```

This works with any [CDP-compatible](https://chromedevtools.github.io/devtools-protocol/) browser service.

## Screencast

Browser providers stream a live video feed of the browser to the Mastra Studio UI. This lets you watch the agent interact with pages in real-time.

Screencast requires WebSocket support. Install these packages in your project:

**npm**:

```bash
npm install ws @hono/node-ws
```

**pnpm**:

```bash
pnpm add ws @hono/node-ws
```

**Yarn**:

```bash
yarn add ws @hono/node-ws
```

**Bun**:

```bash
bun add ws @hono/node-ws
```

> **Note:** These packages aren't included by default because they're incompatible with serverless environments like Cloudflare Workers. If they aren't installed, screencast is disabled but all other browser functionality works normally.

Screencast is enabled by default and can be configured:

```typescript
const browser = new AgentBrowser({
  screencast: {
    enabled: true,
    format: 'jpeg',
    quality: 80,
    maxWidth: 1280,
    maxHeight: 720,
  },
})
```

## Record browser sessions

> **Beta:** Breaking changes may occur without a major version bump until the API is stable.

AgentBrowser and StagehandBrowser can opt into recording for reviewing, sharing, or debugging browser runs. Configure `outputDir` to add the recording tools:

```typescript
import { join } from 'node:path'
import { AgentBrowser } from '@mastra/agent-browser'

export const browser = new AgentBrowser({
  recording: {
    outputDir: join(process.cwd(), 'browser-recordings'),
  },
})
```

StagehandBrowser accepts the same `recording` option. The agent uses `browser_record` to start, check, and stop a recording, and `browser_record_caption` to label major actions. Stopping saves the video and lets the agent return its path. A custom `outputPath` must be absolute and stay inside `recording.outputDir`.

Recordings use Motion-JPEG AVI and don't require `ffmpeg`. The default maximum duration is 30 seconds, with a 120-second hard cap. The default maximum frame size is 1024 × 720, captions are limited to 80 characters, and only one recording can be active per process.

## Next steps

- [AgentBrowser](https://mastra.ai/integrations/browsers/agent-browser)
- [Stagehand](https://mastra.ai/integrations/browsers/stagehand)
- [Firecrawl](https://mastra.ai/integrations/browsers/firecrawl)
- [BrowserViewer](https://mastra.ai/integrations/browsers/browser-viewer)
- [MastraBrowser reference](https://mastra.ai/reference/browser/mastra-browser)
- 📹 [Mastra browser capabilities workshop](https://www.youtube.com/watch?v=E9KFsZEnQO8\&t=5s)