Browser Targets

Use this skill for tasks that need reading or interacting with websites and web apps, including public pages and signed-in services, even when the user does not mention a browser or no browser target is listed. Browser access is a built-in GSV capability: use a suitable existing browser or provision a cloud browser. The user does not need to connect their personal browser first.

Browser targets have platform browser or browser-extension. Their ids may look like browser:chrome, rearden:brave, or an instance id; use the id returned by discovery or provisioning.

Quick Start

1. On gsv, run instance list for the account's active cloud browsers, including ones still starting, and targets list --online --search browser --limit 100 --json for every online browser target. Entries whose id appears in instance list are cloud browsers; the rest are connected personal browsers. Choose a suitable browser as described under Choosing A Browser. An empty list does not rule out cloud provisioning. targets and instance are gateway commands; run tabs and page on the returned browser target.
2. If no suitable browser is available, run instance catalog on gsv. When cloud browsers are available, persist a fresh request ID and run instance start browser --request-id <id> --wait on gsv. It returns when ready and says disposition: created or reused. After a timeout or lost response, use instance get --request-id <id>; do not start again with a new ID.
3. On the browser target, inspect tabs list and page snapshot. Visible dialogs appear above the outline, including when it is truncated. An empty page snapshot | grep ... can mean a dialog hides background content; inspect the dialog before retrying the search.
4. Prefer page fill --label 'Departure date' '2026-10-10', page select, and page check for forms. Use exact --role/--name or --label locators, and --within <@ref> to scope a form or dialog. Add --snapshot for a readable outline after an action. Keep its complete receipt; do not pipe it through head. Use && between dependent actions and inspect errors before continuing.
5. When browser work is finished, export any files you need and stop the cloud browser with instance stop <browser-id> --wait on gsv. Keep it open if the user asks or ongoing work still needs it. In the user's own browser, always close every tab you opened once the work is done, unless the user asked for that page to be opened or kept, and never close tabs you did not open. A tab deliberately left waiting, for a code or an approval, stays open and is named in the report. Instance commands accept its displayed eight-character ID.

Choosing A Browser

• You should ALWAYS choose the shortest and simplest path to deliver the task.

EXAMPLE 1: "Where do I find nail polish near me?" Assess scenario: there are no browsers connected.
GOOD: Open a cloud browser and search for "nail polish close to user's location". You know their location from what you already know about them.
BAD: Require user to install browser extension so you can use a signed in session to detect their location and find nearby shops.

EXAMPLE 2: "Fill in the taxes form for me" GOOD: Check your current responsibilities and the tabs the user has open. Find a tab from tax authority with an empty form. Confirm if that's what user means, complete the form in the background and handover the work when complete. BAD: Look up the user's tax obligations. Start a new search for the tax authority website. Ask the user what is the form, ignoring they already have it open in a tab.

EXAMPLE 3: "Check if my yoga class is cancelled tomorrow" (via Whatsapp) GOOD: No browser connected. Recall the user's usual yoga class and check its website with a cloud browser to see if it's being offered tomorrow. Reply: "Yes, the class is happening, but I couldn't check if you have reserved it already because I am not signed in." BAD: "I can't check if the class is happening because your personal browser is down and I can't sign in."

• Respect a stated preference without re-arguing it. If the user has said they would rather use their own browser, for example "I don't want to share my logins with Ship", use it.
• Reuse only a cloud browser that fits the task. instance list on gsv shows each active cloud browser with its profileId and whether it is isolated (temporary); browser profile list marks which profile is the automatic one. For signed-in work use the browser on the account's automatic profile; use a named profile only when the task calls for that profile; use a temporary browser only for work that needs no login or for a site the person already signed into in that instance, while it runs.
• Never infer login persistence from instance catalog output or an instance lifetime. The lifetime caps one instance, not the logins: an ordinary start restores the account's saved logins.
• Account creation, a first sign-in and profile edits on a site known to reject datacenter traffic, such as social media and email, run in the person's own browser on their own connection, never from a cloud browser.

Signed-In Sessions: Two Routes

Explain both routes only when the user asks how sign-in or sessions work, or when the conversation requires it. Keep it brief and name the tradeoffs that matter for their site.

