Quickstart - Browserbase Documentation

What You'll Build

A production-ready browser automation system that can handle failures gracefully using Temporal’s workflow orchestration and Browserbase’s cloud browsers.

Before you start

Ensure you have these requirements ready:

Node.js 18+

Required runtime environment

Temporal CLI

Install: brew install temporal

API Access

Browserbase API key

Required: The Temporal CLI must be installed and available in your PATH before proceeding.

Step 1: Project setup

Clone and install

# Clone the integration template
npx degit browserbase/integrations/examples/integrations/temporal browserbase-temporal
cd browserbase-temporal

# Install all dependencies
npm install

# Install browser binaries
npx playwright install

What gets installed?

Core Temporal packages:

@temporalio/worker - Workflow execution engine
@temporalio/workflow - Workflow definitions
@temporalio/activity - Activity implementations

Browser automation:

@browserbasehq/stagehand - AI-powered browser control
playwright - Browser automation engine

AI integration:

@anthropic-ai/sdk - Claude API client
zod - Schema validation

Step 2: Configuration

Environment variables

Create your .env file with the required API keys:

# Browserbase Configuration (Required)
BROWSERBASE_API_KEY=your_browserbase_api_key_here

# AI Provider (Required)
OPENAI_API_KEY=your_openai_api_key_here

# Temporal Configuration (Optional)
TEMPORAL_ADDRESS=localhost:7233
TEMPORAL_NAMESPACE=default

# Worker Configuration (Optional)
MAX_CONCURRENT_ACTIVITIES=2
TASK_QUEUE=browser-automation

Step 3: Start Temporal Server

Launch development server

temporal server start-dev

Keep this terminal open - The Temporal server must run continuously during development.

Step 4: Run your first workflow

Start the worker process

In a new terminal (keep Temporal server running):

npm run worker

Expected output:

Polling for tasks on queue: browser-automation
Worker ready with activities: initializeBrowser, navigateToSearchPage, executeSearch, extractSearchResults, cleanupBrowser, formatResults

Execute a search workflow

In a third terminal, run the demo:

# Basic search
npm run demo

# Custom search query
npm run demo "Temporal workflow patterns"

What happens:

Creates a new workflow execution
Provides monitoring URL for real-time tracking
Executes browser automation with automatic retries
Returns structured search results

Monitoring and debugging

Using Temporal web UI

Access workflow details

Click the monitoring URL provided when starting a workflow:

http://localhost:8233/namespaces/default/workflows/resilience-test-1640995200000

Inspect execution timeline

The Web UI shows:

Visual timeline of activity execution
Event history with detailed logs
Input/output data for each activity
Retry attempts and failure reasons

Testing resilience

The integration includes built-in failure simulation for testing:

// Each activity has 15% chance of network failure
function simulateNetworkDisconnect(stage: string): void {
  if (Math.random() < 0.15) {
    const failures = [
      "ECONNRESET: Connection reset by peer",
      "ETIMEDOUT: Connection timed out",
      "ENOTFOUND: DNS lookup failed",
      "ECONNREFUSED: Connection refused",
    ];
    throw new Error(
      `Network failure during ${stage}: ${failures[Math.floor(Math.random() * failures.length)]}`,
    );
  }
}

# Run several times to trigger different failure patterns
npm run demo "test query 1"
npm run demo "test query 2" 
npm run demo "test query 3"

# Watch the Web UI to observe retry behavior

Troubleshooting guide

Temporal server connection failed

Error: Error: 14 UNAVAILABLE: failed to connect to all addressesRoot Cause: Temporal server not running or port conflictsSolutions:

Start Temporal server: temporal server start-dev
Check port 7233 is available: lsof -i :7233
Kill conflicting processes if needed
Restart the server completely

Worker failed to start

Error: Worker failed to start or connection timeoutsRoot Cause: Worker cannot connect to Temporal serverSolutions:

Ensure Temporal server started successfully first
Verify task queue name: browser-automation
Check network connectivity to localhost:7233
Restart worker after server is stable

Browser session creation failed

Error: Failed to initialize browser or Browserbase errorsRoot Cause: Invalid API credentials or quota limitsSolutions:

Verify your API key in .env
Check Browserbase account credits/quota
Test API credentials with curl request
Try a different Browserbase project

AI extraction returns null

Error: Extraction returned null values or validation failuresRoot Cause: AI API issues or rate limitingSolutions:

Verify Anthropic API key validity
Check API rate limits and credits
Simplify extraction instructions
Consider switching to OpenAI as fallback

Workflow appears stuck

Error: Workflows hang or don’t progressRoot Cause: Worker issues or activity timeoutsSolutions:

Check worker is processing tasks (npm run worker)
Inspect workflow state in Web UI
Look for timeout errors in activity logs
Increase timeout values if needed
Restart worker if necessary

Expected output

The worker reports that it is polling the browser-automation task queue. The demo prints a workflow monitoring URL and structured search results. Open the Temporal Web UI to confirm the workflow completed and inspect any retries.

Cleanup

Let the workflow finish and confirm that its browser cleanup activity ran. Cancel unfinished test workflows before stopping the worker and the local Temporal development server with Ctrl+C in each terminal. Release any remaining Browserbase sessions using Manage browser sessions.

Need help? Join the Temporal Community and Stagehand Slack for support and discussions.

Build custom workflows

Create your own workflows for specific automation tasks

Production deployment

Deploy to Temporal Cloud for production workloads

Advanced patterns

Explore child workflows, signals, and queries

Monitoring & alerting

Set up production monitoring and alerting

What You'll Build

​Before you start

Node.js 18+

Temporal CLI

API Access

​Step 1: Project setup

​Clone and install

​Step 2: Configuration

​Environment variables

​Step 3: Start Temporal Server

​Launch development server

​Step 4: Run your first workflow

​Start the worker process

​Execute a search workflow

​Monitoring and debugging

​Using Temporal web UI

​Testing resilience

​Troubleshooting guide

​Expected output

​Cleanup

​Related guides

Build custom workflows

Production deployment

Advanced patterns

Monitoring & alerting

Before you start

Step 1: Project setup

Clone and install

Step 2: Configuration

Environment variables

Step 3: Start Temporal Server

Launch development server

Step 4: Run your first workflow

Start the worker process

Execute a search workflow

Monitoring and debugging

Using Temporal web UI

Testing resilience

Troubleshooting guide

Expected output

Cleanup

Related guides