Cloud browsers

A cloud browser is a Chrome browser hosted by our browser provider, not on anyone's machine. An agent starts one with browser_launch and drives it with the same browser_* tools as a paired browser, so it works in a routine that runs with nobody at the keyboard. A cloud browser starts from your personal browser, from a profile — a named browser that keeps its cookies and sign-ins between runs — or blank when asked for one.

Your personal browser

Each person has one personal browser, listed first under My profiles as My browser. It is where an agent acting for you starts when no profile is chosen, so a site you signed in to there stays signed in for the next conversation or run. It is created the first time it is needed — a launch with no profile chosen, or Prepare on its row.

• It keeps its cookies and storage between browsers; open tabs may not survive a browser closing.
• It never expires. To start over, its menu offers Reset, which asks first, closes its open browsers and erases everything it holds; it keeps its id, and the next browser starts signed out of every site.
• Prepare opens the same preparation window as on a profile, to sign in yourself.
• It is always private: it cannot be renamed, shared or deleted, and only your agents use it. On a shared agent or routine, it is the browser of the person the run acts for.

When a member leaves the workspace, their personal browser is erased and deleted.

Profiles

Profiles live under Settings → Execution → Browsers, in two lists: My profiles and Workspace. Each row shows the profile's name, when it was last prepared ("prepared 2 days ago", or "never prepared"), its visibility, its owner, the routines and agents that use it, and Prepare for its owner. Its menu renames it, shares it or makes it private, and deletes it. The section is listed only on an instance that offers cloud browsers, and only to someone who may create a profile (browser-profiles:create, which member holds).

A profile is private by default: only its owner sees it and only the owner's agents use it. Sharing it with the workspace lets every member's agents act on the signed-in sites in the owner's name, so it asks first: "Members will be able to have their agents act on the sites signed in to in this profile, in your name. They will see neither your passwords nor your cookies." Nobody — members, agents, Standards — ever sees a password or a cookie: the agent drives the browser, it does not read its storage.

Only the owner renames, shares, prepares or deletes a profile. Deleting it closes its open browsers and removes it from every agent and routine that was granted it.

Preparing a profile

New profile asks for a name and a visibility, then Create and prepare opens the preparation window: a large live view of the profile's browser that you drive yourself. Sign in to the sites the agent will need, then click Done: the browser closes and the profile is saved with its sign-ins. Nothing is typed for you and no password is stored, by us or by the browser provider.

Closing the window without Done loses nothing: the browser closes after 15 minutes of inactivity and the profile is saved then. Prepare on an existing profile opens the same window, to sign in again when a site has signed you out.

A profile has one writer at a time, and preparing it takes that place. An earlier preparation, or the browser of a conversation, is closed first — the profile is saved as it was — and the preparation opens; the agent gets a fresh browser on its next browser_launch. The browser of a routine run is closed only once you confirm: Prepare first answers 409 with BROWSER_PROFILE_LOCKED and details.holder: "run", and the window offers Close and prepare, which asks again with { "takeOver": true } — the run loses the page it was on.

Using one in a conversation or a routine

An agent granted a cloud browser has browser_launch. It takes profileId: a profile's id, or null for a blank browser. Left out, it opens the only granted profile if there is exactly one, else — when a blank browser is granted — the personal browser of the person the run acts for, else it answers with the names of the profiles to choose from. The result names the browser (deviceId) and the profile; it never carries a link to the browser.

Once launched, the browser_* tools drive it. The cloud browser sits next to the person's paired browsers in the agent's <devices> list as "Cloud browser · <profile>"; deviceId is needed only when the agent has more than one browser to choose from. One browser serves a whole conversation, sub-agents included: a second browser_launch returns the one already open. The browser belongs to that conversation or run: a command from any other one naming its deviceId answers DEVICE_NOT_FOUND. A cloud browser is never listed under Settings → Account → Devices.

• A conversation keeps its browser between turns. It closes after 15 minutes without a command, or when the conversation is archived; the agent launches it again if it needs it later.
• A run closes its browser when the run ends, whether it completes, fails or is cancelled.

