#Browser API

aiod attaches to an existing Chromium; it does not launch the browser. Two environment variables decide where it attaches:

Use a CDP client such as Playwright or Puppeteer, or call the REST API directly. /v1/browser/* and /v2/browser/* use the same request bodies. The exception is desktop input: v1 uses POST /v1/browser/actions, while v2 uses /v2/computer. See Computer Use.

#What it needs

Below ready, the other tools are unavailable. See Sandbox.

#CDP

#Get the CDP URL

aiod asks the Chromium at BROWSER_REMOTE_DEBUGGING_HOST:PORT for /json/version, takes its webSocketDebuggerUrl, and rewrites it from the request headers:

# BASE_URL=https://sandbox.example.com
curl "$BASE_URL/v2/browser/info"

# BASE_URL=https://sandbox.example.com
curl "$BASE_URL/v1/browser/info"

{
  "data": {
    "cdp_url": "wss://sandbox.example.com/cdp/devtools/browser/46164812-5f92-4ec5-891a-8c138aeb93a4",
    "cdp_ui_url": null
  }
}

When Chromium does not answer, cdp_url still comes back in the same shape as a placeholder; call again once it recovers.

Playwright and Puppeteer connect to cdp_url directly; see Browser (CDP). Reverse proxies, path prefixes, and key parameters are covered on CDP Access.

#Send a raw CDP command

Use it for what REST does not cover. For a sequence of commands, connect over cdp_url instead.

#REST tools

For actions that don't need a full CDP client, aiod serves a small REST set. Every route returns the standard {success, message, data} envelope; full schemas are in the API Reference.

navigate, evaluate, snapshot, click, fill, upload, and cdp accept tab_id and use the first tab without it. screenshot does not accept tab_id and always captures the first tab.

#Navigate and evaluate

{
  "url": "https://example.com",
  "wait_until": "load"
}

• wait_until is load, domcontentloaded, networkidle, or commit; the default is load.
• timeout defaults to 30 seconds; a timeout answers 503, and the tab remains usable.
• history accepts back, forward, or reload.
• evaluate puts the result in data.value and JavaScript exceptions in data.exception; the HTTP status stays 200.

#Take a screenshot

format is png (default), jpeg, or jpg; quality is 0–100 for jpeg and defaults to 85. full_page=true captures the whole scrollable page. PNG responses carry x-image-width and x-image-height.

#Page snapshots

A ref comes from snapshot. Take a new snapshot after each navigation; refs from the old document are no longer valid.

#Tabs

A new tab goes to the head of the list and becomes the default target.

#Cookies

The shape is CDP's own. A cookie needs a name and either a url or a domain with a path; the other fields are optional.

#The request log

Collection starts on the first call and keeps the latest 300 requests. Interception and header rewriting are not supported.

#Window size

Omitting resolution leaves the window unchanged.

#Error semantics

JavaScript exceptions are not HTTP errors: evaluate answers 200 with data.exception.

#Desktop actions

Real mouse and keyboard events run on the computer-use worker rather than on the page, and answer 503 when it is not running.

#MCP tools

An MCP-capable agent calls browser tools through /mcp. The daemon itself carries browser_get_info, plus browser_gui_screenshot and browser_gui_execute_action when computer-use is available.

The AIO image runs @agent-infra/mcp-server-browser on loopback and registers it as an upstream of /mcp, which is where the image's page-level browser_* navigation tools come from. See MCP for how registration works.

#CDP, REST tools, or MCP

All three operate on the same Chromium:

Use CDP for full page automation, REST for common operations, and MCP when the agent already speaks MCP.

#Human in the loop

A person can watch or take over the Chromium the agent is driving. Both viewers attach to the same browser environment:

noVNC attaches to the desktop, not to one browser window, so the file dialog, the address bar and other application windows are all reachable, and the desktop survives a Chromium restart. The noVNC page embeds in an iframe.

Person and agent share one browser state: after a login completed in noVNC, the agent's next snapshot reads the logged-in page.

The daemon serves the API only; the image's gateway serves the noVNC and DevTools pages. Deployment and access are described on Computer Use.