---
name: Hyperbrowser
description: Use when automating browser tasks at scale, scraping websites,
  running AI agents for web automation, or controlling cloud browsers with
  Playwright/Puppeteer. Reach for this skill for tasks requiring bot detection
  evasion, CAPTCHA solving, proxy rotation, multi-page workflows, or AI-powered
  browser automation.
metadata:
  mintlify-proj: hyperbrowser
  version: "1.0"
---

# Hyperbrowser Skill

## Product Summary

Hyperbrowser is a cloud browser platform for running automated browser sessions at scale. Control Chrome browsers in the cloud using Playwright, Puppeteer, or the Hyperbrowser SDK—no infrastructure management required. Use it to scrape websites, run AI agents (HyperAgent, Claude Computer Use, BrowserUse, Gemini, etc.), extract structured data, and automate complex web workflows. Key files: SDKs available for Node.js (`@hyperbrowser/sdk`) and Python (`hyperbrowser`). Primary docs: https://hyperbrowser.ai/docs

## When to Use

Reach for Hyperbrowser when you need to:

- **Automate browser tasks at scale** — Create and manage hundreds of cloud browser sessions without managing infrastructure
- **Scrape websites** — Extract data from pages using the Scrape, Crawl, or Extract APIs
- **Run AI agents** — Execute HyperAgent, Claude Computer Use, BrowserUse, Gemini, or other AI agents on cloud browsers
- **Evade bot detection** — Use stealth mode, proxies, and CAPTCHA solving for sites with anti-bot protections
- **Persist browser state** — Save and reuse profiles with cookies and authentication across sessions
- **Handle complex workflows** — Manage multi-page navigation, form filling, and data extraction in a single task
- **Monitor automation** — Watch sessions live, record activity, and debug failures with video playback

## Quick Reference

### Session Creation (SDK)

| Language | Command |
|----------|---------|
| Node.js | `const session = await client.sessions.create({ useStealth: true, useProxy: true })` |
| Python | `session = client.sessions.create({"use_stealth": True, "use_proxy": True})` |
| cURL | `POST /api/session` with JSON body |

### Common Session Options

| Option | Type | Purpose |
|--------|------|---------|
| `useStealth` | boolean | Enable standard bot detection evasion |
| `useUltraStealth` | boolean | Maximum evasion (enterprise only) |
| `useProxy` | boolean | Route traffic through proxy |
| `proxyCountry` | string | Proxy location (e.g., "US", "GB") |
| `solveCaptchas` | boolean | Auto-solve CAPTCHA challenges |
| `acceptCookies` | boolean | Auto-accept cookie consent |
| `screen` | object | Viewport size: `{width: 1280, height: 720}` |
| `timeoutMinutes` | number | Session timeout (1-720 min) |
| `profile.id` | string | Reuse saved profile with cookies |

### Web Scraping APIs

| API | Use Case |
|-----|----------|
| `client.scrape.startAndWait()` | Single page scrape (markdown, HTML, links) |
| `client.scrape.batch.startAndWait()` | Batch scrape up to 1,000 URLs |
| `client.web.crawl.startAndWait()` | Multi-page crawl with schema extraction |
| `client.web.extract.startAndWait()` | Extract structured data with Zod/Pydantic |

### AI Agent Methods

| Agent | SDK Path | Best For |
|-------|----------|----------|
| HyperAgent | `client.agents.hyperAgent.startAndWait()` | Playwright-based, cost-effective, extensible |
| BrowserUse | `client.agents.browserUse.startAndWait()` | Fast, open-source, DOM-focused |
| Claude Computer Use | `client.agents.claudeComputerUse.startAndWait()` | Robust, reliable, multi-step workflows |
| OpenAI CUA | `client.agents.cua.startAndWait()` | Accurate, slower, complex reasoning |
| Gemini Computer Use | `client.agents.geminiComputerUse.startAndWait()` | Fast, broad tool set |
| Meta Computer Use | `client.agents.metaComputerUse.startAndWait()` | Configurable reasoning effort |
| Grok Computer Use | `client.agents.grokComputerUse.startAndWait()` | Stateless reasoning replay |

### HyperAgent Core Methods

| Method | Purpose |
|--------|---------|
| `page.ai(prompt)` | Multi-step task with AI decision-making |
| `page.perform(action)` | Single deterministic action |
| `page.extract(prompt, schema)` | Extract structured data with Zod schema |

## Decision Guidance

### When to Use Stealth vs Ultra Stealth

| Scenario | Use `useStealth` | Use `useUltraStealth` |
|----------|------------------|----------------------|
| Basic sites without bot detection | ✗ | ✗ |
| Sites with moderate bot detection | ✓ | ✗ |
| Highly protected sites (LinkedIn, etc.) | ✓ | ✓ |
| Enterprise requirement | ✗ | ✓ |

### When to Use Each Scraping API

| Need | Use This |
|------|----------|
| Single page, raw content | `scrape.startAndWait()` |
| Multiple URLs, same format | `scrape.batch.startAndWait()` |
| Follow links across site | `web.crawl.startAndWait()` |
| Structured data with schema | `web.extract.startAndWait()` |

### When to Use Each Agent

