Skip to content
Registry

browser

v0.2.28

A browser on the iii bus - shared Chromium with persistent, restorable tabs and incognito tabs. Navigate, act, read the page console, pick elements. Also parses HTML natively without a browser (browser::* - css/xpath/regex, element search, markdown).

license: Apache-2.0automationbrowsercdpchromiumextractionparsingscrapingweb

Install

bash
iii trigger compose::add worker=browser@0.2.28

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Functions25

browser::act

Function

Interact with the page: click (left/right/middle, single or double), hover, type, select a native <select> option, press, scroll, or drag (press at the start point, glide to x2/y2, release). Address elements with a ref from browser::elements (`n4`), browser::snapshot (`e3`) or a pick, or raw viewport coordinates. A ref is scrolled into view first, and a click, type or select on a disabled, hidden or covered element is refused instead of landing on whatever is on top. Typing into an input or textarea by ref replaces its value. Returns once the page had a moment to react.

Request
  • actionstringrequired

    `click`, `hover`, `type`, `select`, `press`, `scroll`, or `drag`.

  • buttonstring

    Mouse button for `click`: `left` (default), `right`, or `middle`.

  • click_countinteger· uint32min 0

    Clicks in the gesture: 2 double-clicks (`click` only, default 1).

  • delta_ynumber· double

    Scroll distance in pixels; positive scrolls down (`scroll`).

  • keystring

    Key name for `press`: Enter, Tab, Escape, Backspace, Delete, ArrowUp/Down/Left/Right, Home, End, PageUp, PageDown.

  • optionstring

    Option to choose (`select`, native `<select>` only): its value or visible label.

  • refstring

    Element ref from `browser::elements` (`n4`), `browser::snapshot` (`e3`), `browser::dom::read` (`d7`) or `browser::picked` (`p1`). A click, type or select by ref is refused when the element is disabled, hidden or covered. Refs die on navigation; re-read the page after.

  • session_idstringrequired
  • textstring

    Text to insert (`type`). With a ref to an `<input>` or `<textarea>` it replaces the current value; otherwise it is inserted at the caret.

  • xnumber· double

    Viewport x, when acting by coordinates instead of ref.

  • x2number· double

    Drag end x, in viewport pixels (`drag`). The start is `x`/`y` or a `ref`; the end is `x2`/`y2`.

  • ynumber· double

    Viewport y, when acting by coordinates instead of ref.

  • y2number· double

    Drag end y, in viewport pixels (`drag`).

Response
  • detailstringrequired

    What was done, for the transcript.

  • okbooleanrequired

browser::chromium::install

Function

Download Chromium (Chrome for Testing, Stable, about 200 MB) into the worker's cache (~/.cache/iii/browser/chrome) for a machine with no Chrome or Chromium. Returns at once with a job_id; progress arrives on the browser::chromium-install-progress trigger and in browser::chromium::status. A Chrome installed on the system still takes precedence. Does nothing when a Chromium is already found, unless force=true.

Request
  • forceboolean

    Download even when a Chromium is already found (a system one, or the same version already downloaded).

Response
  • job_idstring

    The install job; its progress arrives on the `browser::chromium-install-progress` trigger and in `browser::chromium::status` (`job`). Absent for `already-installed`.

  • pathstring
  • statusone ofrequired
    one of (3)
    Variant 1
    valuestringenum started
    Variant 2
    valuestringenum running
    Variant 3
    valuestringenum already-installed
  • versionstring

browser::chromium::status

Function

Whether this machine has a Chromium the worker can launch: the binary, its version, where it came from (config, $CHROME, a system install, the copy browser::chromium::install downloaded, or a Playwright/Puppeteer cache), every place searched, whether a download is available here, and the latest install job. Read-only; never starts a browser.

