Browser

Give the AI tools in your sandboxes a web browser: an MCP server, browser, with the tools of Playwright MCP: open pages, click, type, fill forms, read the page, take screenshots, run scripts and watch the network. isolance runs each browser outside the sandbox, and signs in to websites with the logins of the sandbox's user (see Logins), so an agent can work in your customer's accounts on the web without ever seeing their passwords, authenticator codes, passkeys or sign-in cookies.

Each of your users gets their own: a sandbox started for a user signs in only with that user's logins, and a sandbox started without a user uses your workspace's. Your users need no isolance account, and your app sets up their logins through the API.

This guide covers the console, the CLI and the API. It assumes you know Connectors and Sandboxes. The CLI examples assume you've set up caas (see The CLI); the API examples send an API key as $CAAS_API_KEY (see The API).

Add the Browser

Only owners add it. In the console, open Connectors, choose Add connector, and pick Browser under Pick a tool. It's added at once, and its page says "Built in: isolance runs this browser. Nothing to connect." A workspace has one Browser connector, and its ID is always browser.

caas connectors add browser

With the API, POST /v1/connectors with { "catalog": "browser" }.

To sign in to websites, also add the Logins connector and give your users their logins (see Logins). To run some sites' browsers on your own Browserbase account, add Browserbase too (see Run on your Browserbase account).

The Browser's card Which sandboxes get the browser picks the sandboxes it reaches by their labels, as any connector's Reaches does (see Reaches). A new Browser connector reaches every sandbox. Removing it closes every browser of your workspace.

In a sandbox

The AI tools in a sandbox the Browser reaches can call its MCP server, browser, at an address made for that sandbox alone, as https://browser.caas.sh/mcp/<sandbox>.<tag>. There's no key in the sandbox: isolance adds the sandbox's access to the browser to its requests on their way out, as it adds any connector's key (see What a sandbox sees).

• A user's first sandbox. isolance sets up each user's access to the browser the first time a sandbox of theirs starts with it. If that doesn't work out, that one sandbox starts without the browser, its log says "The browser couldn't be set up for this sandbox; it will be at its next start", and its next start sets it up again.

• Changes apply at the next start, as for any connector: adding the Browser, or changing which sandboxes it reaches, reaches a running sandbox when it restarts.

• Where keys can be added. A sandbox gets the browser only where isolance can add keys to its requests. With the provider on Auto, the default, isolance places it there.

The tools

The server lists every tool of the Playwright MCP version isolance pins, with Playwright MCP's names, descriptions and inputs, so its own documentation applies: navigating and tabs, snapshots and screenshots, clicks, typing and forms, dialogs and file uploads, scripts in the page (browser_evaluate, browser_run_code_unsafe), console messages, network requests and routes, cookies and storage, PDF, tracing and video, and testing. Where isolance changes how a tool behaves, its description says so.

isolance adds its own tools for logins:

A tool names a login by its ID, or by its site when the sandbox's user has one login there. Passkeys need no tool: when the site's page asks for a passkey, isolance answers it (see Passkeys).

A browser's life

• One per AI tool. Each MCP session, which is each AI tool process and each sub-agent that opens its own, has a browser of its own, opened by its first tool that needs a page; calls it sends at once share that one browser. login_list, login_status and listing tabs answer without one. A sandbox runs as many browsers as its AI tools open.

• It keeps its tabs between calls, until it ends.

• Which browser. It runs on the browser of the login for the first site it opens: isolance's own browsers, or your Browserbase account. A site without a login opens on isolance's own.

• One sign-in per site. A browser holds one login of each site and runs on one kind of browser. A tool for a login of the other kind, or for a second login of a site the browser already holds, is refused with the way there: close this browser (browser_close), then navigate to the site to open one there. Browsing the site without signing in works.

• Opening takes a few seconds. If a browser isn't ready within 25 seconds, the tool answers "The browser is still starting; try again", and the next call finds the same browser.

• It ends at browser_close (the next tool that needs a page opens a new browser, which takes longer than a call), when the AI tool exits and its session ends, when the sandbox stops or is deleted, after 20 minutes without a call on isolance's own browsers or 10 minutes on Browserbase (never while a person's live view of it can still be opened), when a login it uses is removed, and when its user, the Browser or the Logins connector is removed. A browser that ended between calls is replaced at the next one, whose answer starts "A new browser was started; earlier tabs are gone."

• It's refused like a start. No browser opens while your workspace's spend cap is reached, it's out of funds or it's suspended, as no sandbox starts then.

• When isolance's browsers are all busy, the tool says so with how long to wait: "isolance's browsers are all busy right now; try again in 5 s". Nothing waits in a queue.

Files

A tool that reads a file, such as browser_file_upload, browser_drop or browser_set_storage_state, reads it from the calling sandbox, and a tool that writes one, such as a screenshot or PDF with a filename, writes it into that sandbox. A path that isn't absolute is relative to the sandbox's working directory. A file saved with browser_storage_state shows sign-in cookies as [REDACTED].

Signing in

login_sign_in signs in the way a password manager does: it opens the site's sign-in page, checks whether it's already signed in, then tries the login's ways in order (a passkey, then a password and authenticator code, for example) until the page is signed in, and saves the sign-in. If none works, it answers with the page as it stands and what the page shows, so the AI can type the fields the site asks for with login_fill, or ask a person with login_handoff. Logins explains how each login signs in.

