Skip to Content
v3.1.0Installed browsers. Live locators. Verified input.
DocumentationConnect to your browser

Connect to your own browser

Browser.connect() drives a browser profile of your own that has the emunium extension installed persistently, instead of starting a fresh one.

Install the hub extra (the build needs cryptography) and build the extension once:

pip install "emunium[hub]" python -m emunium extension build --out DIR

The build writes DIR/emunium-extension/ (plus a .zip and a signed .crx) and prints the extension id and hub URL. It creates the hub state on first use: a key that fixes the extension id, and hub.json with the hub port (47800 by default; --port N changes and stores it) and an enrollment secret, in %APPDATA%\emunium, ~/Library/Application Support/emunium or $XDG_CONFIG_HOME/emunium (default ~/.config/emunium); EMUNIUM_HOME overrides. The folder carries that secret; keep it private. python -m emunium extension id prints the id.

Load the extension in Chrome, Edge, Brave or Chromium: open the extensions page (chrome://extensions, edge://extensions, …), turn on developer mode, click Load unpacked and pick DIR/emunium-extension.

For Firefox, register the signed extension through Enterprise Policies before starting the browser:

python -m emunium extension build --out DIR --target firefox --firefox-path "C:\Program Files\Mozilla Firefox\firefox.exe"

This builds DIR/emunium-extension-firefox/ and an unsigned local .xpi, then merges ExtensionSettings["bridge@emunium.dev"] into the installation’s distribution/policies.json (Contents/Resources/distribution on macOS). The policy uses installation_mode="force_installed" and defaults to https://github.com/DedInc/emunium/releases/download/<installed-version>/emunium-extension-firefox.xpi. That signed release artifact must exist. To use your own signed artifact, pass --firefox-xpi PATH_OR_HTTPS_URL or set EMUNIUM_FIREFOX_XPI; the CLI option takes precedence and requires --firefox-path, which requires --target firefox. The locally built unsigned XPI needs signing before use in standard Firefox. Its attach.json must match the port and enrollment in the active EMUNIUM_HOME; preserve that state when building and signing.

Browser.connect("firefox") also registers this policy before starting Firefox when no extension has connected during its initial wait. The installation directory must be writable. Existing policy keys and extension settings are preserved; writes replace the policy file atomically. Invalid JSON, incompatible policy shapes or an unwritable installation raise LaunchError. The preference defaults configure welcome/default-browser/session-restore prompts and telemetry, and set dom.webdriver.enabled=false. Existing preference entries are preserved; new entries use Status="default", allowing user overrides. A separate SkipTermsOfUse=true policy skips the Terms of Use dialog on supported Firefox versions (138+, ESR 140+). An existing explicit value, including false, is preserved. These preferences alone do not suppress that dialog. Restart an already-running Firefox to apply changed policies.

from emunium import Browser with Browser.connect("firefox", user_data_dir="firefox-profile") as browser: browser.goto("https://example.com/") print(browser.title)
from emunium import Browser with Browser.connect("edge") as browser: browser.goto("https://example.com/") print(browser.browser_name) # "edge" # The browser is still running: close() only detaches.

connect listens on the hub port and waits up to 5 s for the extension. If none connects, it starts the browser detached from Python, without automation flags, and waits for the rest of timeout. Then it pins the active tab; DOM, locators and native input work as after launch().

OptionMeaning
browser=NoneBrowser to start, as in Browser(browser=...); also names browser_name
user_data_dir=NoneProfile root for a started browser (--user-data-dir, Firefox -profile); None opens the browser’s default profile. Never deleted
profile_directory=NoneChromium profile inside it, e.g. "Profile 1"; not for Firefox
start=TrueStart the browser when no extension connects within 5 s; False only waits
close_browser=Falseclose() also stops a browser that connect started; one that was already running always stays
port=NoneHub port; None uses the stored one, which the build used
install_id=NoneAccept only this install (a UUID); None binds the first install that connects. A session serves one install; others are refused
timeout=60.0Seconds to wait for the extension overall

extra_args, verify_input, motion and typing work as for Browser().

  • close() detaches and leaves the browser running (unless close_browser=True and connect started it).
  • Pass browser= for a browser that is already running: on Windows emunium then finds its window for native input. Without it, an already-running browser is named only from its user agent ("edge", "firefox", else None; Chrome, Brave and Chromium look alike), and its window is not brought to the foreground.
  • An already-running browser can take up to 30 s to retry the connection (the extension’s reconnect back-off); keep timeout above that.
  • Errors: LaunchError when the hub port is taken, the browser cannot start, or no extension connects in time (the message names the build command, hub port and state dir); ImportError without cryptography.

Profiles started by another app

The attach build works in any Chromium-based browser profile you control once the extension is installed in that profile, through the vendor’s own extension feature or through developer mode → Load unpacked. If the vendor has port-scan protection, it must allow the hub port (47800 by default).

Pass start=False: the vendor app starts that browser, not emunium, so connect only waits for the extension. close() detaches and leaves the profile running. Such a profile usually sends a Chrome user agent, so browser_name is None and the window is not brought to the foreground unless you pass browser=.

Example with a Dolphin Anty profile, started and stopped through Dolphin’s local API:

import json import urllib.error import urllib.request from emunium import Browser DOLPHIN_API = "http://localhost:3001/v1.0/browser_profiles" PROFILE_ID = "123456789" def dolphin(action: str) -> dict: """One call to the Dolphin Anty local API; returns its JSON answer.""" url = f"{DOLPHIN_API}/{PROFILE_ID}/{action}" try: with urllib.request.urlopen(url, timeout=60) as response: body = response.read() except urllib.error.HTTPError as exc: body = exc.read() # e.g. 409 with PROFILE_ALREADY_RUNNING in the JSON except urllib.error.URLError as exc: raise SystemExit(f"Dolphin Anty API unreachable: {exc.reason}") from exc try: return json.loads(body) except ValueError: raise SystemExit(f"Dolphin Anty {action}: not JSON: {body[:200]!r}") from None started = dolphin("start") if not started.get("success") and started.get("code") != "PROFILE_ALREADY_RUNNING": raise SystemExit(f"Dolphin Anty start failed: {started}") try: with Browser.connect(start=False, timeout=90) as browser: browser.goto("https://example.com/") print(browser.title) finally: dolphin("stop")

The API paths and authentication follow Dolphin’s local API documentation and can differ between versions. Whether an extension stays installed in a profile depends on the vendor’s plan (Dolphin’s free plan removes extensions added by hand); emunium does not manage that.