API reference

Capium exposes three launch entry points plus await-able twins, the humanize helpers, and a status() call. Everything returns standard Playwright objects, so the rest is the Playwright API you already know.

Entry points

launch(seed=None, platform='windows', headless=False, proxy=None, geoip=False, args=None, timezone=None, locale=None, license_key=None, **kwargs)

returns Browser

Full control. You create your own contexts and pages. **kwargs are forwarded to Playwright's chromium.launch. .close() also stops the driver.

launch.py

from capium import launch

browser = launch(
    seed=200123,            # int | "off" for passthrough | None for random
    platform="windows",     # "windows" | "macos" | "linux"
    headless=False,
    proxy="http://user:pass@host:port",   # or "socks5://...", "dataimpulse", dict
    geoip=False,
    args=None,              # extra --fingerprint-* flags (list[str])
    timezone=None,          # IANA tz override
    locale=None,            # BCP-47 locale override
    license_key=None,       # else CAPIUM_LICENSE_KEY / ~/.capium/license
)
page = browser.new_context().new_page()
page.goto("https://example.com")
browser.close()             # also stops the Playwright driver

launch_context(seed=None, platform='windows', headless=False, url=None, humanize=False, ...)

returns (Browser, BrowserContext, Page)

One-liner: opens a context + page, optionally navigates to url and attaches the human_* helpers when humanize=True.

context.py

from capium import launch_context

browser, ctx, page = launch_context(
    seed=200123, platform="linux",
    proxy="dataimpulse", geoip=True,
    humanize=True,          # attach page.human_* helpers
    url="https://example.com",   # optional: navigate on open
)
browser.close()

launch_persistent_context(user_data_dir, seed=None, platform='windows', headless=False, proxy=None, geoip=False, ...)

returns BrowserContext

A persistent profile: cookies, localStorage and login survive between runs. Returns the context directly (not a tuple).

persistent.py

from capium import launch_persistent_context

ctx = launch_persistent_context(
    "~/profiles/acct1",     # user_data_dir (required first arg)
    seed=200123, platform="linux",
    proxy="http://user:pass@host:port", geoip=True,
)
page = ctx.pages[0] if ctx.pages else ctx.new_page()
ctx.close()

Async twins

launch_async, launch_context_async and launch_persistent_context_async take the same arguments and return the same shapes, awaited.

Shared parameters

Param	Meaning
seed	int, "off" (passthrough), or None (random). The whole coherent device.
platform	"windows" \| "macos" \| "linux" persona.
headless	bool; headed (False) is recommended.
proxy	URL (http/https/socks5), a named pool, or a dict.
geoip	align timezone/geo/WebRTC to the proxy (or self) exit.
timezone / locale	explicit IANA tz + BCP-47 locale overrides.
args	list of extra --fingerprint-* flags.
license_key / license_server	programmatic license (else env / file).
url (context only)	navigate on open.
humanize (context only)	attach page.human_* helpers.

Full flag list in Parameters & flags.

Humanize helpers

human.py

from capium.human import humanize, move, click, type_text, scroll, dwell

humanize(page_or_context, preset="default")   # or "careful"
page.human_click("#login")
page.human_type("#user", "alice")
page.human_scroll(1200)

# ...or call helpers directly on any Playwright page:
click(page, "#login", preset="careful")

status()

Read your license entitlements programmatically (same data as capium status).

status.py

from capium import status

print(status())   # {"plan": ..., "sessions_cap": ..., "live_sessions": ..., "period_end": ...}

Errors

Launch failures raise typed exceptions (CapiumConfigError, CapiumSeatLimitError, CapiumExpiredError, CapiumServerDownError). See the Errors reference.

Parameters & flags

Command-line