isolance types a value, or answers a passkey request, only into a page of the login's site that none of the AI's scripts, routes or storage changes has touched, checked at the moment it acts:

A site the AI's scripts ran on (with browser_evaluate, or a page loaded under a route), or wrote storage for, keeps no sign-in from that browser, and none at all once browser_run_code_unsafe ran: what the AI's code wrote would be saved as the user's own. Signing in there still works; login_save says why it saves nothing, and the next browser signs in again.

The other way round, once isolance has typed into a page, the AI's scripts, routes and storage writes in that browser are refused until the page is submitted, navigates or reloads. login_fill types only into a field of the page itself, named by its ref from a snapshot (not a selector, or a field inside a frame), that the site's sign-in form marks for that value: an account name or email field, a password field, or a one-time-code field. A refused step says why, so the AI can reload or open a new browser. These rules don't apply to a login that lets the AI read its password.

Ask a person

Some sites ask for something only a person can give, such as a code sent to a phone. login_handoff asks a person to finish signing in on the browser's current tab, which the person sees as the AI left it: it answers waiting at once, never holding the AI's request open, and the AI checks how it went with login_status. Its message to the person is up to 256 characters.

• Your app hears of it by reading the login (see When a sandbox asks for a person), and shows the person the live view, or sends your user a link whose page shows it.

• While the person's view is open, the AI's browser tools in that browser answer that a person is signing in, so nothing the AI does reaches what the person types; login_status and login_list still answer.

• A person signs in only in a browser none of the AI's routes, browser_run_code_unsafe or storage writes on the site has touched: otherwise the tool asks the AI to close the browser and open a new one first. A page only browser_evaluate touched is reloaded for the person, but a site the AI's script ran on keeps no sign-in from that browser, so Done saves nothing there and says why.

• The browser doesn't close for being idle while the person's view can still be opened.

• When the person chooses Done, the sign-in is saved when the site is signed in, and the AI goes on in the same browser; login_status says whether it was saved.

What the AI sees

isolance keeps what it puts into the browser from the AI. Unless a login lets the AI read its password, the AI never gets:

• a password, account name or authenticator code isolance typed, or an authenticator setup key;

• a passkey, or the answers isolance gave the site's passkey requests;

• the site's sign-in cookies that its pages' own scripts can't read (HttpOnly cookies), whether a saved sign-in brought them or the site set them.

They show as [REDACTED] wherever a tool would show them: page snapshots, script results, console messages, network requests and their headers, cookie and storage lists, and saved storage files. A script the AI runs with browser_run_code_unsafe gets them hidden too, before its code sees them.

What a page's own scripts can read, the AI's scripts in that page can read too: the cookies that aren't HttpOnly, the page's storage, and whatever the page shows. With a script in a signed-in page, the AI acts as the user there, as any script on that page could. And a screenshot shows what the page shows: a site that shows a password in clear shows it in a screenshot. So run only one user's work in that user's sandboxes, and limit what the sandboxes reach with their outbound hosts and labels.

Run on your Browserbase account

The Browserbase connector runs the browsers of the logins you set to it on your own Browserbase account, which bills you for them; isolance bills no browser time for them.

1. As an owner, add Browserbase from Add connector, or caas connectors add browserbase.

2. On its page, paste an API key from your Browserbase dashboard into the Key field of the Workspace account card, and choose Connect. With the CLI: caas connectors account browserbase --api-key < browserbase-key.txt.

3. Set a login's browser to Browserbase: "browser": "browserbase" (see Logins).

What to know:

• It reaches no sandbox. Its key runs every Browserbase browser of every user and is never in a sandbox. A sandbox that calls Browserbase's own API needs an API connector of its own.

• One saved sign-in per user. All of a user's Browserbase browsers share one Browserbase profile, so two sandboxes of the same user on the same site share the sign-in at once. So a user has at most one Browserbase login per site: a second account on that site signs in on isolance's own browsers.

• Browserbase's limits apply. When your plan refuses a browser, the tool says when to try again. A Browserbase browser ends after 10 minutes without a call.

• Its live views can be embedded in your own pages (see Sign in by hand).

• Without its key, the tools for a login set to Browserbase answer "This login runs on Browserbase, which isn't connected". Removing the connector closes the browsers on it.

• A new profile when a sign-in goes. Removing a Browserbase login or its saved sign-in, replacing or removing the key, or removing the connector starts the users' next Browserbase browsers on a new profile, signed out of every site there (see Saved sign-ins).

Browser time

A browser on isolance's own browsers bills browser time, from when it opens to when it ends:

• A close ends it at once: browser_close, the AI tool exiting, the sandbox's stop, or a person's Done. A browser closed after a ten-second task bills ten seconds.

• A browser left idle bills until it idles out, 20 minutes after its last call. So have the agent close the browser when its task is done.

• A long browser bills day by day: each day's time is counted at the UTC midnight it runs past, not only when it closes.

• Checks and people's live views bill as any browser. A live view nobody finishes counts until its browser would have idled out.

• Browserbase browsers bill nothing here; Browserbase bills your account.

• Logins bill nothing.

Each user's browser time is in their usage, with their sandbox time: browserSeconds in GET /v1/users/<user>/usage (see Status and usage). See Pricing for the rate, and Billing and usage for how it draws down your balance.

Browsers aren't an API resource of their own: they show as browser time, and as live views under the logins they sign in to.

Who can do what

Limits