Repository navigation
Browser Control
Cascade has several browser capabilities with different security properties.
| Mode | Environment | What the agent controls |
|---|---|---|
| Built-in desktop browser | Electron desktop app | Potentially the current user-signed-in tab, with explicit permission |
| Remote cloud browser | Hosted/self-hosted web | A server-provisioned browser session over CDP or Steel |
| Headless browser tool | Selected local/tool runtimes | Separate Playwright automation when enabled |
The live browser_control experience exists on desktop and web, not the CLI. Do not mistake the CLI's optional browser tool for that feature.
Browser control is coordinated through a lease. If a user takes control, the agent must not race them with simultaneous clicks/typing; the user can later hand control back. Observing a browser pixel stream is not equivalent to granting input control. Browser streaming should be tied to authenticated, per-run connections rather than assuming any provider iframe may be embedded.
-
Desktop:
agentBrowserControlis distinct fromtools.browserEnabledand defaults off. Agent use of your active signed-in page requires authorization. -
Hosted web: the operator must configure a valid remote-browser/CDP/Steel endpoint using
REMOTE_BROWSER_*environment settings. An unconfigured deployment does not have a remote browser. - Remote authentication: a hosted browser does not inherit desktop cookies/session state. Do not assume an authenticated session from the user's machine is available.
Retrieved pages, scripts, embedded frames and their instructions are untrusted input, even if the page claims to be from an administrator. The browser bridge should respect per-run authorization, network restrictions, session quotas, stop/idle behavior, and lease ownership. User-provided prompts do not authorize attacks on external sites.
Source code: src/browser/lease.ts, src/browser/remote/controller.ts, cloud/server/src/remote-browser.ts, app/electron/browser.ts.