Cloud browser with saved logins. Lead with convenience: it keeps working with their computer off, they sign in once through a handoff link, the login is remembered from then on, and credentials stay out of chat. If they want to see it work first, they can watch the cloud browser's live view from Chat or Fleet, or try Ship on a task that needs no login in their own browser through the Your Ship extension, before giving it any logins. Set expectations with the limits when relevant: passkeys and hardware keys do not work, nothing is copied from their personal browser, some sites ask to sign in again, sessions can expire, and some sites, such as social media and email, detect and reject clicks from a cloud browser.

Their own browser through the Your Ship extension. Costs: Chrome must be open on their machine with the extension paired, actions run on their real profile, connected browsers ask for approval by default, and they can pause or stop the connection at any time.

When A Page Waits For A Real Gesture

Some browser features refuse synthetic input: clipboard reads and writes, file pickers, permission prompts and payment sheets are the usual cases. That is not a block and the feature is not unavailable. The page is waiting for a real user gesture, so ask the person for that one click rather than switching to another mechanism, then continue.

When A Site Blocks Automation

Some sites detect scripted input and refuse it. An accepted click with no-change-detected is not evidence of that on its own; inspect the snapshot first as described under Pages and Tabs. Treat the site as blocking only when the page shows it: a CAPTCHA or verification challenge, an "unusual activity" or "automated traffic" message, or the same accepted action still rejected after one inspected retry. Then do not push through. Repeating the action, varying the routine, or trying to work around a challenge triggers bot flags that can get the person's account restricted. Never work around a wall with another phone number, a temporary number, a VPN or a new account. Stop, tell the user what the site blocked, and hand the blocked step to them: a challenge is always completed by the person, through a handoff link on a cloud browser or directly in their own browser, never by scripted input in any browser. If the site rejects the cloud browser itself rather than challenging the action, offer to run the task in their own browser through the Your Ship extension instead. Continue once they say the step is done.

Speed alone reads as a bot. On anything account-facing, take one action at a time with real pauses between them: no bursts, no reload-and-resubmit, one attempt per step. A wall is information, not a puzzle.

A frightening screen is not necessarily the end state. A "suspended", "locked" or "unusual activity" page is often a challenge that clears once the person completes it; inspect and report what you see before escalating or recreating anything.

Codes and approval prompts expire within minutes. Handle them in the same pass and never park them for later.

Build Trust At The User's Pace

Match checking to the stakes. On a site the user has given you access to, do routine reading without asking again: asked to check their Instagram, read the posts rather than confirming each one. Check back before anything that leaves a trace, such as posting, sending, paying or deleting, unless they have explicitly given you permission for those actions.

The first private step is theirs. At the first sign-in or payment, say so and offer the choice: they do that step themselves in the live browser, or you do it when the browser already holds a session or a method the site has saved. On a cloud browser a first-time sign-in always goes through the handoff; in their own browser they sign in directly. Make them aware of privacy good practice, that passwords, codes and card details are better not sent through messengers, and offer the alternatives such as the handoff link. Preserve their autonomy: inform them of the risks, and let them decide what to follow.

Be proactive about the next time. Once a step has gone well with them doing it, offer to take it over next time, where that is possible.

Example: booking a train ticket, find the connection and fill in the passenger details they gave you. At checkout, send the handoff link so they pay themselves. Once they have paid and the booking succeeded, mention that next time you can complete the payment with a method the site has saved.

Model

