Live view and profiles

Эта страница ещё не переведена на язык «русский»: вот она на английском.

Not open yet. Browser is not open to accounts yet. This page says how it works as it is built, ahead of its opening, and may change before then.

Watching a session live

A session’s live_url is where its page is watched and driven, live, in any browser: a signed address, as its CDP address is, and a credential as that one is.

• A headless session (chromium-headless): a page that draws the browser’s most recent tab as it changes, with a list to switch tabs; the viewer’s mouse, wheel, keyboard and pastes reach the page.
• A headful session (chromium): its screen, through noVNC, mouse and keyboard and all.
• A Lightpanda session (lightpanda) has none: it has no layout engine and nothing to stream. Its live_url is null, and GET /v1/browsers/{id}/live is refused (400 kind_unsupported). It keeps no profile either: a create with one, and a save, are refused the same way. See Lightpanda.

GET /v1/browsers/{id}/live?interactive=false gives an address where the page is only looked at: an address of its own, whose signature opens nothing else, where nothing but what draws the screen reaches the browser. Keys, clicks, pastes, resizes, scripts and navigation do not. Put it in a page of your own for people to watch an agent at work. Without interactive=false the call gives live_url.

GET /v1/browsers/agent-42/live?interactive=false

{"object": "browser_live", "id": "sbx-…", "url": "https://6081-…/live?interactive=false", "interactive": false}

A viewer connected keeps the session awake, as a CDP client does. Both addresses are a new pair after rotate-url, which ends the viewers’ connections with the rest. Reading either takes the key’s url scope: live_url is null without it. Where the session’s machine gives no address now, the call answers 503 unavailable, retryable.

Profiles

A profile is what says who a browser is to the sites it visited: its cookies, Local Storage, IndexedDB, Session Storage and preferences, without its cache. Log in once in a session, save its profile, and every session made with the profile is logged in.

• Make a session with one: profile: {"name": "acme-login"} in the create. Its newest version (or the one version names) is loaded before the session is answered: the browser is started again on it. With save: true, the session saves it again when it is deleted (unless the delete says ?save_profile=false); a profile that has no version yet is made by that save. A profile with no version that the session does not save is refused (404 profile_not_found).
• Save one now: POST /v1/browsers/{id}/profile with {"name"}, or with nothing for the profile the session was made with. Its browser is stopped as it is closed, so that it writes what it holds, packed, and started again: a client connected is disconnected, and connects again. The answer is the profile, the new version first among its versions.
• One save of a profile at a time: another, from any session, is refused 409 profile_busy (retryable). Two sessions may load one profile; each save is a version of its own, and the newest is the profile’s.
• GET /v1/browsers/profiles lists the project’s profiles by name, GET /v1/browsers/profiles/{name} gives one with every version (its bytes, sha256, when it was saved and by which session), and DELETE /v1/browsers/profiles/{name} deletes one: gone at once, and its archives deleted 30 days later. A profile saved again under the name is a new one. A profile’s name is 1 to 63 lower-case letters, digits and hyphens, a letter or a digit first and last; no session is named profiles.

Where a profile could not be loaded or saved (the object store not reached, the browser not come back), the call is 503 profile_transfer_failed, retryable: a session made for a profile it could not load is deleted again, and one whose save failed is left as it was.

Where profiles are kept. In a bucket the platform keeps for the project behind its own object gateway, glac-profiles-<project>, made with the first save and not billed on its own. The platform reads and writes it with a key of its own for the project, which reaches that bucket alone. A session never holds a key: for each load or save it is given the address of one object, good for two minutes. A control plane with no object gateway keeps no profiles (400 objects_not_served). A profile’s cookies are sealed with a key that is the same in every session, so another session reads them: treat a profile as the login it holds.

The command line has glac browsers live, save-profile, profiles ls and profiles rm, and create --profile; the Python and TypeScript SDKs have the same. The Go, Rust and Java SDKs and the MCP server have neither live view nor profiles yet: the MCP server’s browser_open gives live_url.