Skip to main content

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
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:
  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

Error: Error: 14 UNAVAILABLE: failed to connect to all addressesRoot Cause: Temporal server not running or port conflictsSolutions:
  1. Start Temporal server: temporal server start-dev
  2. Check port 7233 is available: lsof -i :7233
  3. Kill conflicting processes if needed
  4. Restart the server completely
Error: Worker failed to start or connection timeoutsRoot Cause: Worker cannot connect to Temporal serverSolutions:
  1. Ensure Temporal server started successfully first
  2. Verify task queue name: browser-automation
  3. Check network connectivity to localhost:7233
  4. Restart worker after server is stable
Error: Failed to initialize browser or Browserbase errorsRoot Cause: Invalid API credentials or quota limitsSolutions:
  1. Verify your API key in .env
  2. Check Browserbase account credits/quota
  3. Test API credentials with curl request
  4. Try a different Browserbase project
Error: Extraction returned null values or validation failuresRoot Cause: AI API issues or rate limitingSolutions:
  1. Verify Anthropic API key validity
  2. Check API rate limits and credits
  3. Simplify extraction instructions
  4. Consider switching to OpenAI as fallback
Error: Workflows hang or don’t progressRoot Cause: Worker issues or activity timeoutsSolutions:
  1. Check worker is processing tasks (npm run worker)
  2. Inspect workflow state in Web UI
  3. Look for timeout errors in activity logs
  4. Increase timeout values if needed
  5. Restart worker if necessary

​
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.