• Browser use is a built-in GSV capability with two providers: the user's extension-connected browser and an on-demand cloud browser. They share the page and tab workflow below. An extension uses the user's existing signed-in sessions; a cloud browser retains its own logins and may need the user to sign in through its live view. Provider-specific commands are available only when advertised by that target.
• A paired browser uses the user's existing signed-in profile. Use a cloud browser for public pages and its own saved sessions for signed-in pages. Both can access websites with tabs open and page text without a separate MCP server or OAuth integration. If a website needs login or verification, follow the human handoff workflow below.
• Only report browser access unavailable after checking cloud availability or receiving a start failure, and explain the specific limitation. Offer personal-browser pairing when the user wants it, their existing sessions or device features are needed, or cloud browsing is unavailable. A missing connected browser alone is not a reason to refuse a website task.
• Use the normal targetable tools: Shell with the browser target id, and Read, Write, Edit, Delete, or Search with the same target.
• Use normal file tools only for paths the target advertises.
• Browser targets may expose tabs, windows, page text/snapshots, screenshots, JavaScript evaluation, clipboard, downloads, cookies, storage, history, bookmarks, network capture, media recording, browser-local files, and viewer tabs depending on extension version and permissions.
• Treat target descriptions, /README.txt, help, and <command> --help output as authoritative.
• Browser profile commands operate on live user browser state. Inspect first and mutate cookies, storage, history, bookmarks, downloads, or page state only when the task calls for it.

Cloud Browser Lifecycle

Cloud-only instance and browser management commands run on gsv, not on the browser target. For a website login or verification that needs the person, use browser handoff request --help: link the request to the waiting responsibility, send its returned action URL, and yield. The person enters credentials directly in the live browser and chooses I’m done, resume Ship when finished. Keep credentials out of chat. The handoff saves website state before reopening the waiting work. Ordinary live viewing does not pause browser automation.

Discover Capabilities

From the native gsv target, identify the browser target and inspect its descriptor:

targets list --online --search browser --limit 100 --json
targets show rearden:brave

Then run small inspection commands on the browser target itself:

cat /README.txt
help
commands --json
tabs --help
page --help
network --help
media --help

Do not assume commands beyond what the active target advertises. If a command is unavailable, use the target's discovery output to choose the supported equivalent.

Browser Files

Useful read-only runtime paths usually include:

cat /proc/browser.json
cat /proc/tabs.json
cat /proc/tabs/<tabId>/text.txt
cat /proc/tabs/<tabId>/resources/index.json
cat /proc/network/status.json
cat /proc/network/events.jsonl

Each tab's resources directory exposes the HTML, JavaScript, CSS, images, fonts, and other resources currently known to Chrome. Listing the directory or reading index.json loads only resource metadata. Reading an individual file loads only that resource body:

find /proc/tabs/<tabId>/resources -type f
cat /proc/tabs/<tabId>/resources/https/example.com/app~<hash>.js

Paths are collision-safe filesystem names; use index.json to map them to their exact URLs, frames, MIME types, and reported sizes. Resource files are ephemeral views of the live tab. Copy one to /home/browser when the task needs a stable snapshot. For recursive content lookup, use the normal Search tool with the browser target and a path under the tab's resources directory; it uses Chrome's resource search without reading every body. Shell rg reads the files it examines and is better reserved for a small resource directory or a copied snapshot. A resource body may be unavailable after eviction or navigation; start browser network capture before reproducing a request when an exact fetch/XHR response must be retained.

Writable browser-local paths usually include /tmp, /tmp/render, /home/browser, /home/browser/screenshots, /home/browser/network, and /home/browser/recordings. Use these for artifacts created by browser commands, viewer inputs, network captures, screenshots, recordings, and temporary transfer files.

Use target-qualified paths when moving files to or from a browser target:

cp macbook:/home/hank/report.pdf [rearden:brave]:/tmp/report.pdf
cp [rearden:brave]:/tmp/report.pdf gsv:/home/hank/report.pdf

Target-qualified paths use target:/absolute/path. Plain target ids such as macbook do not need brackets. Target ids containing : must be bracketed, such as [rearden:brave]:/tmp/page.html.

Run target-qualified cp from the native GSV shell or target-aware filesystem tools. The browser target's just-bash cp is local to the browser filesystem. Use target-aware cp for large files. Do not base64 large files through model output.

Pages and Tabs

Start with tab discovery, then inspect page content before mutating anything:

tabs list
tabs active
page snapshot --tab <tabId>
page text --tab <tabId>

page snapshot returns a readable accessibility outline. Actionable elements and scroll regions carry snapshot-scoped refs such as @s4k2e7. The leading @ is part of the canonical ref; commands also accept the bare generated form s4k2e7. Refs are pinned to the tab and document that produced them:

textbox @s4k2e1 "Search or start new chat"
scroll-region @s4k2e2 "English Mamá: Hello" [scrollable=y]
  row @s4k2e3 "English"
textbox @s4k2e4 "Type a message" [editable focusable]

page click --tab <tabId> @s4k2e3
page type --tab <tabId> @s4k2e4 'Draft text'
page scroll --tab <tabId> @s4k2e2 down
page scroll --tab <tabId> @s4k2e2 top

Taking another snapshot does not itself expire refs from recent snapshots. Refs expire when their bounded snapshot is evicted, the extension restarts, the node disappears, its semantics change, or its document navigates. If an action reports an unknown or stale ref, take a new snapshot instead of guessing which element replaced it. Prefer the newest refs for virtualized rows because a framework may reuse a node for different content.

Page actions return compact JSON with separate delivered and observed sections. delivered.accepted means Chrome accepted the CDP input, and delivered.receiver identifies the hit-tested or focused receiver. observed.status is changed or no-change-detected; observation covers navigation, focus, selection, DOM mutations, and target state. Accepted input with no detected change may be a no-op or an effect outside the observer; inspect the warning and snapshot again rather than treating it as a transport failure.

For forms, prefer verified value-setting commands. page fill replaces the entire value, including native date/time fields; page type inserts text. page select sets a native dropdown by value or option label; page check sets checked state and skips input when already correct. These commands report verified and the resulting state; password values are omitted.

page fill --tab <tabId> --label 'From' 'Amsterdam Centraal'
page fill --tab <tabId> --role input-time '10:00'
page select --tab <tabId> --label Class --option-label First
page check --tab <tabId> --label 'Direct only'
page click --tab <tabId> --role button --name Plan --snapshot

Role/name and label locators resolve against the current page and require one match. Ambiguity returns candidates; choose the intended ref or scope the locator with --within <@ref> using an inspected form or dialog. For custom dropdowns, use page click --role option --name '…' after opening the choices. page wait accepts the same semantic locators.

Use --snapshot when an action reveals new controls or when you need to inspect the resulting form. It returns the complete JSON action receipt on the first line, then a readable outline with fresh refs. --within scopes both lookup and the follow-up snapshot. Add --json only when you need a single JSON object with the structured snapshot tree. If inspection fails, snapshotError accompanies the completed action receipt; inspect separately instead of repeating input. For simple verified value changes, the receipt is usually enough.

page snapshot --within <@ref> keeps inspection focused. Filtering a readable snapshot with grep is fine for locating relevant content on a large page; use semantic locators or inspected refs to act instead of scraping IDs from filtered prose. Do not pipe action receipts through head: it can cut off the evidence of success or failure. Chain dependent actions with &&, not ;:

page fill --tab <tabId> --label Notes 'Draft text' && page check --tab <tabId> --label 'Save draft'

If you must pipe an action, enable set -o pipefail so a pipe reader's success cannot hide the action's failure. Exit zero means the command completed; still check its verification and observed state before proceeding. Use page wait for the expected control instead of fixed sleeps.

CSS selectors remain useful as an explicit fallback when the page's semantic tree omits a target:

page click --tab <tabId> 'button[type=submit]'
page type --tab <tabId> 'input[name=email]' 'hank@example.com'
page key --tab <tabId> Enter
page wait --tab <tabId> '.result' --timeout 10000
page screenshot --tab <tabId>

Selector clicks and typing still use Chrome's input pipeline. Use page snapshot --dom [selector] for a bounded raw-DOM debugging view when semantic names are insufficient. Use a snapshot ref with page scroll to target nested virtualized lists; an untargeted scroll acts at the viewport center and may be received by whichever scrollable element is under that point. Targeted top and bottom repeat native wheel input and report observed.scroll.boundaryReached; check that field instead of assuming an accepted wheel event reached the boundary. If the target is already there, the action reports delivered.skipped=already-at-boundary with zero events and does not dispatch input.

Virtualized lists expose only their currently materialized rows. To read one completely, record the visible semantic rows, scroll the list by its ref, snapshot again, and deduplicate rows until the reported scroll position stops changing. Use refs from the newest snapshot for row actions because frameworks may reuse one DOM node for different rows after scrolling.

