/horizon-browser

name: horizon-browser
description: Control, inspect, or audit Horizon browser panels through public browser_* MCP tools.

Horizon browser control

Native VNC Device panels, simulators, and isolated desktop tests use the `horizon-device` skill. The workflow below applies to browser pages.

Use the `browser_*` MCP tools as the only agent-facing browser contract. Do not inspect Horizon runtime files, connect to raw CDP/BiDi/WebDriver endpoints, or invoke a browser-control CLI. If the MCP tools are unavailable, report that the Horizon browser MCP server is not connected.

Start with `browser_list` when the panel id is unknown. If it returns no panels, call `browser_create`; this opens a panel in the current agent's Horizon workspace and returns its ready panel id once the backend is ready and, when you passed a `url`, once that page committed (`navigation: committed`). A `navigation: pending` result means the panel is controllable but the first page had not committed within the bounded startup wait, so use `browser_wait` or `browser_panel` before reading it; `navigation: failed` means that page failed to load (`navigation_error` says why) and you must navigate again or fix the URL; `navigation: superseded` means the user navigated the panel first, so read `panel.url` before acting. If `browser_list` returns a usable panel, reuse that panel for iframe, popup, dialog, and consent interactions. Never create or reveal a helper panel as a workaround. You may hold one panel per browser engine: to run the same check in another engine, call `browser_create` with an explicit `backend` (`chromium`, `firefox` or `safari`) beside your open panel. Only when the user explicitly requests another independent browser session may you call `browser_create` with `allow_additional: true`; a second panel of the same engine, a create without `backend` while you own a panel, and a remote `target` while you own a panel need it. A create that is still pending counts as a panel of its engine. Omit `backend` to use Horizon's configured browser, or select `chromium`, `firefox`, or `safari` when the platform supports it. Read `automation_disclosure` on `browser_list` and `browser_panel`. In the UI, hover the local backend picker or the remote identity header to read the same status. `common_signals_minimized` means the native `navigator.webdriver` getter is still native. On Firefox that result needs `firefox_system_access: true` and geckodriver 0.37 or newer. The option passes geckodriver `--allow-system-access`. Mozilla documents that flag as full system access for any local client that can reach the driver port. Leave it false unless that privilege is acceptable. `preload_fallback` means Firefox installed a script getter that returns false. Sign-in pages can reject that getter. The default minimized Firefox session uses that fallback. Chromium does not install it. A remote Firefox or Chromium session reports `unsupported_by_backend` for minimization. Remote Firefox does not clear the native flag or install the preload. Remote Chromium does not receive the local automation flag. `unreported` means an older manifest omitted the field. That is not an established result. To run at a configured remote target instead of a local browser, pass `target` with its name and omit `backend`; Horizon resolves the provider and credentials from its configuration, and a refusal carries a typed code and at most the target, provider or credential reference name, never a credential value. Such a panel reports `remote_target`, `remote_device` (the model, OS version and hardware evidence the provider itself reported, verified against the target before the panel became ready), classic WebDriver and no network capture. A target that requires a physical device is refused as `remote_device_rejected` unless that evidence confirms it, after Horizon attempts to release the session; a `remote_allocation_unknown` refusal means a device may still be held, so check with the user before creating again; `remote_authentication_failed`, `remote_not_entitled` and `remote_device_unavailable` say which of the credential, the account's automation access or the device request the provider refused, with nothing held. Cite `remote_device`, not the target name, as real-device evidence. Set `visible: false` for background automation; use `browser_visibility` to show or hide the live panel later without stopping its session, capture, ownership, or MCP control. Call `browser_close` on a panel you own when the user is done with it or a remote device session must be released now; it stops the session, releases any remote allocation, and the panel leaves `browser_list`. Read anything you still need from `browser_audit` before closing: it answers only for a live panel. An optional bare-host `url` defaults to HTTPS while explicit HTTP remains available. Use `browser_panel` for a known panel. Discovery and control are scoped to the workspace that contains your agent panel: `browser_list` never shows panels from other workspaces, every other tool rejects their ids, and a panel's `visible` field is host presentation state, not proof that the panel is in your workspace. If nothing usable is listed, create a panel rather than guessing an id. On a cloud worker, your injected actor must match a registered workspace session. For a request addressed to the current worker, an actor outside that workspace receives `panel_outside_workspace` before a browser starts. Use the registered session identity; do not retry an unregistered actor. Before interacting, call `browser_snapshot` or `browser_query` and prefer its short-lived `ref` in `browser_act`. Remote iOS clicks and field entry use synchronous target checks before trusted native input. Verify the visible result after each action. `browser_evaluate` works on a driver that omits its script timeout, and it awaits a returned promise: a rejection is a `javascript_error` and an unsettled promise is an `evaluation_timeout`. Na