Agents drive real browsers on the target computer. On enrolled machines the system launches its own managed browser instances; on your own machine, the browser extension works directly with the browser you already use. This page covers the managed sessions: how tabs are managed, how sessions are isolated, and how they are shared when several tasks use one computer.
Sessions and instances
Every browser session is a fully independent browser instance — its own process, its own data directory. Nothing is shared between sessions.
Most browser commands take an optional sessionId. With a single session running, commands target it automatically. With several running, the call must name its session — omitting the id is an error that lists the sessions currently alive, rather than a guess.
Passing newInstance: true when opening a tab starts a brand-new independent instance instead of reusing an existing one. A tabId can never reference a tab in an instance that was just created by that same call.
Tab management
Four tab operations are available, each scoped to a session:
| Method | Parameters | Returns | Behavior |
|---|---|---|---|
tabs.list |
sessionId? |
session id, channel, tabs | Lists the session's tabs with tabId, URL, title, and which one is active. |
tabs.open |
url?, newInstance?, sessionId? |
session id, tab id, channel | Opens a new tab. The URL must be an http(s) URL; about:blank is also accepted as the canonical empty tab. Navigation only accepts http(s). |
tabs.activate |
tabId, sessionId? |
ok, session id, tab id, channel | Brings an existing tab to the front (creates the target if needed). |
tabs.close |
tabId, sessionId? |
ok, session id, tab id, channel | Closes the tab. |
Snapshots and navigation accept a tabId too; when omitted they use the session's currently active tab.
Handle rules
- A
sessionIdidentifies one session. When omitted, the current session is used, or a fresh one starts if none exists. - A
tabIdis only valid within its own session. A tab handle from another session (or another computer) does not resolve. browser.closeshuts down one session and deletes its data directory. It never touches your own browser.- All tab operations work on system-managed sessions only. On a machine where the only browser is your own (the extension), tab management fails explicitly rather than acting on your browser.
Session lifecycle
- Idle cleanup — a session idle for more than 10 minutes (and any session whose process has died) is cleaned up.
- Explicit close —
browser.closetears a session down immediately and removes its data directory. - No orphans — on service restart, leftover browser processes from previous runs are swept. Only processes the system itself started are touched, never anything else.
Browsers run headless where there is no GUI session (an enrolled server, for example), so browser methods stay usable without a desktop. If the computer doesn't declare a browser capability at all, the operation is rejected with an explicit capability error — never silently skipped.
Cloud agent scheduling
When several agent tasks share one computer, browser sessions are allocated by these rules:
- Per-task binding — each task gets its own session, never shared.
- Concurrency cap — each computer runs at most 4 concurrent browser sessions. At the cap, arriving tasks wait in queue (a 30-second budget by default, then an explicit timeout error) and never preempt a running one.
- Terminal-state reclaim — when a task completes, fails, or is cancelled, its session is reclaimed. A session that failed to close shows up in the stats, so leaks are visible instead of silent.
- Traceability — session allocation and reclaim are recorded, each naming the task and computer involved.
The extension channel
On a machine where you use your own browser, the MagicFrog browser extension provides navigation and structured DOM snapshots of pages in that browser — no separate browser instance, no debugging port. The extension does not expose tab management, and tab operations never act on your own browser.
For how tool calls reach a specific computer in the first place, see Computer ID Routing; for creating and enrolling the computers themselves, see Cloud Computers.