Request
Empty object
Response
  • enginestringrequired

    The configured interactive engine (`chromium` or `lightpanda`). Scrapling's browser tiers use Chromium either way.

  • foundbooleanrequired

    A Chromium the worker can launch exists.

  • installobjectrequired

    Whether `browser::chromium::install` can download a Chromium here.

    • approx_download_mbinteger· uint64requiredmin 0

      Roughly how big the download is.

    • dirstringrequired

      Where the download is kept (`III_BROWSER_CACHE_DIR`, else `${XDG_CACHE_HOME:-~/.cache}/iii/browser`, plus `/chrome`).

    • platformstring

      Chrome for Testing platform: `linux64`, `linux-arm64`, `mac-arm64`, `mac-x64`, or `win64`.

    • reasonstring

      Why there is no download here (unsupported platforms).

    • supportedbooleanrequired

      A Chrome for Testing build exists for this platform.

  • jobany of

    This worker's latest install job, running or finished.

    any of (2)
    Variant 1
    • bytes_doneinteger· uint64requiredmin 0

      Bytes downloaded (downloading) or unpacked (extracting) so far.

    • bytes_totalinteger· uint64min 0

      Total for `bytes_done`, when known.

    • errorstring

      What went wrong (failed).

    • hintstring

      How to fix it, when known (failed) — e.g. the system packages a Linux machine is missing.

    • job_idstringrequired
    • pathstring

      The installed binary (done).

    • phaseone ofrequired
      Show 6 nested
      one of (6)
      Variant 1
      valuestringenum resolving
      Variant 2
      valuestringenum downloading
      Variant 3
      valuestringenum extracting
      Variant 4
      valuestringenum verifying
      Variant 5
      valuestringenum done
      Variant 6
      valuestringenum failed
    • timestampinteger· int64required
    • versionstring

      Chrome for Testing version being installed, once known.

    Variant 2
    valuenull
  • pathstring

    The binary sessions launch.

  • sandboxedboolean

    False when sessions launch this Chromium with `--no-sandbox` (a cache copy on a Linux that blocks the user-namespace sandbox).

  • searchedstring[]required

    The places looked, in order.

  • sourceany of

    Where it came from: `configured`, `env`, `system`, `managed` (the download), `playwright`, or `puppeteer`.

    any of (2)
    Variant 1
    one of (6)
    Variant 1
    valuestringenum configured
    Variant 2
    valuestringenum env
    Variant 3
    valuestringenum system
    Variant 4
    valuestringenum managed
    Variant 5
    valuestringenum playwright
    Variant 6
    valuestringenum puppeteer
    Variant 2
    valuenull
  • versionstring

    `<binary> --version`, first line.

browser::console::read

Function

Read the session's captured console: console.* calls, uncaught exceptions, and browser-level log entries. Filter with pattern/level and page with since_seq instead of dumping everything.

Request
  • levelstring

    Only entries at this level: `log`, `info`, `warning`, `error`, `debug`, `exception`. `error` also matches `exception`.

  • limitinteger· uint64min 0

    Maximum entries returned, newest kept (default 100).

  • patternstring

    Regex applied to entry text. Use it: dumping an unfiltered console wastes the caller's context.

  • session_idstringrequired
  • since_seqinteger· uint64min 0

    Only entries with `seq` greater than this; resume from the cursor returned as `last_seq`.

Response
  • droppedinteger· uint64requiredmin 0

    Entries evicted from the ring buffer since session start.

  • entriesobject[]required
    • levelstringrequired

      `log`, `info`, `warning`, `error`, `debug`, or `exception`.

    • seqinteger· uint64requiredmin 0

      Monotonic per-session cursor; pass back as `since_seq`.

    • sourcestring

      `url:line` of the emitting frame, when known.

    • textstringrequired
    • timestampinteger· int64required
  • last_seqinteger· uint64requiredmin 0

    Cursor for the next `since_seq`.

browser::doctor

Function

Diagnose the browser environment: which Chromium the worker would launch, its version, session capacity, and any degraded capability with how to enable it. Never starts a browser.

