browser

Start Chromium in the sandbox and return its CDP address.

Starts Chromium with the Chrome DevTools Protocol on the sandbox's loopback (port 9222, for code inside the sandbox) and returns cdpUrl, a private wss address for agents outside it. Chromium comes from the host as a read-only disk, so a start in a new sandbox takes about 1 to 2 seconds and installs nothing. A sandbox from a custom image that is not Ubuntu 24.04 x86_64, or on a host without the layer, installs Chromium on its first start (about a minute, once; 409 browser_installing until then, which the SDKs wait for). Idempotent: a running browser is returned as it is. Needs exec.

post/v1/sandboxes/{id}/browser:start

Request

  • Base URL: https://api.withruntime.com
  • URL: https://api.withruntime.com/v1/sandboxes/{id}/browser:start
  • Auth: HTTP bearer

Path parameters

idstring required

Resource identifier (UUID).

Headers

Idempotency-Keystring

Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header.

Request body

headlessboolean

true (the default): no window. false: on the sandbox's desktop, which this starts, with a live view.

widthinteger

Window width in pixels. Default 1280.

heightinteger

Window height in pixels. Default 800.

Response

Success

runningboolean required
headlessboolean
versionstring

Chromium's version, e.g. "Chrome/154.0.8037.92".

cdpUrlstring

The browser's DevTools WebSocket, with its private preview token: give it to Playwright's connectOverCDP, puppeteer.connect({browserWSEndpoint}), browser-use or Stagehand as it is.

httpUrlstring

The DevTools HTTP endpoint (json/version and the rest); send headers with it.

headersobject
expiresAtstring nullable

When the token in cdpUrl ends; GET the browser again for a fresh one.

streamUrlstring

headless: false only: the desktop's live view.

memoryMiBinteger

browser:start only: the sandbox's memory, which is the browser's.

hintstring

browser:start only, under 2048 MiB: heavy apps such as Google Sheets, YouTube and StackBlitz need a 2 GiB sandbox; 1 GiB suits light pages.

Changes

No recorded changes to this operation across all 1 revision of this API.