SDK Reference

Two SDKs, one product: anti-detect-browser on npm and antibrow on PyPI. They share a cache directory, a profile format and an account, so a profile created from one opens in the other and in the desktop app. Either way you launch a profile and receive real Playwright objects over CDP, so the selectors, assertions and traces you already wrote keep working. Windows, macOS and Linux. Local profiles are unlimited on every plan; paid plans add concurrency, cloud sync, managed proxies and Live View.

npm install anti-detect-browser

import { AntiDetectBrowser } from 'anti-detect-browser'

const ab = new AntiDetectBrowser({ key: 'your-api-key' })

const { page, context, browser } = await ab.launch({
  profile: 'account-01',
  label: 'account-01',
})

// Plain Playwright from here.
await page.goto('https://example.com')
await page.getByRole('button', { name: 'Sign in' }).click()

await browser.close()

pip install antibrow

python -m antibrow login      # stores your API key
python -m antibrow install    # downloads the engine (optional: the first launch does it)

from antibrow import launch

browser = launch(profile="account-01")

# Plain Playwright from here.
page = browser.new_page()
page.goto("https://example.com")
page.get_by_role("button", name="Sign in").click()

browser.close()

from antibrow import launch

with launch(
    profile="scraper-eu",
    headless=True,
    proxy="http://user:pass@gate.example.com:8080",
    geoip=True,                # timezone and WebRTC follow the proxy exit
) as browser:
    page = browser.new_page()
    page.goto("https://example.com")
    print(browser.timezone, browser.public_ip)

import asyncio
from antibrow import launch_async

async def main():
    browser = await launch_async(profile="agent-01")
    page = await browser.new_page()
    await page.goto("https://example.com")
    print(await page.title())
    await browser.close()

asyncio.run(main())

new AntiDetectBrowser(options)

launch(options)

What launch() returns

openProfile(options)

The lower-level entry point that launch() is built on. Use it when you want the session object directly, the exit-IP geo, archive-sync callbacks, or the per-profile engine switches.

import { openProfile } from 'anti-detect-browser'

const session = await openProfile({
  key: 'your-api-key',
  profileName: 'account-01',
  proxyUrl: 'http://user:pass@host:5001',
  onProgress: (m) => console.log(m),
})

console.log(session.geo)   // { ip, country, countryCode, city, timezone }

const page = session.context.pages()[0] ?? await session.context.newPage()
await page.goto('https://example.com')

await session.close()

The session it resolves to

launch(profile="default", **options)

Starts the engine and returns a handle that is ready to drive. launch_async() takes exactly the same options.

The Antibrow handle

Attribute lookups fall through to the Playwright BrowserContext, so the handle behaves like one without you having to reach for .context first.

browser = launch(profile="account-01")

# Attribute lookups fall through to the Playwright BrowserContext,
# so anything you would call on a context works on the handle.
browser.add_init_script("...")
browser.add_cookies([...])
browser.pages

Other entry points

from antibrow import (
    launch_async, launch_persistent_context,
    launch_persistent_context_async, prepare_launch,
)

browser = await launch_async(profile="p1")           # asyncio twin of launch()
context = launch_persistent_context(profile="p1")    # a literal Playwright BrowserContext
plan    = prepare_launch(profile="p1")               # resolve everything, start nothing

print(plan.redacted_args())   # the command line with the token and proxy password masked

prepare_launch() resolves the exact executable, arguments, persona and timezone a launch would use without starting a process, which makes it the thing to run for tests, dry runs and bug reports.

Managing profiles

import {
  listProfiles, getProfileDir, defaultCacheDir,
  getOrCreateProfile, deleteProfile,
} from 'anti-detect-browser'

// Local profiles are directories on disk. Unlimited on every plan.
listProfiles()                // string[] of profile names
getProfileDir('account-01')   // absolute path to that profile
defaultCacheDir()             // ~/.anti-detect-browser by default

// Cloud-synced profiles talk to the server and need an API key.
const p = await getOrCreateProfile({ key, name: 'account-01', tags: ['ads'] })
await deleteProfile({ key, id: p.id })

from antibrow import list_profiles, profile_dir, default_cache_dir

# Local profiles are directories on disk. Unlimited on every plan, and
# launching a name that does not exist creates it.
list_profiles()                # ['account-01', 'account-02']
profile_dir("account-01")      # Path to that profile
default_cache_dir()            # ~/.anti-detect-browser by default

# Or point at an exact directory, e.g. a volume mounted into CI:
launch(profile_dir="/data/profiles/account-01")

Device profiles

Two independent options, both resolved only the first time a profile is created - an existing profile keeps whatever they resolved to, frozen in its persona.

• deviceType: 'android' simulates a full Android phone environment - user agent, Client Hints, touch input, screen - that runs on this same Windows, macOS or Linux machine. It does not run on a phone, and no physical device is required. Free on every plan, including Free.
• realFingerprint: true draws the identity from the Captured-machine fingerprint library, a pool of fingerprints captured from real physical machines, instead of generating one locally. Paid plans only - a Free-plan request gets a 403 from the server rather than a silent fallback to a generated identity. Works with either device type.

// A simulated Android phone - runs on this same Windows/macOS/Linux
// machine, not on a physical device, and needs none. Free on every
// plan. Only takes effect the first time this profile is created.
await ab.launch({ profile: 'mobile-01', deviceType: 'android' })

// Draw the identity from a real captured device instead of generating
// one. Paid plans only - a Free-plan key gets a 403. Works for either
// device type, and also only applies at first creation.
await ab.launch({ profile: 'captured-01', realFingerprint: true })

