Open a browser
open_browserOpens a real Chromium browser on SpecStream's server and returns its session id. Drive it with the browser_ tools (browser_navigate, browser_snapshot, browser_click, browser_type, browser_take_screenshot, browser_read and the others) with that session_id, or hand its connect_url to Playwright, Puppeteer, browser-use or Stagehand. Use it for pages that need a real browser: forms, clicks, pages drawn by scripts. For the text of known pages read_pages is faster and cheaper. A page whose site opted out, whose robots.txt disallows SpecStream or that is outside allowed_domains answers blocked. The session ends at close_browser, after idle_timeout_s with no step or connection, or at timeout_s (default 300 seconds, at most 3,600). Charged $0.10 an hour by the second while it runs (at most 10¢ a session), plus $1 per 1,000 steps (0.1¢ a step). A session that fails to start is not charged.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "open_browser"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| headless | No | false runs the browser with a screen, for sites that act differently without one. It uses more memory. | |
| metadata | No | Your own labels for the session, returned as sent. | |
| viewport | No | The browser window's size in pixels. | |
| timeout_s | No | The most seconds the session runs. It ends then, connected or not. | |
| keep_alive | No | true keeps the session when the client disconnects, so a new client can connect, until idle_timeout_s passes. false ends it at the disconnect. | |
| block_media | No | true skips images, video, audio and fonts: pages load faster and the session reads fewer bytes. | |
| idle_timeout_s | No | The session ends after this many seconds with no client connected and no action. With keep_alive false, a disconnect ends it at once. | |
| allowed_domains | No | Hosts the browser may open, such as example.com or *.example.com. Empty allows every public host. A page outside them is refused with blocked. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| bytes | No | ||
| price | No | ||
| limits | No | ||
| status | No | ||
| actions | No | ||
| seconds | No | ||
| ended_at | No | ||
| headless | No | ||
| live_url | No | ||
| metadata | No | ||
| viewport | No | ||
| timeout_s | No | ||
| created_at | No | ||
| expires_at | No | ||
| keep_alive | No | ||
| started_at | No | ||
| actions_url | No | ||
| block_media | No | ||
| charged_usd | No | ||
| connect_url | No | ||
| ended_reason | No | ||
| idle_timeout_s | No | ||
| allowed_domains | No |