--- canonical: "https://agi-labo.com/en/tools/cockpit/docs/browser" title: cockpit browser description: Open web pages in a task's in-app browser so people and agents can safely inspect, operate, and verify the same tabs. section: cockpit browser order: 14 pageType: how-to lastVerifiedVersion: 4.61.0 lastVerifiedAt: "2026-08-27" draft: false surfaces: - desktop - cli operatingSystems: - windows - macos - linux plans: - guest - member --- `cockpit browser` is the official surface for opening real web pages in a task-scoped in-app browser and inspecting their DOM, appearance, and outcomes. It is driveable, not just viewable: it can click, type, select, upload, paste, press keys, and scroll. [HTML Surface](/en/tools/cockpit/docs/results-and-tools#distinguish-html-mode-from-html-surface) displays reports produced by an agent. Use the in-app browser for external navigation, sign-in, form operation, and Web UI verification. ## Share one page between person and agent Each tab has one canonical page instance shared by the person viewing the side panel and the agent operating it. Switching tasks, tabs, or panels detaches the page from the window without reloading it, preserving unsent forms, scroll position, SPA state, and popup or OAuth context. Browser sessions and navigation history survive task completion, resume, and app restart. Form values and scroll position are restored after restart on a best-effort basis, and saved state is encrypted when the operating-system credential store is available. A parked tab can receive input while hidden without showing a separate window or switching macOS Spaces. The same page is visible when the panel is shown again. ## Open a page ```bash cockpit browser open https://example.com --json cockpit browser tabs --summary --json cockpit browser show --json ``` Inside a Cockpit task, omitting a session or task ID uses the current task. `open` reuses its most recent session and selected tab. Add `--new-tab` when the current page has unsent state to preserve. ```bash cockpit browser open https://example.com/form --new-tab --json cockpit browser goto https://example.com/next --json cockpit browser reload --json ``` `tabs --summary` reports selection, a body-text preview, loading time, renderer responsiveness, and the latest navigation error. Popups and page-side `window.close()` are reflected in Cockpit's tabs. ## Choose snapshot or screenshot ```bash cockpit browser snapshot --json cockpit browser snapshot --wait-for-text "Ready" --timeout 10000 --json cockpit browser screenshot --full-page --output ./page.png --json ``` `snapshot` returns rendered text, links, buttons, inputs, roles, accessible names, and selectors. Use it to identify controls and verify machine-readable state. Use `screenshot` for visual layout, imagery, canvas content, or a result a person needs to see. Locators traverse open shadow roots. A normal CSS selector works across them, and `host >>> inner` pins an explicit shadow boundary. Closed shadow roots are inaccessible from the page; use screenshot coordinates when necessary. ## Operate by meaningful name ```bash cockpit browser click --role button --name "Submit" --json cockpit browser type --role textbox --name "Email" --text "name@example.com" --json cockpit browser select --selector "#plan" --option-text "Team" --json cockpit browser scroll-into-view --role button --name "Continue" --json ``` Prefer `--role` and `--name`, then a stable CSS selector, then viewport coordinates. Accessible names are computed from `aria-labelledby`, `aria-label`, labels, alt text, values, content, and titles. Matching is case-insensitive and exact by default; use `--name-match prefix|contains` explicitly when needed. No match, several matches, and all-hidden matches fail with `browser_target_not_found`, `browser_target_ambiguous`, and `browser_target_not_visible`, respectively, and return candidate details. Cockpit never silently operates the first ambiguous candidate. ## Verify operations with postconditions ```bash cockpit browser click --role button --name "Save" \ --wait-for-text "Saved" --timeout 10000 --json cockpit browser click --selector "#checkout" \ --wait-for-url "*/complete" \ --wait-for-response-url "*/api/orders*" \ --wait-for-response-status "200-299" --json ``` `changed` and `changeSignals` report observed changes to the URL, DOM, form values, and related state. `changed: false` is not proof of success. Add a postcondition that matches the requested outcome: URL, visible text, selector state, a new tab, or a network status. If `eventDispatched: false` but `inputDelivered: true`, the operation may have taken effect even though event propagation was stopped. Avoid an immediate retry that could submit twice; inspect the current page with a snapshot first. Network verification returns only method, status, and a URL with query values and the hash masked. It never returns request or response bodies, headers, or payloads. ## Type, paste, upload, and dismiss dialogs ```bash cockpit browser paste --selector "[contenteditable]" --text "Long content" --json cockpit browser upload --role button --name "Attach a file" --path ./build.zip --json cockpit browser press --selector "#search" --key Enter --json cockpit browser dismiss-dialog --button-text "OK" --json ``` `type` replaces the target value and verifies the final value. `paste` sends a real clipboard paste event, verifies that the requested text appeared, and restores the previous clipboard representations. `upload` sets a file input or a file input inside a dropzone without opening the operating-system picker. `dismiss-dialog` handles a pending JavaScript dialog first, then a visible HTML dialog. Use `--reject` for the negative action. Postconditions do not expand authority: submitting, purchasing, publishing, deleting, and other external state changes remain subject to user approval. ## Recover loading and renderer failures Use `health` from `tabs` to distinguish these cases: | Value | Meaning | | --- | --- | | `loadingDurationMs` | How long Chromium has reported the page as loading | | `rendererResponsive` | Whether the renderer answered a short JavaScript ping | | `lastNavigationError` | The latest main-frame load failure | Wait when the site is merely slow, and inspect the URL or connection after a navigation error. If the renderer is stuck, recreate only that renderer while keeping the same tab ID, URL, session, and Browser Identity. ```bash cockpit browser tab recreate --json ``` ## Sign-in and safety boundaries See [Browser Identity](/en/tools/cockpit/docs/browser-identities) for cookie and localStorage isolation, task and Autorun assignment, Chrome session import, clearing, and removal. Passkeys can use Touch ID in signed macOS builds and Windows Hello on Windows. Linux has no platform authenticator, so use a roaming security key or password. If no prompt appears, inspect the reason with `cockpit browser diagnostics`. Only HTTP and HTTPS links can normally leave the in-app browser. A `mailto` link opens only after the person's own interaction and explicit confirmation; other schemes are rejected. Agent automation does not count as that person interaction. ## Related pages - [Browser Identity](/en/tools/cockpit/docs/browser-identities) - [`cockpit browser` reference](/en/tools/cockpit/docs/cockpit-cli/reference/browser) - [Results and tools](/en/tools/cockpit/docs/results-and-tools) - [Security and data](/en/tools/cockpit/docs/security-and-data)