> ## Documentation Index
> Fetch the complete documentation index at: https://docs.browserbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get production-ready browser agents with automatic retries and failure recovery

<Card title="What You'll Build" icon="rocket" horizontal>
  A production-ready browser automation system that can handle failures gracefully using Temporal's workflow orchestration and Browserbase's cloud browsers.
</Card>

## Before you start

Ensure you have these requirements ready:

<CardGroup cols={3}>
  <Card title="Node.js 18+" icon="node-js" href="https://nodejs.org/">
    Required runtime environment
  </Card>

  <Card title="Temporal CLI" icon="terminal" href="https://docs.temporal.io/cli">
    Install: `brew install temporal`
  </Card>

  <Card title="API Access" icon="key" href="https://www.browserbase.com/overview">
    Browserbase API key
  </Card>
</CardGroup>

<Warning>
  **Required**: The Temporal CLI must be installed and available in your PATH before proceeding.
</Warning>

## Step 1: Project setup

### Clone and install

```bash theme={null}
# 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
```

<Accordion title="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
</Accordion>

## Step 2: Configuration

### Environment variables

Create your `.env` file with the required API keys:

```bash theme={null}
# 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

```bash theme={null}
temporal server start-dev
```

<Info>
  **Keep this terminal open** - The Temporal server must run continuously during development.
</Info>

## Step 4: Run your first workflow

### Start the worker process

In a **new terminal** (keep Temporal server running):

```bash theme={null}
npm run worker
```

**Expected output:**

```bash theme={null}
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:

```bash theme={null}
# 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

<Steps>
  <Step title="Access workflow details">
    Click the monitoring URL provided when starting a workflow:

    ```
    http://localhost:8233/namespaces/default/workflows/resilience-test-1640995200000
    ```
  </Step>

  <Step title="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
  </Step>
</Steps>

### Testing resilience

The integration includes built-in failure simulation for testing:

<CodeGroup>
  ```typescript Network Failure Simulation theme={null}
  // 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)]}`);
    }
  }
  ```

  ```bash Testing Multiple Scenarios theme={null}
  # 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
  ```
</CodeGroup>

## Troubleshooting guide

<AccordionGroup>
  <Accordion title="Temporal server connection failed" icon="server">
    **Error**: `Error: 14 UNAVAILABLE: failed to connect to all addresses`

    **Root Cause**: Temporal server not running or port conflicts

    **Solutions**:

    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
  </Accordion>

  <Accordion title="Worker failed to start" icon="gear">
    **Error**: `Worker failed to start` or connection timeouts

    **Root Cause**: Worker cannot connect to Temporal server

    **Solutions**:

    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
  </Accordion>

  <Accordion title="Browser session creation failed" icon="browser">
    **Error**: `Failed to initialize browser` or Browserbase errors

    **Root Cause**: Invalid API credentials or quota limits

    **Solutions**:

    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
  </Accordion>

  <Accordion title="AI extraction returns null" icon="brain">
    **Error**: `Extraction returned null values` or validation failures

    **Root Cause**: AI API issues or rate limiting

    **Solutions**:

    1. Verify Anthropic API key validity
    2. Check API rate limits and credits
    3. Simplify extraction instructions
    4. Consider switching to OpenAI as fallback
  </Accordion>

  <Accordion title="Workflow appears stuck" icon="clock">
    **Error**: Workflows hang or don't progress

    **Root Cause**: Worker issues or activity timeouts

    **Solutions**:

    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
  </Accordion>
</AccordionGroup>

## What's next?

Now that you have a working Temporal + Browserbase integration:

<CardGroup cols={2}>
  <Card title="Build custom workflows" icon="code" href="https://docs.temporal.io/docs/workflows">
    Create your own workflows for specific automation tasks
  </Card>

  <Card title="Production deployment" icon="server" href="https://docs.temporal.io/docs/production-deployment">
    Deploy to Temporal Cloud for production workloads
  </Card>

  <Card title="Advanced patterns" icon="brain" href="https://docs.temporal.io/child-workflows">
    Explore child workflows, signals, and queries
  </Card>

  <Card title="Monitoring & alerting" icon="bell" href="https://docs.temporal.io/cloud/high-availability/monitor#observe">
    Set up production monitoring and alerting
  </Card>
</CardGroup>

***

<Info>
  **Need help?** Join the [Temporal Community](https://temporal.io/community) and [Stagehand Slack](https://stagehand.dev/slack) for support and discussions.
</Info>