Request
Empty object
Response
  • active_sessionsinteger· uint64requiredmin 0

    Tabs with a page open right now.

  • allow_cookie_importbooleanrequired
  • allow_history_accessbooleanrequired
  • allowed_schemesstring[]required
  • attach_enabledbooleanrequired

    Whether attach mode is enabled (allow_attach).

  • browser_runningbooleanrequired

    Whether the shared Chromium process is running.

  • chromium_pathstring

    The engine binary the worker would launch (a Chromium/Chrome, or the `lightpanda` binary). The field name predates the `engine` setting.

  • chromium_sourceany of

    Where the Chromium came from: `configured`, `env`, `system`, `managed` (downloaded by browser::chromium::install), `playwright`, or `puppeteer`. Absent for Lightpanda or when nothing was found.

    any of (2)
    Variant 1
    one of (6)
    Variant 1
    valuestringenum configured
    Variant 2
    valuestringenum env
    Variant 3
    valuestringenum system
    Variant 4
    valuestringenum managed
    Variant 5
    valuestringenum playwright
    Variant 6
    valuestringenum puppeteer
    Variant 2
    valuenull
  • chromium_versionstring

    `<binary> --version`, first line.

  • configured_origin_policiesinteger· uint64requiredmin 0
  • data_dirstringrequired

    Where the profile, downloads and tab list live.

  • default_origin_policy_setbooleanrequired
  • enginestringrequired

    Configured engine: `chromium` or `lightpanda`.

  • headless_defaultbooleanrequired
  • issuesobject[]required
    • enable_howstringrequired
    • whatstringrequired
  • max_sessionsinteger· uint64requiredmin 0

    Live-tab cap (`max_sessions`).

  • okbooleanrequired

    True when sessions can start right now.

  • open_tabsinteger· uint64requiredmin 0

    Every tab, live or asleep.

  • recording_availablebooleanrequired

    Whether ffmpeg is on PATH, which browser::recording requires.

browser::dom::read

Function

Read the DOM as a tree of tags with id/class and refs. Structure-oriented complement to browser::snapshot; read deep subtrees by passing a ref.

Request
  • depthinteger· uint32min 0

    Levels of children to include (default 3).

  • refstring

    Subtree root from an earlier ref (`e3`/`p1`) or dom node. Omit for the document root.

  • session_idstringrequired
Response
  • rootobjectrequired

    One DOM node in the outline. `ref` resolves in `browser::act`, `browser::styles::read`, and `browser::styles::write`.

    • child_countinteger· uint32requiredmin 0

      Total children in the document, which may exceed `children` returned at this depth.

    • childrenunknown[]
    • classesstring
    • idstring
    • refstringrequired
    • tagstringrequired

      Lowercase tag (`div`, `button`) or node name (`#text`).

    • textstring

      Trimmed text content for text nodes.

  • truncatedbooleanrequired

    True when the node cap cut the tree short; read a subtree via `ref`.

browser::elements

Function

The page's visible, enabled controls in the viewport as an indexed table (ref, role, label, current value, checked/expanded state, what browser::act can do with each, and <select> options), plus the visible text, from one read. Cheaper and flatter than browser::snapshot: use it to drive forms and read what an action changed. Refs (`n4`) stay valid while the element stays in the document.

Request
  • session_idstringrequired
Response
  • busyboolean

    The page is still loading: the document, a region marked `aria-busy`, or (in `browser::run`) requests an action started that had not finished when the run stopped waiting.

  • can_scroll_downbooleanrequired
  • can_scroll_upbooleanrequired
  • elementsobject[]required

    Visible, enabled controls inside the viewport, in document order.

    • autocompletestring

      The field's `autocomplete` hint (`username`, `current-password`, …).

    • checkedstring
    • expandedstring
    • input_typestring

      `<input>` type when not `text` (`email`, `password`, `tel`, …).

    • labelstringrequired

      Accessible name (aria-labelledby, aria-label, label, text, title, or placeholder).

    • more_optionsinteger· uint32min 0

      Options beyond the listed 50; `select` still accepts them by label.

    • namestring

      The field's `name` (or `id`).

    • operationsstring[]required

      `click`, `type` and/or `select`.

    • optionsstring[]

      Enabled `<select>` option labels (first 50), for `act` `select`.

    • refstringrequired

      `n` ref `browser::act` accepts; valid while the element stays in this document.

    • rolestringrequired
    • selectedstring
    • valuestring

      Current value of a field or dropdown; a set password reads `(set)`.

  • generationinteger· uint64min 0

    Document generation; navigation advances it and every `n` ref dies.

  • omittedinteger· uint32requiredmin 0

    Controls past the 250-element cap, not listed.

  • textstringrequired

    Visible text in the viewport, up to 6000 characters.

  • titlestringrequired
  • urlstringrequired

