oculr (Python)

Thin Python client for the Oculr local Automation API. Launch real browser profiles on your own machine, choose a per-launch stealth level, and connect over CDP with Playwright or Selenium.

Zero runtime dependencies (stdlib only). Playwright is optional, for the connect_playwright() helper.

Install

pip install oculr
# optional, for connect_playwright():
pip install playwright

Usage

import os
from oculr import OculrClient
from playwright.sync_api import sync_playwright

# The desktop app shows the port and token under Settings.
oculr = OculrClient("http://127.0.0.1:8378", token=os.environ["OCULR_TOKEN"])

# Low-level: launch and get a ready CDP endpoint + driver recipes.
res = oculr.launch("de-store-01", stealth="balanced", headless=False)
print(res["ws_endpoint"])

# High-level: launch and connect a Playwright browser in one call.
with sync_playwright() as p:
    browser, _ = oculr.connect_playwright(p, "de-store-01", stealth="max")
    page = browser.contexts[0].pages[0]
    page.goto("https://example.com")
    oculr.stop("de-store-01")

Stealth dial

stealth is chosen per launch: "off" (clean Chromium, no fingerprint injection), "balanced" (native fingerprints, the default) or "max" (strongest noise). Overrides apply to that launch only and are never written back to the profile.

API

list_profiles(), create_profile(**body), get_profile(id), update_profile(id, **body), delete_profile(id), generate_profile(**body), launch(id, **options), stop(id), status(), connect_playwright(playwright, id, **options).

Errors raise OculrError with .status and .body.