sandboxes

Set who controls a browser window (beta)

Changed on

Beta: give the window to a person ("user") or back to the attached sandbox ("agent"). It takes effect at once and does not wait for anyone. While a person has control, the attached sandbox's commands that read or act on the page fail with a "human has control" error, and it receives no page content. The window's current controller is in the browser's attachments.

post/api/v2/sandboxes/browsers/{name}/attachments/{attachment_id}/controller

Request

  • Base URL
    https://api.smith.langchain.com
  • URL
    https://api.smith.langchain.com/api/v2/sandboxes/browsers/{name}/attachments/{attachment_id}/controller
  • Auth
    • API key in header X-API-Key
    • or API key in header X-Tenant-Id
    • or HTTP bearer

Path parameters

namestring required

Browser name or ID

attachment_idstring required

Attachment ID

Request body

controller'agent' | 'user'

Controller is "user" to give the window to a person, or "agent" to give it back to the attached sandbox.

Response

OK

act_urlstring
api_cdp_urlstring

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.

cdp_urlstring

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.

clientsstring[]

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'agent' | 'user'

Controller is "agent" while the attached sandbox drives the window and "user" while a person has taken it over.

created_atstring
heightinteger
idstring
links_expire_atstring date-time
localhost_aliasstring

LocalhostAlias is the sandbox's localhost as the browser sees it: open http://<localhost_alias>:<port> 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:<port> 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.

namestring
reasonstring

Reason is why the agent asked a person to take over, when it did.

sandboxstring

Sandbox is the attached sandbox; empty for a window a person opened.

unrestrictedboolean

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.

view_urlstring

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.

widthinteger

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.

Changes