helixwright 0.1.5

Python automation SDK for Helix Browser Local API and the private Helix RPC page-control plane.

Helixwright

Helixwright is the Python automation SDK for Helix Browser.

It does not create fingerprints locally, manage browser profile folders, or start chrome.exe directly. Profile creation, fingerprint generation, proxy configuration, browser launch, and profile sync are delegated to Helix Browser Desktop through its Local API. Page actions then use the private Helix RPC control plane built into the Helix Chromium fork, not CDP, DevTools, WebDriver, Playwright, or Selenium.

Install

pip install helixwright

Requirements:

1. Helix Browser Desktop is installed and running.
2. The desktop app is logged in.
3. The desktop Local API is available, usually at http://127.0.0.1:59777.
4. The desktop build supports /api/v1/automation/sessions.

Helixwright discovers the Local API from:

%APPDATA%\Helix Browser\local_api.json
%APPDATA%\fpclient\local_api.json

The first path is the preferred Helix config directory. The fpclient path is kept for existing local installations that still use the legacy config directory.

You can override it explicitly:

$env:HELIX_LOCAL_API = "http://127.0.0.1:59777"

Quick Start

Reuse an existing Helix profile:

import helixwright as hw

with hw.launch(profile_id="profile_123", url="https://example.com") as page:
    page.ele("#email").input("[e-mail]")
    page.ele("#submit").click()

Create or reuse a profile by account_id:

import helixwright as hw

with hw.launch(
    "https://example.com",
    account_id="shop-001",
    name="Shop 001",
    proxy="http://user:pass@127.0.0.1:7890",
    fingerprint=hw.Fingerprint(locale="en-US", region="US", group="octo"),
    update_existing=True,
) as page:
    page.wait_for("body", timeout=10_000)
    print(page.title())

Use a reusable launch config:

import helixwright as hw

cfg = hw.LaunchConfig(
    account_id="shop-002",
    name="Shop 002",
    url="https://example.com",
    start_pages=["https://example.com", "https://example.com/login"],
    proxy="http://127.0.0.1:7890",
    fingerprint=hw.Fingerprint(locale="en-US", region="US"),
    update_existing=True,
)

with hw.launch(config=cfg) as page:
    page.ele("text=Login").click()

Client API

Use Client when you want to manage profiles, fingerprints, proxies, cores, or automation sessions explicitly:

import helixwright as hw

client = hw.Client()
print(client.health())
print(client.session())

profile = client.profiles.ensure(
    account_id="shop-003",
    name="Shop 003",
    proxy=hw.Proxy("http", "127.0.0.1", 7890),
    fingerprint=hw.Fingerprint(locale="en-US", region="US"),
    update_existing=True,
)

with profile.launch(url="https://example.com") as page:
    print(page.url)

Common managers:

client.profiles.list(page=1, size=20)
client.profiles.get("profile_123")
client.profiles.create(name="A", account_id="acct_A")
client.profiles.ensure(account_id="acct_A")
client.profiles.clone("profile_123", count=2)
client.profiles.sync_up("profile_123")
client.profiles.sync_down("profile_123")

client.fingerprint.options()
client.fingerprint.draw(account_id="acct_A", group="octo")
client.fingerprint.serialize({"ua": "..."}, seed=123)
client.fingerprint.redraw({"ua": "..."}, "ua")

client.proxy.check("http://127.0.0.1:7890")
client.cores.list()
client.cores.ensure("chromium", "149.0.7827.156")
client.browser.active()
client.browser.start("profile_123")
client.browser.stop("profile_123")
client.browser.stop_all()
client.automation.list()
client.automation.start("profile_123", url="https://example.com")
client.automation.stop("auto_123")

RPC Metadata And Input Receipts

Normal scripts can keep using page.ele(...), navigation, trace, and network helpers. For diagnostics and multi-target workflows, the operator exposes the browser RPC metadata layer when the installed core supports it:

print(page.rpc_hello())
print(page.rpc_endpoint_path)
print(page.rpc_describe())
print(page.rpc_ping())
print(page.targets())
page.activate_target(index=0)
print(page.frame_context())
print(page.last_action_receipt())

The current cloud-active M149 core is RPC V3: rpc.hello advertises protocol version 3, action receipts, typed errors, method metadata, and preferred endpoint /rpc/v2. Helixwright probes /rpc first for compatibility, then switches to the preferred endpoint reported by rpc.hello.