browser::evaluate

Function

Evaluate a JavaScript expression in the page and return its completion value. Use for reads the snapshot can't express; prefer browser::act for interactions.

Request
  • expressionstringrequired

    JavaScript expression evaluated in the page. The completion value is returned by value; wrap statements in an IIFE.

  • session_idstringrequired
  • timeout_msinteger· uint64min 0

    Upper bound on evaluation; clamped to `max_timeout_ms`.

Response
  • errorstring

    Exception text when not `ok`.

  • okbooleanrequired
  • valueunknown

    JSON completion value when `ok`.

browser::execute

Function

Run a multi-step async JavaScript script in the page: top-level await and return work, with log(...), sleep(ms), waitFor(selector), and a state object that persists across execute calls for the session. One call replaces a chain of act/evaluate round-trips; returns { result, logs, state }.

Request
  • codestringrequired

    Async JavaScript body run in the page; `state`, `log(...)`, `sleep(ms)` and `waitFor(selector, { timeout })` are in scope. Return plain JSON.

  • session_idstringrequired
  • timeout_msinteger· uint64min 0

    Upper bound on the run; clamped to `max_timeout_ms`.

Response
  • errorstring

    Exception text when not `ok`. A "context destroyed" error usually means the script navigated; split the script at the navigation.

  • logsstring[]required

    `log(...)` output collected during the run, in order.

  • okbooleanrequired
  • resultunknown

    The script's return value when `ok`.

  • stateunknownrequired

    Session state after the run; the next execute call sees this as `state`.

browser::handoff

Function

Pause a session for a step only a human can do (CAPTCHA, 2FA, payment): show an in-page continue banner and block until the human clicks it, a browser::handoff::confirm call resolves it, or the timeout elapses. Human acknowledgment is not proof — verify the expected page state after it returns.

Request
  • instructionsstringrequired

    What the human must do before the call continues. Shown in the in-page banner and the handoff-requested event.

  • session_idstringrequired
  • timeout_msinteger· uint64min 0

    Give up after this many ms and return `via: "timeout"` (clamped to `max_timeout_ms`); set generously, a human is slow.

Response
  • confirmedbooleanrequired

    True when a human confirmed; false when the wait timed out.

  • handoff_idstringrequired
  • urlstringrequired

    The page URL when the wait ended, so the caller can verify the step actually landed (human acknowledgment is not proof).

  • viastringrequired

    How the confirmation arrived: `in_page`, `confirm_call`, or `timeout`.

browser::handoff::confirm

Function

Resolve a paused browser::handoff by handoff_id, or the one pending handoff for a session_id. The console calls this when the human confirms outside the page.

Request
  • handoff_idstring

    Confirm a specific handoff by id. Omit to confirm the one pending handoff for `session_id`.

  • session_idstring
Response
  • handoff_idstring
  • okbooleanrequired

    True when a pending handoff matched and was resolved.

browser::history

Function

Go back, go forward, or reload the tab's page. History survives the tab sleeping and the worker restarting. Back/forward at the history edge is a no-op with moved=false.

Request
  • actionstringrequired

    `back`, `forward`, or `reload`.

  • session_idstringrequired
Response
  • movedbooleanrequired

    False when back/forward had no entry to move to.

  • okbooleanrequired
  • urlstringrequired

    URL after the action. `back`/`forward` at the history edge is a no-op with ok=true.

browser::navigate

Function

