{"id":"headless-browser","name":"headless-browser","summary":"PlaywrightまたはPuppeteerを使ってChrome DevTools Protocol(CDP)を介してOxylabsのリモートヘッドレスブラウザに接続します。","body":"# Oxylabs Headless Browser\n\nRemote headless browser service with built-in anti-detection and proxy integration. Chrome supports Playwright, Puppeteer, and any CDP-compatible library. Firefox is legacy and uses Playwright's Firefox connection API.\n\n## Environment Variables\n\nPrefer `OXY_UNBLOCKER_USERNAME` and `OXY_UNBLOCKER_PASSWORD` for Headless Browser credentials. `OXY_HB_USERNAME` and `OXY_HB_PASSWORD` are supported aliases in older setups.\n\n## Connection URLs\n\n| Browser | Global endpoint | US endpoint |\n|---------|-----------------|-------------|\n| Chrome | `wss://USERNAME:PASSWORD@ubc.oxylabs.io` | `wss://USERNAME:PASSWORD@ubc-us.oxylabs.io` |\n| Firefox (legacy) | `wss://USERNAME:PASSWORD@ubs.oxylabs.io` | `wss://USERNAME:PASSWORD@ubs-us.oxylabs.io` |\n\n## Browser Types\n\n| Type | Best For | Notes |\n|------|----------|-------|\n| **Chrome** | High performance, dedicated servers, residential proxies | Use `chromium.connect_over_cdp` / `connectOverCDP` |\n| **Firefox (legacy)** | Alternative engine for targets that perform better outside Chrome | Use `firefox.connect`; supported Playwright versions are 1.51 and 1.56 via `?o_pw=1.56` |\n\n## Quick Start\n\n**Playwright (Python):**\n```python\nfrom playwright.sync_api import sync_playwright\nimport os\n\nusername = os.environ.get(\"OXY_UNBLOCKER_USERNAME\") or os.environ[\"OXY_HB_USERNAME\"]\npassword = os.environ.get(\"OXY_UNBLOCKER_PASSWORD\") or os.environ[\"OXY_HB_PASSWORD\"]\nendpoint = \"ubc.oxylabs.io\"\n\nwith sync_playwright() as p:\n    browser = p.chromium.connect_over_cdp(\n        f\"wss://{username}:{password}@{endpoint}\"\n    )\n    page = browser.new_page()\n    page.goto(\"https://example.com\")\n    print(page.content())\n    browser.close()\n```\n\n**Playwright (JavaScript):**\n```javascript\nconst { chromium } = require(\"playwright\");\n\nconst username = process.env.OXY_UNBLOCKER_USERNAME || process.env.OXY_HB_USERNAME;\nconst password = process.env.OXY_UNBLOCKER_PASSWORD || process.env.OXY_HB_PASSWORD;\nconst endpoint = \"ubc.oxylabs.io\";\n\n(async () => {\n  const browser = await chromium.connectOverCDP(\n    `wss://${username}:${password}@${endpoint}`\n  );\n  const page = await browser.newPage();\n  await page.goto(\"https://example.com\");\n  console.log(await page.content());\n  await browser.close();\n})();\n```\n\n**Puppeteer:**\n```javascript\nconst puppeteer = require(\"puppeteer\");\n\nconst username = process.env.OXY_UNBLOCKER_USERNAME || process.env.OXY_HB_USERNAME;\nconst password = process.env.OXY_UNBLOCKER_PASSWORD || process.env.OXY_HB_PASSWORD;\nconst endpoint = \"ubc.oxylabs.io\";\n\n(async () => {\n  const browser = await puppeteer.connect({\n    browserWSEndpoint: `wss://${username}:${password}@${endpoint}`\n  });\n  const page = await browser.newPage();\n  await page.goto(\"https://example.com\");\n  console.log(await page.content());\n  await browser.close();\n})();\n```\n\n## Rate Limits\n\n- **Concurrent sessions:** 100 per browser type\n- **Launch rate:** up to 10 sessions per second per browser type\n- **Higher limits:** Available upon request to support\n\n## Features\n\n- **Anti-detection:** Built-in fingerprint management\n- **Residential proxies:** Automatic proxy rotation\n- **Geo-targeting:** Country, city, and US state targeting via connection parameters\n- **US endpoints:** Lower latency for US-based users; not the same as proxy geolocation\n- **CAPTCHA handling:** Automatic load-time solving; manual trigger available with `window.postMessage({action: 'solve_captcha', type: '<captcha type>'}, '*')`\n- **Session inspection:** Enable VNC debugging with `o_vnc=true`\n- **No local browsers:** All execution happens remotely\n\n## Connection Parameters\n\nAppend query parameters to the WebSocket URL:\n\n| Parameter | Browser | Description |\n|-----------|---------|-------------|\n| `p_cc=US` | Chrome, Firefox | Route traffic through a 2-letter country code |\n| `p_city=los_angeles` | Chrome, Firefox | Target a city; combine with `p_cc` or `p_state` |\n| `p_state=texas` | Chrome, Firefox | Target a US state; takes priority over `p_cc` |\n| `p_device=mobile` | Chrome | Emulate `desktop`, `mobile`, or `tablet` device fingerprints |\n| `o_vnc=true` | Chrome, Firefox | Enable Session Inspection for visual debugging |\n| `o_pw=1.56` | Firefox | Select supported Firefox Playwright version `1.51` or `1.56` |\n| `bargs=disable-notifications` | Chrome | Pass supported Chrome browser arguments |\n\nSupported Chrome `bargs` values: `force-color-profile:<profile>`, `window-position:X,Y`, `hide-scrollbars`, `enable-features:<feature1>,<feature2>`, `disable-notifications`.\n\nRepeat `bargs` for multiple browser arguments, e.g., `?bargs=force-color-profile:srgb&bargs=window-position:100,100`. `p_city` requires `p_cc` or `p_state`; `p_state` overrides `p_cc`.\n\n## CAPTCHA Handling\n\n- Listen for `oxylabs-captcha-solve-start`, `oxylabs-captcha-solve-end`, and `oxylabs-captcha-solve-error` window messages.\n- Register CAPTCHA listeners before navigation when possible so page-load challenges are captured.\n- For CAPTCHAs shown after page load, trigger solving with `window.postMessage({action: 'solve_captcha', type: '<captcha type>'}, '*')`.\n- Supported manual CAPTCHA types: `hcaptcha`, `recaptcha`, `turnstile`.\n\n## When to Use\n\n| Scenario | Use Headless Browser |\n|----------|------------------------|\n| Complex JavaScript sites | Yes |\n| Anti-bot protected sites | Yes |\n| Browser automation with stealth | Yes |\n| Screenshot/PDF generation | Yes |\n| Simple HTML scraping | Consider Web Scraper API instead |\n\n## Supported Libraries\n\nAny library supporting Chrome DevTools Protocol (CDP):\n- Playwright (recommended)\n- Puppeteer\n- Selenium with CDP\n- Custom CDP implementations\n\nFirefox is legacy and should use Playwright `firefox.connect` with supported Playwright versions 1.51 or 1.56.\n\nFor more examples, see [examples.md](examples.md).","author":"@oxylabs","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/oxylabs/agent-skills/tree/main/skills/headless-browser","license":"MIT","category":"coding","lang":"en","tokens":1433,"stars":0,"calls30d":1,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"examples.md","size":7305,"sha256":"32fad6ead6d33778574a04213f7a3b27a28d3c512fb998e3b94b20bd774cf69b"}],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[{"code":"code.eval","kind":"dangerous-code","where":"examples.md:154","excerpt":"eval(","message":"evaluates code at runtime","severity":"warn"}],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":[]}}