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 DIRThe 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().
| Option | Meaning |
|---|---|
browser=None | Browser to start, as in Browser(browser=...); also names browser_name |
user_data_dir=None | Profile root for a started browser (--user-data-dir, Firefox -profile); None opens the browser’s default profile. Never deleted |
profile_directory=None | Chromium profile inside it, e.g. "Profile 1"; not for Firefox |
start=True | Start the browser when no extension connects within 5 s; False only waits |
close_browser=False | close() also stops a browser that connect started; one that was already running always stays |
port=None | Hub port; None uses the stored one, which the build used |
install_id=None | Accept only this install (a UUID); None binds the first install that connects. A session serves one install; others are refused |
timeout=60.0 | Seconds to wait for the extension overall |
extra_args, verify_input, motion and typing work as for Browser().
close()detaches and leaves the browser running (unlessclose_browser=Trueandconnectstarted 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", elseNone; 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
timeoutabove that. - Errors:
LaunchErrorwhen 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);ImportErrorwithoutcryptography.
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.