Navigate a tab to a URL and wait for the page to load. Like a browser, a network failure or an empty HTTP error response leaves Chromium's error page in the tab and is reported in `error` rather than failing the call. Element refs from earlier snapshots are invalidated by navigation.

Request
  • session_idstringrequired
  • timeout_msinteger· uint64min 0

    Upper bound on the navigation wait; clamped to `max_timeout_ms`.

  • urlstringrequired

    Absolute URL; scheme must be on the configured allowlist.

Response
  • errorstring

    Chromium's error text when the navigation ended on the browser's own error page: a network failure (`net::ERR_NAME_NOT_RESOLVED`), or an empty HTTP error response (`net::ERR_HTTP_RESPONSE_CODE_FAILURE`, a 4xx/5xx with no body). Like a browser, the tab still shows that page and stays usable.

  • okbooleanrequired

    False when the tab shows Chromium's error page instead of the site; see `error`.

  • timed_outbooleanrequired

    True when the load event did not fire inside the timeout; the page may still be usable; snapshot to check.

  • titlestring
  • urlstringrequired

    URL after redirects.

browser::network::read

Function

Read the session's captured network requests (method, URL, status, failures). failed_only=true is the fast path for 'what broke'.

Request
  • failed_onlyboolean

    Only failed requests (network error or status >= 400).

  • limitinteger· uint64min 0

    Maximum entries returned, newest kept (default 100).

  • patternstring

    Regex applied to the request URL.

  • session_idstringrequired
  • since_seqinteger· uint64min 0

    Only entries with `seq` greater than this.

Response
  • droppedinteger· uint64requiredmin 0

    Entries evicted from the ring buffer since session start.

  • entriesobject[]required
    • errorstring
    • failedbooleanrequired
    • methodstringrequired
    • mime_typestring
    • seqinteger· uint64requiredmin 0

      Monotonic per-session cursor; pass back as `since_seq`.

    • statusinteger· int64
    • timestampinteger· int64required
    • urlstringrequired
  • last_seqinteger· uint64requiredmin 0

    Cursor for the next `since_seq`.

browser::run

Function

Drive the page toward a goal in one call (fill and submit a form, log in, pick filters, step through a wizard): each step reads the visible controls, asks the judge worker which operation (click, type, select, scroll, wait, done, blocked) and which element, acts, and waits for the requests the action started, until the judge says done or blocked, a field needs text you did not give in `inputs`, nothing changes three times, or the step/time budget runs out. State the goal as the end state to reach ("logged in: the dashboard shows"), not the clicks. Returns the steps taken and the final page table; read it before reporting success, done is the judge's reading, not proof (a login can end on an error). Without a judge worker it returns status judge_unavailable with the page table: drive with browser::elements and browser::act instead.

Request
  • goalstringrequired

    The end state to reach, as the page would show it ("logged in: the dashboard shows", "the bug is saved and listed"), not the clicks to make. Name every value the outcome needs.

  • inputsobject

    Text for fields the goal needs filled: `{"email": "…", "password": "…"}`. A key reaches a field by its `n` ref, by its label (case, accents and punctuation ignored: `email` for "E-mail"), by what the field is (input type, `name`, `autocomplete`: `password` for a password field labelled "Senha"), or as the only key the label contains. Only the keys are shown to the judge.

  • max_stepsinteger· uint32min 0

    Most actions to execute (default 10, at most 60).

  • session_idstringrequired
  • timeout_msinteger· uint64min 0

    Whole-run budget in ms (default 30000), clamped to `max_timeout_ms`.

