helixwright 0.1.0

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

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", "150")
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")

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.

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