| Requirement | Agent |
|-------------|-------|
| Cost-effective, Playwright-compatible | HyperAgent |
| Fast, open-source, DOM-based | BrowserUse |
| Reliable, multi-step, reasoning | Claude Computer Use |
| Complex reasoning, accuracy over speed | OpenAI CUA |
| Speed, broad actions | Gemini Computer Use |
| Reusable sessions, profiles | HyperAgent + profiles |

### Playwright vs Puppeteer vs HyperAgent

| Use Case | Playwright | Puppeteer | HyperAgent |
|----------|-----------|-----------|-----------|
| Deterministic selectors | ✓ | ✓ | ✗ |
| Natural language commands | ✗ | ✗ | ✓ |
| Complex workflows | ✓ | ✓ | ✓ |
| AI-powered actions | ✗ | ✗ | ✓ |
| Cost per action | Low | Low | Medium |

## Workflow

### 1. Create and Connect to a Session

```typescript
// Create session with stealth + proxy
const session = await client.sessions.create({
  useStealth: true,
  useProxy: true,
  proxyCountry: "US",
  screen: { width: 1280, height: 720 },
});

// Connect Playwright
const browser = await chromium.connectOverCDP(session.wsEndpoint);
const page = browser.contexts()[0].pages()[0];
```

### 2. Automate with Playwright or HyperAgent

**Option A: Playwright (deterministic)**
```typescript
await page.goto("https://example.com");
await page.fill("input[name='search']", "query");
await page.click("button[type='submit']");
```

**Option B: HyperAgent (AI-powered)**
```typescript
const agent = new HyperAgent();
const page = await agent.newPage();
await page.goto("https://example.com");
await page.ai("search for 'query' and click the first result");
```

### 3. Extract Data

```typescript
// With HyperAgent
const data = await page.extract(
  "get product name, price, and rating",
  z.object({
    name: z.string(),
    price: z.number(),
    rating: z.number(),
  })
);

// With Scrape API
const result = await client.scrape.startAndWait({
  url: "https://example.com",
  scrapeOptions: { formats: ["markdown", "html"] },
});
```

### 4. Run AI Agent Task

```typescript
const result = await client.agents.hyperAgent.startAndWait({
  task: "Go to example.com, search for 'laptop', and extract the top 3 results",
  maxSteps: 20,
  sessionOptions: { useStealth: true },
});

console.log(result.data?.finalResult);
```

### 5. Clean Up

```typescript
// Stop session
await client.sessions.stop(session.id);

// Or close HyperAgent
await agent.closeAgent();
```

## Common Gotchas

- **Sessions timeout silently** — Always use try-finally to stop sessions, even on error. Sessions auto-close after timeout (default varies by plan).
- **Stealth + Proxy required together** — Always enable `useStealth` or `useUltraStealth` when using proxies. Proxy alone is easily detected.
- **CAPTCHA solving is slow** — Only enable `solveCaptchas: true` when necessary. It adds 5-10 seconds per page.
- **Profiles take time to save** — After closing a session with `profile.persistChanges: true`, wait a few seconds before reusing the profile ID.
- **Screen size affects AI agents** — Keep default 1280x720 for AI agents. Larger screens degrade model performance.
- **Batch scrape limited to 1,000 URLs** — Split larger jobs into multiple batch requests.
- **WebSocket endpoint expires** — Reconnect if the session is idle for too long; check session status first.
- **Proxy + CAPTCHA solving requires paid plan** — Free tier cannot use these features together.
- **HyperAgent needs LLM API keys** — Set `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `GOOGLE_API_KEY` environment variables.
- **Agent tasks are async by default** — Use `startAndWait()` for blocking behavior, or poll status manually with `getStatus()`.
- **Credentials must be attached at session creation** — Cannot add credentials to an active session; create a new one.
- **Profile IDs are UUIDs** — Save profile IDs from the response; they're not human-readable.

## Verification Checklist

Before submitting work with Hyperbrowser:

- [ ] Session is stopped in finally block (no resource leaks)
- [ ] Stealth mode enabled if target site has bot detection
- [ ] Proxy enabled if stealth mode is on
- [ ] Screen size is 1280x720 for AI agents (or justified otherwise)
- [ ] CAPTCHA solving only enabled when necessary
- [ ] Credentials attached at session creation, not after
- [ ] Profile ID saved if persistence needed
- [ ] Agent task has clear, specific prompt (not vague)
- [ ] maxSteps set appropriately (10-20 for simple, 50+ for complex)
- [ ] Error handling includes session cleanup
- [ ] API key has correct scopes (browser.sessions.create, etc.)
- [ ] Timeout is reasonable for task complexity
- [ ] Batch scrape URLs ≤ 1,000 per request
- [ ] Recording enabled for debugging if task fails
- [ ] Results validated before returning to user

## Resources

**Comprehensive navigation:** https://hyperbrowser.ai/docs/llms.txt

**Critical documentation pages:**
- [Sessions & Configuration](/sessions/create) — Create and configure cloud browser sessions
- [HyperAgent Overview](/hyperagent/overview) — AI-powered browser automation with natural language
- [Web Scraping APIs](/web-scraping/scrape) — Scrape, crawl, and extract structured data
- [AI Agents Overview](/agents/overview) — Run Claude, BrowserUse, Gemini, and other agents
- [API Reference](/api-reference/create-new-session) — Complete REST API documentation

---

> For additional documentation and navigation, see: https://hyperbrowser.ai/docs/llms.txt