Browser Service

The browser service is a standalone Playwright-based HTTP microservice that provides browser automation capabilities to WASM plugins. It runs on localhost:9515 and enforces strict domain and action restrictions.

Architecture

Runtime — Playwright (Chromium) running in headless mode
Transport — HTTP on 127.0.0.1:9515 (localhost only, not exposed to network)
Session Pooling — up to 5 concurrent browser sessions with 5-minute idle timeout
Max Response Size — 1 MB (1,048,576 bytes)
Default Timeout — 30 seconds per action

Supported Actions

The service supports 8 browser actions:

Action	Parameters	Description
`navigate`	`url`	Navigate to a URL
`click`	`selector`	Click an element matching the CSS selector
`type`	`selector`, `text`	Type text into an input element
`get_text`	`selector`	Extract text content from an element
`get_attribute`	`selector`, `attribute`	Read an attribute value from an element
`screenshot`	`selector` (optional)	Capture a screenshot (full page or element)
`wait_for_selector`	`selector`, `timeout` (optional)	Wait for an element to appear in the DOM
`evaluate`	`script`	Execute JavaScript in the page context

HTTP API

Health Check

GET /health json

{
  "status": "ok",
  "active_sessions": 2
}

Execute Action

POST /action — Request json

{
  "action": "navigate",
  "session_id": "plugin-abc-123",
  "url": "https://example.com",
  "timeout": 30000
}

POST /action — Response json

{
  "success": true,
  "data": "https://example.com"
}

Request Fields

Field	Type	Required	Description
`action`	string	Yes	One of the 8 supported actions
`session_id`	string	Yes	Session identifier (created on first use)
`url`	string	For navigate	Target URL
`selector`	string	For click/type/get_text/get_attribute/wait_for_selector	CSS selector
`text`	string	For type	Text to type into the element
`attribute`	string	For get_attribute	HTML attribute name
`script`	string	For evaluate	JavaScript to execute
`timeout`	number	No	Action timeout in milliseconds. Default: 30000

Response Fields

Field	Type	Description
`success`	boolean	Whether the action completed successfully
`data`	string?	Action result (text content, attribute value, base64 screenshot, etc.)
`error`	string?	Error message if the action failed

Close Session

DELETE /session/:id json

{
  "closed": true
}

Security Model

The browser service enforces multiple security layers:

Domain restrictions — plugins declare allowed domains in their manifest's browser capability. The service rejects navigation to any unlisted domain.
Action restrictions — plugins declare which actions they need. The service blocks undeclared actions.
Headless only — all browser sessions run in headless mode. No visible browser window is ever created.
Localhost only — the service binds to 127.0.0.1 and is not accessible over the network.
Never auto-approved — the browser capability always requires user approval at plugin install time.
Session isolation — each plugin gets its own browser context with separate cookies, storage, and cache.

WASM Plugin Integration

WASM plugins access the browser service through the host_browser_action host import. The AI Core proxies the request to the browser service, applying capability checks before forwarding.

Plugin Integration Flow text

WASM Plugin
  │  calls host_browser_action(request)
  ▼
AI Core (Zone 2)
  │  validates capability grants
  │  checks domain + action allowlists
  ▼
Browser Service (localhost:9515)
  │  executes Playwright action
  ▼
Response (≤1 MB)
  │  returned to plugin