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://browse.uranus.im/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}

Providers

Headless automation always runs on the Cloudflare Browser Run provider (lib/browser-cf.ts, the BROWSER binding driven with @cloudflare/puppeteer). Sessions are addressable by id across Worker invocations, so a session survives Durable Object eviction; a session that has expired is soft-reconnected (new session with cookies replayed). Live view and human takeover use Cloudflare's hosted Live View and handoff events (see Human-in-the-Loop); the dashboard shows an Open Live View button for live.browser.run URLs and keeps the iframe for the custom /cf-live screencast bridge, which is only a fallback when the CDP command is unavailable.

Session recordings: settings.browser.recording = true (Settings → Runtime) launches sessions with recording on; Browser Run keeps a replayable recording of each session for 30 days (Cloudflare dashboard → Browser Run → Runs). Default off.

Steel remains available for human-in-the-loop sessions when settings.browser.hitlProvider is steel.

Integration with Steel Browser

Uranus can use Steel Browser (open-source) for HITL sessions:

• Self-hosted browser infrastructure
• Full CDP (Chrome DevTools Protocol) control
• Session context persistence (cookies, localStorage, IndexedDB)
• Human-in-the-loop support
• Session recording and live debugging
• Anti-detection and fingerprint management

Configuration

[vars]
STEEL_API_KEY = "your_steel_api_key"
BROWSER_API_URL = "https://browse.uranus.im"

Two-Tier Browser Strategy

Tool	Use Case	Session State
browser_render	Public pages, quick scraping	Stateless
browser_context	Login-required sites, multi-step flows	Persistent

browser_render: Lightweight, fast execution for public pages. No session state preserved.

browser_context: Full session with cookies, localStorage, and IndexedDB persistence. Use for sites requiring authentication or multi-step workflows.

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 Steel Browser API key configuration
• Verify browser service is running (browse.uranus.im)
• Check network connectivity
• Review browser service logs

Actions Failing

• Increase timeout values
• Verify selectors using browser DevTools
• Check page load state
• Look for anti-bot detection (try enabling stealth mode)

Live View Not Loading

• Verify session is active
• Check live view URL expiration
• Confirm browser service status
• Check WebSocket connectivity

Session Context Not Persisting

• Ensure using browser_context (not browser_render)
• Verify cookies are being set correctly
• Check for SameSite cookie restrictions
• Review session context extraction logs