The SDK also supports the V4 source contract being staged in the M149 browser tree: protocol version 4, preferred endpoint /rpc/v3, explicit request context, and unified input.action. When a V4 core advertises input_action_vm, Helixwright sends keyboard, mouse, wheel, drag, and text actions through input.action; otherwise it falls back to the V3 atomic input methods or older RPC methods.

Older V2/V1 cores still attach. V2 uses /rpc/v1; V1 uses legacy /rpc. rpc_hello() falls back to a V1 capability payload when the browser does not expose rpc.hello.

Native Trace

Native trace records the page timeline locally through the Helix browser core: RPC actions, navigation, network metadata, console messages, and native DOM snapshots. It does not use CDP, WebDriver, Playwright, Selenium, or page-world JavaScript.

Local API is only used to start the automation session and return the browser RPC endpoint. All trace calls below go directly from Helixwright to the browser RPC endpoint; they are not forwarded through Local API.

Default mode is summary. Use full=True only when you need full DOM snapshot payloads for debugging or AI code generation. Trace data is not redacted.

import helixwright as hw

with hw.launch("https://example.com/login", account_id="trace-demo") as page:
    page.trace_start()  # summary mode

    page.trace_action(
        "fill-login",
        lambda: page.ele("#email").input("[e-mail]"),
        settle_ms=800,
    )

    state = page.where_am_i({
        "login": lambda p: p.ele("#email").exists(),
        "dashboard": lambda p: "/dashboard" in p.url,
        "blocked": lambda p: p.ele(text="Verify").exists(),
    })

    page.trace_export("trace-login.json")
    print("state:", state)

Full trace:

page.trace_start(full=True)
page.trace_snapshot(full=True)
page.trace_export("trace-full.json")

CLI capture for an already-running automation session:

python -m helixwright trace --session auto_123 --duration 15 --output trace.json
python -m helixwright trace --session auto_123 --full --duration 15 --output trace-full.json

Launch Rules

hw.launch() requires either profile_id or account_id/account.

Important behavior:

• profile_id means reuse that exact Helix profile.
• account_id means find an existing profile by account ID, or create one when create=True.
• fingerprint=hw.Fingerprint(...) only sends creation hints to Helix Local API. The SDK does not generate fingerprints itself.
• proxy can be a string, dict, or hw.Proxy.
• start_pages is passed to the Local API automation session.
• config=hw.LaunchConfig(...) should not be mixed with explicit profile_id, account_id, name, proxy, or fingerprint arguments.
• page.close() stops the Local API automation session, waits until that session disappears, then waits until the matching /browser/active entry is gone before returning. Browser cleanup errors are propagated instead of being silently ignored.

Unsupported legacy direct-launch arguments are rejected, including chrome, user_data_dir, persona, seed, geoip, and extra_args.

Errors

Common error types:

Error	Meaning
LocalApiUnavailable	Helix Desktop is not running, the Local API address is wrong, or the port is unreachable.
DesktopNotLoggedIn	Desktop is reachable but not logged in.
LocalApiError	Local API returned a business error.
ProfileNotFound	The requested profile does not exist.
AutomationEndpointUnavailable	The desktop build did not return a usable automation RPC endpoint.
AutomationSessionNotFound	The requested automation session does not exist.
RpcError	The browser RPC endpoint returned a structured RPC error with a code.
TransportError	The private page RPC connection failed, usually because the browser exited.
WaitTimeoutError	A page wait condition timed out.

Examples

From the source repository:

cd "E:\Helix Browser\repos\helixwright"
python examples\99_offline_mock_demo.py

The offline demo does not need Helix Browser. It starts a mock Local API and mock RPC endpoint, then exercises the public SDK surface.

Real desktop examples require Helix Browser Desktop to be running and logged in:

python examples\00_helixwright_quickstart.py
python examples\01_client_managers.py
python examples\02_launch_config_and_actions.py

Useful environment variables:

$env:HELIX_LOCAL_API = "http://127.0.0.1:59777"
$env:HELIX_EXAMPLE_ACCOUNT = "demo-account"
$env:HELIX_EXAMPLE_URL = "https://example.com"
$env:HELIX_EXAMPLE_PROXY = "http://127.0.0.1:7890"
$env:HELIX_EXAMPLE_TIMEOUT_MS = "30000"

Development

cd "E:\Helix Browser\repos\helixwright"
pip install -e .
python tests\ci.py

Build and validate a distribution:

python -m build
python -m twine check dist/*

Boundary

Helixwright is only the automation SDK. The authoritative source for profiles, fingerprints, proxies, browser core downloads, cloud sync, and launch lifecycle is Helix Browser Desktop plus its Local API.