Attach a sandbox to a browser (Beta)
Beta: give a sandbox its own window of the browser, or, with no sandbox, open a window for the person calling (or, with controller “agent”, for a client to drive over api_cdp_url). The response’s cdp_url is the Chrome DevTools endpoint the sandbox connects to, and api_cdp_url the same endpoint through the API; a client can open more tabs, which stay in its window. Windows share the browser’s cookies and logins. Keeping each sandbox to its own window is best effort, not a security boundary: attach only sandboxes you would trust with every login in the browser. With share_localhost, the browser can also reach the servers the sandbox runs, at the response’s localhost_alias. Attaching takes, for the browser and for the attached sandbox each, being its creator or a role with sandboxes:exec. With unrestricted, nothing is filtered: the window’s CDP clients (its sandbox, or anyone using its api_cdp_url) get the whole browser, including people’s windows, every site’s cookies, and commands that close it. It needs nothing beyond what any attach needs.
Authorizations
Path Parameters
Browser name or ID
Body
Controller is who drives a window opened with no sandbox: "user" (default) for a person in the live view, or "agent" for a client that drives it over api_cdp_url. A sandbox's window always starts with "agent".
agent, user 300 <= x <= 2400Name labels the window in the live view; defaults to the sandbox name.
Sandbox is the name or ID of the sandbox to attach. Leave it out to open a window for the person calling, to use from the live view.
ShareLocalhost shares the sandbox's localhost with the browser, so pages can open the servers it runs, such as dev servers, at the response's localhost_alias. It reaches every port of the sandbox, including servers bound only to its localhost. Off by default. Not available for a window opened with no sandbox, or when the sandbox is itself a browser.
Unrestricted gives the window's CDP clients (its sandbox, or anyone using its api_cdp_url) the whole browser, with nothing filtered: every window and tab including people's, every site's cookies, and commands that close or crash the browser. Taking over its window does not pause them.
Width and Height size the window's page in CSS pixels; set both or neither. Without them the window opens at 1280x800.
400 <= x <= 3840Response
Created
APICDPURL is the same Chrome DevTools endpoint through the LangSmith API, for clients outside any sandbox. It takes any API credential: headers as for any API call (X-Api-Key, or Authorization: Bearer with an OAuth access token, plus X-Tenant-Id where needed), or, for clients that take only a URL, api_key, token and tenant_id query parameters.
CDPURL is the Chrome DevTools endpoint the attached sandbox connects to, for example with Playwright's connect_over_cdp. It works only from inside that sandbox.
Clients are the sandboxes currently connected to this window, with "api" for each client connected through api_cdp_url. An unrestricted window's connections are not listed.
Controller is "agent" while the attached sandbox drives the window and "user" while a person has taken it over.
agent, user LocalhostAlias is the sandbox's localhost as the browser sees it: open http://<localhost_alias>: in a window to reach a server listening on that port in the sandbox, whether bound to localhost or to all interfaces (any port but 80 and 443). While this is the only sandbox sharing its localhost, http://localhost: works too. Pages on other sites can navigate to a plain-HTTP server there but cannot fetch from it. Set only for windows attached with share_localhost.
Reason is why the agent asked a person to take over, when it did.
Sandbox is the attached sandbox; empty for a window a person opened.
Unrestricted windows give their sandbox the whole browser over CDP, with nothing filtered: every window and tab, every site's cookies, and commands that close or crash the browser. Taking over such a window does not pause its sandbox, and the LSBrowserControl domain is not available.
ViewURL and ActURL open the window on the sandbox service domain with no LangSmith login, for an agent to send to a person: ViewURL to watch it, ActURL also to use it while its controller is "user". Anyone holding a link can open the window until LinksExpireAt. Each response mints new ones; they are returned only to those who may use the browser.
Width and Height are the window's page size in CSS pixels, when it was given one; a window without one keeps Chrome's default of 1280x800.