Agent Browser

Use this skill when browser state matters and the workflow needs the user's logged-in, visible browser.

Prime And Upstream Sources

Read the local deployment manual and load the installed CLI's version-matched core skill before acting:

Get-Content docs\browserops-agent-browser-manual.md
agent-browser skills get core --full

Use the official sources when commands, CDP behavior, sessions, bundled skills, or known bugs may have changed:

• https://agent-browser.dev/
• https://agent-browser.dev/commands
• https://agent-browser.dev/skills
• https://agent-browser.dev/cdp-mode
• https://github.com/vercel-labs/agent-browser
• https://github.com/vercel-labs/agent-browser/releases

Check version drift without changing the machine:

agent-browser --version
npm view agent-browser version
agent-browser skills list --json

Review intervening releases and get operator authority before running npm install -g agent-browser@latest. Do not run agent-browser install for this attach-only deployment; it downloads an Agent Browser-managed Chrome. After an authorized update, reload core, run BrowserOps tests, and prove one read-only --cdp 18222 attachment.

Contract

• Use one persistent visible browser per deployment.
• Attach through CDP. Do not launch a separate headless or test browser.
• Put --cdp 18222 on every direct local command. Never use bare open, auto-connect, or upstream example port 9222 on this machine.
• Use current snapshot refs or allowlisted selectors and real Agent Browser click/fill commands. Never substitute eval, HTMLElement.click(), injected JavaScript, blind coordinates, or address-bar typing.
• Re-snapshot after navigation or DOM mutation and verify the resulting URL, selected state, or visible confirmation.
• Do not copy cookies, profiles, raw tokens, tabs, .env files, or service credentials between machines.
• Do not scrape or print secrets from browser storage.
• Do not perform external writes such as posts, DMs, connection requests, purchases, or profile edits unless the user explicitly asks for that exact action.

First Check

From the Homie chat surface, prefer deterministic router checks before model-driven browser work:

/browser status
/browser tabs

Use /linkedin_profile status only for the LinkedIn-specific wrapper. It uses the same browser helper contract.

Local Windows Backend

Expected local backend:

• real Chrome
• visible window
• CDP on port 18222
• agent-browser --cdp 18222 ...
• sole launcher/keeper SecondBrain-LinkedInChrome
• deployment-local profile %USERPROFILE%\.codex\browser-profiles\chrome-cdp-9222 (9222 is a legacy directory suffix, not the active port)

Useful direct commands when operating from a terminal:

agent-browser --cdp 18222 snapshot -i -c
agent-browser --cdp 18222 --session operator-desk tab --json

If CDP is unreachable, fail closed and diagnose the existing keeper. Do not launch or restart Chrome from Agent Browser, add another keeper, warm the Agent Browser daemon from the keeper, or fall back to Playwright/headless just to make a test pass. Upwork uses the named attach-only session operator-desk inside this same Chrome process/profile.

If raw http://127.0.0.1:18222/json/version health succeeds but Agent Browser attach hangs or fails with Failed to read ... (os error 10060), stop the worker. Foreground and reload the exact existing tab, retry one read-only attachment, then keep the workflow paused if it still fails. Do not spawn a fresh/duplicate browser, a headless fallback, or a second keeper as recovery.

Chrome-150 Origin exception (proven 2026-07-19). That exact "raw CDP healthy but every Agent Browser command 10060s" signature after a Chrome update is Chrome 150+ returning 403 on any CDP WebSocket handshake carrying an Origin header — Agent Browser sends one. It is NOT a port, daemon, IPv6, or version problem (downgrade, portproxy, and fresh-profile are all proven dead ends). The fix is the Chrome launch flag --remote-allow-origins=*, which the sole keeper ensure-linkedin-chrome.ps1 now includes. Sanctioned recovery here is a controlled keeper relaunch (not an ad-hoc Chrome kill): kill only the CDP-profile Chrome by --user-data-dir, clear stale ~/.agent-browser/default.*, re-run the keeper (or reboot — logon trigger), verify with agent-browser --cdp 18222 tab list, then resume the desk via resume_supervised_preview_after_repair. Isolate the cause in one test: a raw WebSocket to the webSocketDebuggerUrl returns Browser.getVersion OK with the Origin header suppressed and 403 with it present. Full writeup: docs/manual/features/operator-desk.md → Browser Recovery, and memory agent-browser-broken-cdp-read-timeout.

Linux / VPS Backend

The production reference uses:

• qm-chromium.service for persistent Chromium
• xvfb-99.service for the visible virtual display
• /tmp/ab.sh as the safe wrapper
• hotbox-cdp-stream.service for viewer streaming

Use the wrapper on VPS:

/tmp/ab.sh snapshot -i -c
/tmp/ab.sh open https://www.linkedin.com/

Treat VPS browser state as deployment-local. Do not copy it into the repo or local machine.

Viewer

Hotbox is the proven VPS reference for watching the remote browser. The framework viewer target is Mission Control or Hub, but local Hotbox work is not part of the first slice.

Output Discipline

When reporting browser state:

• say whether CDP is reachable
• say whether the visible/non-headless guard passed, failed, or was unknown
• redact URL query strings and fragments in tab lists
• keep command output concise
• surface blockers plainly instead of claiming browser readiness