Response
  • elapsed_msinteger· uint64requiredmin 0
  • judge_requestsinteger· uint32requiredmin 0
  • needs_textany of
    any of (2)
    Variant 1
    • input_keysstring[]required

      The `inputs` keys the run was given, none of which matched this field.

    • labelstringrequired
    • refstringrequired
    Variant 2
    valuenull
  • pageall ofrequired

    The page as the run left it (`browser::elements` shape).

    all of (1)
    Variant 1
    • busyboolean

      The page is still loading: the document, a region marked `aria-busy`, or (in `browser::run`) requests an action started that had not finished when the run stopped waiting.

    • can_scroll_downbooleanrequired
    • can_scroll_upbooleanrequired
    • elementsobject[]required

      Visible, enabled controls inside the viewport, in document order.

      Show 13 nested
      • autocompletestring

        The field's `autocomplete` hint (`username`, `current-password`, …).

      • checkedstring
      • expandedstring
      • input_typestring

        `<input>` type when not `text` (`email`, `password`, `tel`, …).

      • labelstringrequired

        Accessible name (aria-labelledby, aria-label, label, text, title, or placeholder).

      • more_optionsinteger· uint32min 0

        Options beyond the listed 50; `select` still accepts them by label.

      • namestring

        The field's `name` (or `id`).

      • operationsstring[]required

        `click`, `type` and/or `select`.

      • optionsstring[]

        Enabled `<select>` option labels (first 50), for `act` `select`.

      • refstringrequired

        `n` ref `browser::act` accepts; valid while the element stays in this document.

      • rolestringrequired
      • selectedstring
      • valuestring

        Current value of a field or dropdown; a set password reads `(set)`.

    • generationinteger· uint64min 0

      Document generation; navigation advances it and every `n` ref dies.

    • omittedinteger· uint32requiredmin 0

      Controls past the 250-element cap, not listed.

    • textstringrequired

      Visible text in the viewport, up to 6000 characters.

    • titlestringrequired
    • urlstringrequired
  • reasonstring
  • statusone ofrequired
    one of (6)
    Variant 1
    valuestringenum max_steps, deadline
    Variant 2
    valuestringenum done
    Variant 3
    valuestringenum blocked
    Variant 4
    valuestringenum stalled
    Variant 5
    valuestringenum needs_text
    Variant 6
    valuestringenum judge_unavailable
  • stepsobject[]required

    Executed actions, in order.

    • errorstring

      Why the action was refused or failed; the page was re-read and the judge asked again.

    • judge_msinteger· uint64requiredmin 0
    • labelstring
    • operationstringrequired

      CLICK, TYPE_TEXT, SELECT, SCROLL_UP, SCROLL_DOWN or WAIT.

    • optionstring

      The option chosen (SELECT).

    • page_changedbooleanrequired
    • probabilitynumber· doublerequired

      The judge's probability for the executed choice.

    • refstring

browser::screencast::start

Function

Internal: start the live viewport feed — frames arrive on the browser::frame-event trigger and browser::frame reads the newest. Console-UI plumbing; agents use browser::screenshot. Not an agent function.

Request
  • previewboolean

    A corner thumbnail rather than a pane: streams frames but does not count as a viewer for `browser::resize` fit arbitration.

  • session_idstringrequired
Response
  • okbooleanrequired

browser::screenshot

Function

Screenshot the session's current page as a JPEG (or a lossless PNG with format=png). Use browser::snapshot for machine-readable structure; screenshot when layout or rendering matters.

Request
  • formatstring

    `jpeg` (default, compressed with the configured quality) or `png` (lossless; what pixel comparisons need).

  • full_pageboolean

    Capture the full scrollable page instead of the viewport.

  • session_idstringrequired
Response
  • contentobject[]required
    • datastring
    • mimestring
    • textstring
    • typestringrequired
  • detailsobjectrequired
    • heightinteger· uint32requiredmin 0
    • session_idstringrequired
    • urlstringrequired
    • widthinteger· uint32requiredmin 0

browser::sessions::attach

Function

Attach a session to an already-running browser over CDP. Opens a fresh tab the session owns, or adopts a user tab by URL substring and releases it untouched on stop. Reaches the real profile and its logins; needs Chrome started with --remote-debugging-port and allow_attach in config.

Request
  • adopt_url_substringstring

    Adopt the one open tab whose URL contains this substring (released untouched on stop); omit to open a fresh tab the session owns.

  • cdp_urlstringrequired

    CDP endpoint of the running browser: `http://127.0.0.1:9222` (resolved via `/json/version`) or a `ws://` debugger URL.

  • read_onlyboolean

    Inspection-only session; see browser::sessions::start.

  • urlstring

    URL to open in the fresh tab (ignored when adopting). Omit for about:blank.

