skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
oxylabs/agent-skills62 installs

oxylabs-headless-browser

Connects to Oxylabs remote headless browsers via Chrome DevTools Protocol (CDP) using Playwright or Puppeteer. Provides anti-detection, CAPTCHA handling, residential proxies, and geo-targeting built in. Use when browser automation needs remote execution, stealth capabilities, rendered pages, screenshots, PDFs, or complex JavaScript interaction.

How do I install this agent skill?

npx skills add https://github.com/oxylabs/agent-skills --skill oxylabs-headless-browser
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    This skill provides instructions and code examples for using Oxylabs' remote headless browser service. It follows security best practices by using environment variables for credential management and connects exclusively to the vendor's official infrastructure.

  • Socketwarn

    1 alert: gptAnomaly

  • Snykwarn

    Risk: MEDIUM · 1 issue

What does this agent skill do?

Oxylabs Headless Browser

Remote 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.

Environment Variables

Prefer OXY_UNBLOCKER_USERNAME and OXY_UNBLOCKER_PASSWORD for Headless Browser credentials. OXY_HB_USERNAME and OXY_HB_PASSWORD are supported aliases in older setups.

Connection URLs

BrowserGlobal endpointUS endpoint
Chromewss://USERNAME:PASSWORD@ubc.oxylabs.iowss://USERNAME:PASSWORD@ubc-us.oxylabs.io
Firefox (legacy)wss://USERNAME:PASSWORD@ubs.oxylabs.iowss://USERNAME:PASSWORD@ubs-us.oxylabs.io

Browser Types

TypeBest ForNotes
ChromeHigh performance, dedicated servers, residential proxiesUse chromium.connect_over_cdp / connectOverCDP
Firefox (legacy)Alternative engine for targets that perform better outside ChromeUse firefox.connect; supported Playwright versions are 1.51 and 1.56 via ?o_pw=1.56

Quick Start

Playwright (Python):

from playwright.sync_api import sync_playwright
import os

username = os.environ.get("OXY_UNBLOCKER_USERNAME") or os.environ["OXY_HB_USERNAME"]
password = os.environ.get("OXY_UNBLOCKER_PASSWORD") or os.environ["OXY_HB_PASSWORD"]
endpoint = "ubc.oxylabs.io"

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(
        f"wss://{username}:{password}@{endpoint}"
    )
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.content())
    browser.close()

Playwright (JavaScript):

const { chromium } = require("playwright");

const username = process.env.OXY_UNBLOCKER_USERNAME || process.env.OXY_HB_USERNAME;
const password = process.env.OXY_UNBLOCKER_PASSWORD || process.env.OXY_HB_PASSWORD;
const endpoint = "ubc.oxylabs.io";

(async () => {
  const browser = await chromium.connectOverCDP(
    `wss://${username}:${password}@${endpoint}`
  );
  const page = await browser.newPage();
  await page.goto("https://example.com");
  console.log(await page.content());
  await browser.close();
})();

Puppeteer:

const puppeteer = require("puppeteer");

const username = process.env.OXY_UNBLOCKER_USERNAME || process.env.OXY_HB_USERNAME;
const password = process.env.OXY_UNBLOCKER_PASSWORD || process.env.OXY_HB_PASSWORD;
const endpoint = "ubc.oxylabs.io";

(async () => {
  const browser = await puppeteer.connect({
    browserWSEndpoint: `wss://${username}:${password}@${endpoint}`
  });
  const page = await browser.newPage();
  await page.goto("https://example.com");
  console.log(await page.content());
  await browser.close();
})();

Rate Limits

  • Concurrent sessions: 100 per browser type
  • Launch rate: up to 10 sessions per second per browser type
  • Higher limits: Available upon request to support

Features

  • Anti-detection: Built-in fingerprint management
  • Residential proxies: Automatic proxy rotation
  • Geo-targeting: Country, city, and US state targeting via connection parameters
  • US endpoints: Lower latency for US-based users; not the same as proxy geolocation
  • CAPTCHA handling: Automatic load-time solving; manual trigger available with window.postMessage({action: 'solve_captcha', type: '<captcha type>'}, '*')
  • Session inspection: Enable VNC debugging with o_vnc=true
  • No local browsers: All execution happens remotely

Connection Parameters

Append query parameters to the WebSocket URL:

ParameterBrowserDescription
p_cc=USChrome, FirefoxRoute traffic through a 2-letter country code
p_city=los_angelesChrome, FirefoxTarget a city; combine with p_cc or p_state
p_state=texasChrome, FirefoxTarget a US state; takes priority over p_cc
p_device=mobileChromeEmulate desktop, mobile, or tablet device fingerprints
o_vnc=trueChrome, FirefoxEnable Session Inspection for visual debugging
o_pw=1.56FirefoxSelect supported Firefox Playwright version 1.51 or 1.56
bargs=disable-notificationsChromePass supported Chrome browser arguments

Supported Chrome bargs values: force-color-profile:<profile>, window-position:X,Y, hide-scrollbars, enable-features:<feature1>,<feature2>, disable-notifications.

Repeat 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.

CAPTCHA Handling

  • Listen for oxylabs-captcha-solve-start, oxylabs-captcha-solve-end, and oxylabs-captcha-solve-error window messages.
  • Register CAPTCHA listeners before navigation when possible so page-load challenges are captured.
  • For CAPTCHAs shown after page load, trigger solving with window.postMessage({action: 'solve_captcha', type: '<captcha type>'}, '*').
  • Supported manual CAPTCHA types: hcaptcha, recaptcha, turnstile.

When to Use

ScenarioUse Headless Browser
Complex JavaScript sitesYes
Anti-bot protected sitesYes
Browser automation with stealthYes
Screenshot/PDF generationYes
Simple HTML scrapingConsider Web Scraper API instead

Supported Libraries

Any library supporting Chrome DevTools Protocol (CDP):

  • Playwright (recommended)
  • Puppeteer
  • Selenium with CDP
  • Custom CDP implementations

Firefox is legacy and should use Playwright firefox.connect with supported Playwright versions 1.51 or 1.56.

For more examples, see examples.md.

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/oxylabs/agent-skills/oxylabs-headless-browser">View oxylabs-headless-browser on skillZs</a>