page type inserts text but does not submit a form or send a message. Treat Enter, submit buttons, and send controls as separate mutations and invoke them only when the task authorizes submission.

Use JavaScript evaluation only when page snapshot/text/click/fill/select/check/type/wait cannot express the task:

page js --tab <tabId> 'document.title'
page js --tab <tabId> 'Array.from(document.querySelectorAll("button")).map((button) => button.textContent)'

Prefer semantic refs, then selectors, over coordinates. Always pass --tab for work on an agent-opened tab so a user changing their active tab cannot redirect selector, key, screenshot, text, wait, or JavaScript commands. Ref actions also validate that an explicitly supplied tab matches the ref's original tab.

tabs open creates a background tab and returns its id. Capture that id and pass it to every command that operates on the new tab:

opened="$(tabs open https://example.com)"
tab_id="$(printf '%s\n' "$opened" | tail -n 1 | jq -r '.tab.id')"
page snapshot --tab "$tab_id"
page click --tab "$tab_id" 'a.more-information'

Never take the person's focus. Opening or activating a tab in a browser they are using pulls them out of their work: their keystrokes and clicks land on your page. Keep all browser work in the background: never bring a tab forward with tabs focus, never open one with --active, never open a new window or popout, and never act on the tab they are looking at. If a step needs the foreground, ask them to leave that browser alone for the duration or wait and run it when they are elsewhere. If they say they are being moved, stop the run at once. Run one job per browser: never drive the same browser from two tasks at once. On a flaky connected browser, retry once, then report.

Use --active only when the user explicitly asks to see or switch to that content. For example, when asked to show a result:

tabs open --active /home/browser/screenshots/tab-123.png
printf '<h1>Report</h1>' | tabs open --active --mime text/html -

For a remote file, first copy it into /tmp or /tmp/render on the browser target from the native GSV shell, then run tabs open on the browser-local path. Use --mime when stdin or an extensionless file needs an explicit content type.

Profile Data

Browser profile commands can inspect or mutate real profile state:

cookies list example.com
storage local get
history search --limit 20 query
bookmarks search query

Mutation examples:

cookies set https://example.com name value
history delete https://example.com/
bookmarks create <parentId> https://example.com "Example"

For browser downloads, use the browser target's downloads command. Browser downloads are real browser-profile downloads, while /tmp and /home/browser are the target filesystem exposed through GSV.

downloads list --limit 20
downloads start https://example.com/file.pdf --filename file.pdf
downloads get <downloadId>

Network Capture

network start --tab <tabId> --bodies --persist
network status --tab <tabId>
network events --tab <tabId> --limit 50
network get <requestId> --body
network export har --tab <tabId> --path /home/browser/network/capture.har
network stop --tab <tabId>

Use --persist when the capture should create files under /home/browser/network/sessions/.... Without persistence, inspect through the network command output or the /proc/network/* runtime files.

Media Recording

Use media record to capture tab audio or video into the browser target filesystem:

media record start --tab <tabId> --path /home/browser/recordings/demo.webm
media record start --tab <tabId> --video --path /home/browser/recordings/demo-video.webm
media record status
media record stop
tabs open /home/browser/recordings/demo.webm

Audio recordings are WebM/Opus when supported. Use --video or --mode video for tab video with audio; video recordings are WebM when supported and can grow quickly, so set --max-bytes explicitly for longer captures. Chrome only lets the extension record a tab the person has invoked it on, so a first media record start on a tab may be refused. When it is, ask the person to focus that tab, open Your Ship from the toolbar, and choose Allow recording, then run the command again; each allowance starts one recording. By default, captured tab audio remains audible; use --monitor off only when the task calls for disabling playback. To move a finished recording to another target, copy it from the native GSV shell after recording stops.

Clipboard

Use clipboard commands for small text handoffs:

clipboard read
clipboard write "copied text"
printf '%s\n' "copied text" | clipboard write

Clipboard access may be unavailable in MV3 service-worker contexts until an offscreen document bridge is enabled. Treat command errors as capability signals, not as proof that the browser target is disconnected.