Response
  • adoptedbooleanrequired

    True when the session adopted an existing user tab (released, not closed, on stop); false when it opened a fresh tab it owns.

  • read_onlybooleanrequired
  • session_idstringrequired
  • urlstringrequired

browser::sessions::list

Function

List every browser tab, live or asleep, with its current URL, title, and activity.

Request
Empty object
Response
  • sessionsobject[]required
    • activebooleanrequired

      True while the tab has its page open. A sleeping tab (false) is listed and usable; the next call on it reopens the page at `url`.

    • console_entriesinteger· uint64requiredmin 0

      Console entries captured since the page opened; 0 while asleep.

    • created_msinteger· int64required
    • headlessbooleanrequired
    • incognitobooleanrequired

      Private tab: nothing persisted, closes instead of sleeping.

    • last_used_msinteger· int64required
    • read_onlybooleanrequired
    • session_idstringrequired
    • titlestring
    • ttl_msinteger· uint64min 0

      Lifetime the tab was opened with, when any.

    • urlstringrequired

browser::sessions::start

Function

Open a browser tab (a session) and return its session_id. Tabs share one browser profile (cookies, logins) and stay open until stopped or until an optional ttl_ms; an unused tab sleeps and wakes on the next call. incognito=true opens a PRIVATE tab: nothing it does is saved, and inactivity closes it for good.

Request
  • headfulboolean

    Force a visible window, overriding the configured `headless` default. Applies when this call launches the browser process; a browser that is already running keeps its mode.

  • incognitoboolean

    INCOGNITO TAB. Opens the tab in a private browser context: it shares no cookies, logins, or storage with the regular tabs, nothing it does is saved to disk (no cookies, no history, no tab record), it does not come back after a restart, and inactivity closes it for good instead of putting it to sleep. Everything lives in memory for as long as the tab does. Use it for logins you do not want kept, or to see a site signed out.

  • previewboolean

    Whether consoles pop a live preview of the new tab (default true). The console's own tab controls pass `false`: the page that opened the tab already shows it, in every console window. Agents leave it.

  • read_onlyboolean

    Inspection-only session for its whole lifetime: act, evaluate, execute and styles::write are rejected; navigation and reads work.

  • ttl_msinteger· uint64min 0

    Optional lifetime in milliseconds: the tab closes on its own this long after it opened, even while in use. Omit for a tab that stays until stopped (what the console does).

  • urlstring

    URL to open immediately. Omit to start on about:blank.

Response
  • errorstring

    Chromium's error text when the requested url did not load and the tab shows the browser's error page instead (a network failure, or an empty HTTP error response such as a 400). Absent when the page came up. The tab is open either way.

  • headlessbooleanrequired
  • incognitobooleanrequired

    True for a private tab; see `incognito` on the request.

  • read_onlybooleanrequired
  • session_idstringrequired

    Pass this to every other browser function.

  • timed_outbooleanrequired

    True when the requested url's load event did not fire inside the default navigation timeout; the tab is open and the page may still be usable; snapshot to check.

  • urlstringrequired

browser::sessions::stop

Function

Close an interactive browser tab (a session from browser::sessions::start or attach) for good; do this when the task is done, since every tab holds a Chromium page. Idempotent: closing an unknown or already-closed tab succeeds with was_running=false. Scraping sessions from browser::session-open close with browser::session-close.

Request
  • session_idstringrequired

    Tab to close. Closing an unknown or already-closed id succeeds.

Response
  • okbooleanrequired
  • was_runningbooleanrequired

    False when the session was already gone.

browser::snapshot

Function

Read the page as an accessibility-tree outline. Lines carry [ref=eN] handles that browser::act accepts; refs stay valid until the next navigation. Prefer this over browser::screenshot; it is cheaper and machine-readable.

