A browser session is driven over its control URL: a WebSocket URL with a short-lived token scoped to that one session. Browser.connect() opens it and performs the DCP handshake.
from halyard import Browser

browser = Browser.connect()   # inside a sandbox: reads HALYARD_CONTROL_URL
page = browser.page

Browser.connect()

Open a session’s control socket and return a Browser.
Browser.connect(control_url=None, *, timeout=60.0, client=None)
ParameterTypeDefaultDescription
control_urlstr | NoneHALYARD_CONTROL_URLThe session’s control URL. Raises ValueError when neither is set.
timeoutfloat60.0Seconds to wait for any one reply before giving up. Locator and page timeouts are separate and shorter.
clientstr | NoneNoneA short lowercase name (up to 32 characters) for an extra connection beside the main one.
Returns Browser. Raises NotConnectedError when the socket can’t open, for any reason: a refused or expired token, an ended session, or a network failure. The message says which. TimeoutError when the handshake gets no reply within timeout.

One connection per session

A session keeps one driver connection. Opening a second one replaces the first, which is closed, so two scripts can’t fight over the same page by accident. To keep a second connection open beside the first, name it:
main = Browser.connect(url)
watcher = Browser.connect(url, client="watcher")   # sits beside main
Opening another connection with the same name replaces only that one.

Getting a control URL

Inside a Halyard sandbox, HALYARD_CONTROL_URL is set for you. Elsewhere, start a session with the session client and your API key:
from halyard import Client

with Client() as client:
    session = client.browsers.create(viewport={"width": 1440, "height": 900})
    try:
        with session.connect() as browser:
            ...
    finally:
        session.stop()

Client()

The session client. Reads the key from HALYARD_API_KEY when api_key is omitted.
Client(api_key=None, *, base_url=None, timeout=60.0)
ParameterTypeDefaultDescription
api_keystr | NoneHALYARD_API_KEYYour API key.
base_urlstr | NoneHALYARD_BASE_URL, then https://api.dominuslabs.comThe API’s origin, such as https://api.example.com, without /api/v1: the client adds the path.
timeoutfloat60.0HTTP timeout in seconds.
A request the API answers with an error status raises a HalyardError: UnauthorizedError for 401 and 403, ConflictError for 409, InvalidArgsError for 400 and 422. A network failure raises the httpx exception underneath, such as httpx.ConnectError.

client.browsers.create()

Start a browser session and return once it is ready to drive (up to 60 seconds).
client.browsers.create(*, viewport=None, tier=None, telemetry=None, **extra)
ParameterTypeDefaultDescription
viewportdict | None1920 x 1080{"width", "height", "pixel_ratio"} in CSS pixels.
tierstr | None"standard"Live-view video quality: standard, high or extra_high.
telemetrybool | NoneTrueFalse turns off the session’s event stream.
Returns BrowserSession, with id, status, control_url and the full response in data.

client.browsers.get() and client.browsers.stop()

client.browsers.get(session_id)     # -> BrowserSession
client.browsers.stop(session_id)    # ends the session

session.connect()

Open the session’s control socket: Browser.connect(session.control_url, timeout=timeout).
session.connect(*, timeout=60.0)
Returns Browser.

session.stop() and session.refresh()

stop() ends the session. refresh() re-reads it so status and data are current.