// Combine both: an Android identity pulled from the captured library.
await ab.launch({
  profile: 'captured-mobile-01',
  deviceType: 'android',
  realFingerprint: true,
})

# A simulated Android phone - runs on this same Windows/macOS/Linux
# machine, not on a physical device, and needs none. Free on every
# plan. Only takes effect the first time this profile is created.
browser = launch(profile="mobile-01", device_type="android")

# Draw the identity from a real captured device instead of generating
# one. Paid plans only - a Free-plan key raises. Works for either
# device type, and also only applies at first creation.
browser = launch(profile="captured-01", real_fingerprint=True)

Export and import

Profiles export to a portable .fpprofile archive on every plan, including Free, because the ability to leave should not be a paid feature. It carries the fingerprint, cookies, storage, bookmarks and passkeys. Treat the file as a credential: whatever can open it is signed in as that identity.

import { exportProfileArchive, importProfileArchive, getProfileDir } from 'anti-detect-browser'
import { writeFileSync, readFileSync } from 'node:fs'

// Carries the fingerprint, cookies, storage, bookmarks and passkeys.
const buf = exportProfileArchive(getProfileDir('account-01'), meta)
writeFileSync('account-01.fpprofile', buf)

// Restore it into another machine's profile directory.
importProfileArchive(readFileSync('account-01.fpprofile'), getProfileDir('account-01'))

Proxies

launch(proxy="http://user:pass@gate.example.com:8080")
launch(proxy="socks5://user:pass@127.0.0.1:1080")
launch(proxy={"server": "http://gate.example.com:8080", "username": "u", "password": "p"})

browser = launch(profile="p1", proxy="socks5://user:pass@127.0.0.1:1080")
print(browser.public_ip, browser.timezone)   # 203.0.113.7 America/Los_Angeles

Framework integrations

Every integration works the same way: the SDK starts the browser, and you hand its CDP endpoint to whatever wants to drive it. Playwright needs no glue at all - the handle already is a context.

browser = launch(profile="agent-01")

browser.cdp_url        # http://127.0.0.1:54321        - crawl4ai, puppeteer.connect
browser.cdp_endpoint   # ws://127.0.0.1:54321/devtools/browser/...

# browser-use
Agent(task="...", llm=llm, browser=Browser(cdp_url=browser.cdp_url))

# crawl4ai
AsyncWebCrawler(config=BrowserConfig(cdp_url=browser.cdp_url, headless=False))

# Scrapling
DynamicFetcher.fetch("https://example.com", cdp_url=browser.cdp_endpoint)

Selenium cannot attach to a CDP-only endpoint without a matching chromedriver, so there is no Selenium binding today. If you are migrating from it, Playwright is the shortest path. Driving the browser from an AI agent instead? See the MCP server.

Live View

Stream a running session to the dashboard. Paid plans only.

const { page, viewUrl } = await ab.launch({
  profile: 'account-01',
  liveView: { quality: 60, maxWidth: 1280, everyNthFrame: 2 },
})

console.log(viewUrl)   // open in the dashboard to watch the session

Engine updates

The engine downloads on first use and is cached under the cache directory. New profiles use the current default version; an existing profile keeps the version recorded in its persona, so its fingerprint does not shift underneath it after an update.

await ab.checkKernelUpdates()

if (await ab.hasKernelUpdate()) {
  await ab.updateKernel(undefined, (m) => console.log(m))
}

// Or fold it into a launch:
await ab.launch({ profile: 'account-01', updateKernelBeforeLaunch: true })

# Fold the check into a launch:
launch(profile="account-01", update_kernel=True)

# Or from the CLI:
#   python -m antibrow install --force

CLI and environment

python -m antibrow install [--version 151] [--force]              # get the engine
python -m antibrow info                                           # engines, profiles, license
python -m antibrow login [--key ab_live_...]                      # store an API key
python -m antibrow version                                        # SDK and default engine version

antibrow ... works too, as a console script. info is the first thing to run when something is wrong: it prints the cache directory, every engine version with its install status, all profiles with the version they are pinned to, and where your API key was found.

Docker

The Linux engine runs headful under Xvfb, because real headless Chromium has its own fingerprint. This image works on both linux/amd64 and linux/arm64; the matching build is chosen from the container's CPU.

FROM python:3.12-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
      xvfb xauth libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
      libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 \
      libgbm1 libasound2 libpango-1.0-0 libcairo2 fonts-liberation ca-certificates \
    && rm -rf /var/lib/apt/lists/*
RUN pip install --no-cache-dir antibrow
COPY script.py .
# Two details this line earns the hard way: xvfb-run needs xauth (without it you get
# "xauth command not found"), and it must not be PID 1 - as PID 1 it never reaps the
# browser's children, so the container hangs after a successful launch with no output.
CMD ["sh", "-c", "xvfb-run -a python script.py"]

Mount the cache directory as a volume (-v antibrow-cache:/root/.anti-detect-browser) so the engine and your profiles survive between runs, otherwise every container downloads the engine again.

Errors

from antibrow import AntibrowError, ConcurrencyLimitError, LicenseError

try:
    browser = launch()
except ConcurrencyLimitError:
    ...   # the plan's simultaneous-browser cap is in use
except LicenseError:
    ...   # no API key, or the server rejected it
except AntibrowError:
    ...   # engine download, unsupported platform, proxy, launch failure

Server API

Both SDKs call these for you, so you rarely need them directly. They are here for anyone integrating without an SDK. Authenticate with Authorization: Bearer <api-key>.