---
title: "Start Chromium in the sandbox and return its CDP address."
method: POST
path: "/v1/sandboxes/{id}/browser:start"
tags: ["browser"]
---

# Start Chromium in the sandbox and return its CDP address.

`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

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.

## Path parameters

- `id` string, required: Resource identifier (UUID).

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `headless` boolean: true (the default): no window. false: on the sandbox's desktop, which this starts, with a live view.
  - `width` integer: Window width in pixels. Default 1280.
  - `height` integer: Window height in pixels. Default 800.

## Response `200`

Success

- object
  - `running` boolean, required
  - `headless` boolean
  - `version` string: Chromium's version, e.g. "Chrome/154.0.8037.92".
  - `cdpUrl` string: 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.
  - `httpUrl` string: The DevTools HTTP endpoint (json/version and the rest); send headers with it.
  - `headers` object
  - `expiresAt` string, nullable: When the token in cdpUrl ends; GET the browser again for a fresh one.
  - `streamUrl` string: headless: false only: the desktop's live view.
  - `memoryMiB` integer: browser:start only: the sandbox's memory, which is the browser's.
  - `hint` string: 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.

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/withruntime/apis/runtime-cloud-api.md) · [All operations](https://skmtc.dev/withruntime/apis/runtime-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/withruntime/apis/runtime-cloud-api/revisions/6f4012286988?raw)