Request
  • diffboolean

    Return only what changed since the previous snapshot; a full outline when there is no baseline (first snapshot or after a navigation).

  • session_idstringrequired
Response
  • diffany of

    Present when the caller asked for `diff: true` and a baseline existed. Covers only the emitted nodes of both snapshots; check `truncated` before trusting it as a complete change set.

    any of (2)
    Variant 1
    • addedstring[]required
    • removedstring[]required
    • unchangedinteger· uint64requiredmin 0
    Variant 2
    valuenull
  • generationinteger· uint64requiredmin 0

    Document generation the refs belong to; navigation advances it and kills every ref from earlier generations.

  • titlestring
  • treestringrequired

    Indented outline; lines carry `[ref=eN]` handles for `browser::act`. Empty when `diff` is populated.

  • truncatedbooleanrequired

    True when the tree hit `max_snapshot_nodes` and was cut short. Also the signal that a `diff` may be incomplete: the diff is computed over emitted nodes only, so when either snapshot was truncated a node that was emitted before and capped out now can show up in `removed` even though it still exists (and vice versa for `added`).

  • urlstringrequired

browser::styles::read

Function

Read an element's computed styles (curated design set by default, or named properties) plus its inline style attribute.

Request
  • propertiesstring[]

    Computed property names to return. Omit for a curated design-panel set; pass `["*"]` for every computed property.

  • refstringrequired

    Element ref from `browser::snapshot`, `browser::dom::read`, or a pick.

  • session_idstringrequired
Response
  • inline_stylestring

    The element's inline `style` attribute, when present.

  • propertiesobject[]required
    • namestringrequired
    • valuestringrequired
  • refstringrequired

browser::styles::write

Function

Set one inline CSS property on an element, live in the page. Visual experiment only: the page's source files are untouched, and the edit dies with the next navigation.

Request
  • importantboolean

    Apply with `!important`.

  • propertystringrequired

    CSS property name (`background-color`).

  • refstringrequired

    Element ref to edit.

  • session_idstringrequired
  • valuestringrequired

    CSS value (`#101418`). Empty string removes the inline property.

Response
  • inline_stylestringrequired

    The element's inline `style` attribute after the edit.

  • okbooleanrequired

browser::tabs::list

Function

List the open tabs of a running browser reachable at a CDP endpoint (url, title, and whether a session already adopted each). Read-only; adopt one with browser::sessions::attach.

Request
  • cdp_urlstringrequired

    CDP endpoint of the running browser, as in browser::sessions::attach.

Response
  • tabsobject[]required
    • adoptedbooleanrequired

      True when a session already adopted this tab; it cannot be adopted again until that session stops.

    • titlestring
    • urlstringrequired

Triggers12

browser::chromium-install-progress

Trigger

A browser::chromium::install job moved: a new phase (resolving, downloading, extracting, verifying, done, failed) or about 1% more bytes. Not a session event: bind without a session_id filter.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::console-event

Trigger

A console/log/exception entry was captured on a session's page.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::download-changed

Trigger

A download started, progressed, or finished in a session.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::frame-event

Trigger

Internal: a live screencast frame of a watched tab (console viewport plumbing, high volume).

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::handoff-requested

Trigger

A session is paused waiting for a human to complete a step (CAPTCHA, 2FA, payment).

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::handoff-resolved

Trigger

A paused handoff finished (confirmed in page, by call, or timed out).

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::navigated

Trigger

The session's page committed a navigation.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::network-event

Trigger

A network request was captured (completed or failed) on a session's page.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::picked

Trigger

The human picked an element in inspect mode.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::session-started

Trigger

A browser tab opened and is ready.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::session-stopped

Trigger

A browser tab closed for good (stopped, idle, expired, or crashed).

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

browser::session-updated

Trigger

A browser tab woke up (page open again), went to sleep (page closed, tab kept), or its page's title changed.

Invocation
  • session_idstring

    Only deliver events for this browser session.

Return
valueunknown

Search the registry

Find workers, kits and executables, or jump to a page.