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 and project ID
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

​
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
BROWSERBASE_PROJECT_ID=your_browserbase_project_id_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:
  1. Creates a new workflow execution
  2. Provides monitoring URL for real-time tracking
  3. Executes browser automation with automatic retries
  4. Returns structured search results

​
Monitoring and Debugging

​
Using Temporal Web UI

1

Access Workflow Details

Click the monitoring URL provided when starting a workflow:
http://localhost:8233/namespaces/default/workflows/resilience-test-1640995200000
2

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)]}`);
  }
}

​
Troubleshooting Guide

​
What’s Next?

Now that you have a working Temporal + Browserbase integration:

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
Need help? Join the Temporal Community and Stagehand Slack for support and discussions.