Docs
⌘K
Browser ›

Enable browser

PUT/v1/sandboxes/{id}/browser

Turns the sandbox's browser on to be driven from outside it: Chrome is started in the sandbox's machine with its DevTools on, and the answer says where to connect. The sandbox has to be running. With no body, a browser that is on keeps what it has, and one turned on now is on the desktop when a desktop is turned on for the sandbox, and has no window when none is. Asked again as it is, it changes nothing that is already so, and starts a browser that had ended. Asked otherwise, Chrome is started again so, which closes what was open in it. From then on Chrome ends when the sandbox stops and is started again by itself when it runs again, with nothing open in it. What it remembers, as cookies and logins, is kept on the sandbox's disk.

RequestTypeScript
  1. import { Agental } from "agental-sdk";
  3. const agental = new Agental();
  4. const sandbox = await agental.sandboxes.get("sbx_2a9a47e50daec64a");
  5. const browser = await sandbox.browser.on();
Answer200 OK · BrowserState
  1. {
  2. "enabled": boolean,
  3. "enabledAt": string | null,
  4. "running": boolean,
  5. "headless": boolean | null,
  6. "cdpUrl": string | null,
  7. "localCdpUrl": string | null,
  8. }

The browser is on, and this is where to connect to it.

Path

idrequired
string
 e.g. "sbx_0123456789abcdef"

Headers

Authorizationrequired
Bearer key
An API key that may make this call.

Body

headless
boolean
true for a Chrome with no window, false for one on the desktop, which needs a desktop turned on.

Returns

200 The browser is on, and this is where to connect to it.

BrowserState6 fields
enabled
boolean
Whether the browser is turned on for the sandbox.
More It stays so through a stop and a start, and a move to another server: Chrome is started again by itself, with nothing open in it.
enabledAt
stringnull
Since when it is on.
More Null when it is off.
running
boolean
Whether Chrome is running in the sandbox's machine now and its DevTools answer.
More False while it is off, while the sandbox is not running, in the moments after a start before it is up again, and while a Chrome that is on the desktop waits for the desktop to be turned on.
headless
booleannull
Whether Chrome has no window.
More False when it is on the desktop, where it is watched as it is driven. Null while it is off.
cdpUrl
stringnull
Where Chrome's DevTools are reached from outside the sandbox, over a WebSocket: what Playwright's connectOverCDP, Puppeteer's connect, browser-use and Stagehand are given.
More It needs no token and is hard to guess, and whoever has it has the whole browser, with what it is signed in to, so it is to be kept as a password is. It stays the same through a stop and a start, and is another each time the browser is turned on. Null while the browser is not running, and where GET /v1/policy says publicUrls is false.
localCdpUrl
stringnull
Where the same DevTools are reached from inside the sandbox, as by playwright-cli attach --cdp.
More Null while the browser is off.

Errors and other answers

404 Not found.
409 sandbox_not_running; desktop_not_running: Chrome was to be on the desktop, and no desktop is turned on; or browser_unavailable: the sandbox's machine was made from an image that cannot run its browser to be driven from outside, or Chrome did not start. The message says which. A sandbox made now can.
501browser_not_configured sandboxes here have no browser to drive from outside. GET /v1/policy says so as browser.

Every error answers { "error": { "code", "message" } }; a key without the action a call needs answers 403 key_action_forbidden, naming it.

← Get browserDisable browser →