A browser asleep between two commands wakes on the next one; the first command after a pause takes a little longer.

Watching

While a cloud browser is open, its tool card shows a live view, and a strip above the message box names it ("Cloud browser · <profile>") with View to open it large. The live view opens read-only: anyone who may see the conversation or the run watches it, and the page they are shown takes no clicks (the URL itself is the limit, see below). Only the preparation window is interactive, and only for the profile's owner. After the browser closes, the card reads Closed and keeps the agent's screenshots.

GET /cloud-browsers/:sessionId/live returns { url, mode }: mode is read for an agent's browser and interact for a preparation. Someone who may not see the conversation or the run gets 404, and so does a browser that has closed (CLOUD_BROWSER_CLOSED).

Sign-in pages

An agent never types a username, a password or a one-time code. When a page asks it to sign in, it calls request_setup with a browser_login item — the profile, the site and why — and stops. The card it leaves shows Reconnect <profile> to the profile's owner, which opens the preparation window, and Ask <owner> to anyone else, which mentions the owner in the conversation. The card closes on its own once the profile has been prepared again.

A routine run may ask for this too, unlike any other request_setup item: the card appears in the run and the run ends instead of waiting. The owner reconnects, and the next run starts signed in.

Granting it

Cloud browsers are granted in toolGroups like any other tool (see Tools and connectors):

A routine may hold both, unlike a paired browser. A shared (workspace) agent or routine holds only shared profiles (AGENT_TOOL_GROUP_NOT_CONTAINED), and a profile cannot be made private while a shared agent or routine still holds it — the refusal names them. Granting either to something that runs with nobody present needs agents:manage. Neither is part of the grants a new agent starts with. The general chat has every cloud browser its person may use: a blank one and every profile they see.

At run time, the person the run acts for must still see the profile; a profile that went private, or was deleted, gives no tool. Making a profile private also closes, at once, the browsers other members' agents have open on it.

What is kept where

The browser and the profile — its cookies, its local storage — run and are stored at our browser provider. Standards keeps the profile's name, visibility, owner and dates, and for each browser it starts, when it ran and for how long. The provider gives no data-residency guarantee, even for a browser started in an EU region: do not prepare a profile on a site whose data must stay in a given region.

Limits

• One writer per profile. The first browser on a profile saves what changes in it (new cookies, refreshed sign-ins). A second browser started on the same profile meanwhile runs normally but read-only: its changes are not saved. A site that renews its session on every visit may then ask for a reconnect sooner. Preparing a profile takes over its writer: a conversation's browser is closed, a routine run's only after you confirm.
• 15 minutes without a command closes a conversation's browser; a preparation closes after 15 minutes of inactivity.
• 24 hours is the longest any cloud browser stays open.
• 15 seconds: a browser that has not connected within that time after its start fails with CLOUD_BROWSER_EXTENSION_TIMEOUT and is closed.
• A conversation's browser closed by the 15-minute timeout may leave its (already revoked, unusable) connection token in the profile's storage.

API

visibility: "workspace" needs confirmShared: true, on create and on update; without it the request answers 400 with SCHEMA_VALIDATION_FAILED. A name another profile of the workspace already uses answers 409 with SCHEMA_DUPLICATE. A profile you cannot see answers 404; one you see but do not own answers 403 on the owner routes. Renaming, sharing or deleting your personal browser is refused. On an instance without cloud browsers, every route answers 503 with CONFIGURATION_REQUIRED, and no agent is offered browser_launch.

Errors

Inside a conversation or a run, an agent meets these as a failed tool call rather than an HTTP answer; CLOUD_BROWSER_CLOSED tells it to call browser_launch again. See Errors for the shared codes.

Next steps

• Browser devices — the browser_* tools, their limits and the control lease.
• Agents and routines — granting tools and whose access a run uses.
• Roles and permissions — the browser-profiles capability.
• Book a demo