Browser Sessions

Browser sessions enable web automation with full browser control.

Overview

Features:

• Headless and headed modes
• Live view monitoring
• Human takeover capability
• Action recording
• Screenshot capture
• Content extraction

Creating Sessions

Via Dashboard

1. Navigate to Browser
2. Click New Session
3. Configure options:
   • Headless mode
   • Viewport size
   • User agent
4. Click Create

Via API

curl -X POST https://your-domain.com/api/agents/{id}/browser \
  -H "Content-Type: application/json" \
  -d '{
    "headless": true,
    "viewport": {
      "width": 1280,
      "height": 720
    }
  }'

Response:

{
  "id": "session-123",
  "status": "active",
  "created_at": "2024-12-15T10:00:00Z",
  "live_view_url": "https://..."
}

Session Configuration

Options

Option	Description	Default
headless	Run without UI	true
viewport.width	Browser width	1280
viewport.height	Browser height	720
user_agent	Custom user agent	(default)
timeout	Action timeout (ms)	30000

Browser Settings

Configure in agent settings:

{
  "browser_headless": true,
  "browser_viewport_width": 1920,
  "browser_viewport_height": 1080,
  "browser_user_agent": "Mozilla/5.0...",
  "browser_default_timeout": 60000
}

Live View

Accessing Live View

1. Open session details
2. Click Live View
3. Watch browser activity in real-time

Live View URL

curl https://your-domain.com/api/agents/{id}/browser/{sessionId}/live-view

Response:

{
  "url": "https://browserbase.com/live/session-123",
  "expires_at": "2024-12-15T11:00:00Z"
}

Session Lifecycle

┌─────────────┐
│   Created   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Active    │◀──────────────┐
└──────┬──────┘               │
       │                      │
       ├─────────────────────►│
       │  Execute Actions     │
       │                      │
       ▼                      │
┌─────────────┐               │
│   Paused    │───────────────┘
└──────┬──────┘  Resume
       │
       ▼
┌─────────────┐
│   Closed    │
└─────────────┘

Session Status

Status	Description
active	Session running, ready for actions
paused	Temporarily paused
closed	Session ended
error	Session failed
takeover	Human control active

Managing Sessions

List Sessions

curl https://your-domain.com/api/agents/{id}/browser

Get Session Details

curl https://your-domain.com/api/agents/{id}/browser/{sessionId}

Delete Session

curl -X DELETE https://your-domain.com/api/agents/{id}/browser?id={sessionId}

Integration with Browserbase

Uranus integrates with Browserbase for:

• Managed browser infrastructure
• Human-in-the-loop support
• Session recording
• Live debugging

Configuration

[vars]
BROWSERBASE_PROJECT_ID = "your_project_id"
BROWSERBASE_API_KEY = "your_api_key"

Best Practices

1. Use Headless Mode

For automation without visual output:

{
  "headless": true
}

2. Set Appropriate Timeouts

Adjust for slow pages:

{
  "timeout": 60000
}

3. Clean Up Sessions

Close sessions when done:

curl -X DELETE .../browser?id={sessionId}

4. Monitor Active Sessions

Track session metrics:

• Active count
• Duration
• Action success rate

5. Handle Errors

Implement retry logic:

• Network timeouts
• Element not found
• Page load failures

Troubleshooting

Session Won't Start

• Check Browserbase credentials
• Verify quota availability
• Check network connectivity

Actions Failing

• Increase timeout values
• Verify selectors
• Check page load state

Live View Not Loading

• Verify session is active
• Check live view URL expiration
• Confirm Browserbase status