browser-automation

Use bb browser-automation. Open one session, retain its session ID, then inspect, act, and verify in short scripts.

--machine accepts an exact host ID or an unambiguous machine name. Exact IDs take precedence over names; unknown or ambiguous names fail before opening a session.

Choose --backend local --headless --machine <host-id> for headless Chrome on an enrolled host. Choose --backend desktop --machine <host-id> --desktop <instance-id> for a new desktop automation tab. Desktop tabs use the BB browser's profile, including the user's signed-in cookies. Starting desktop control opens the side panel and selects the browser tab only if its thread is already focused. New or activated controller pages follow the same rule; automation does not switch threads or bring the desktop window forward. While controlled, a desktop tab never takes keyboard focus from the composer or other apps; the user presses Take over to type into it. Headless sessions remain headless. Plugin-owned local/headless Chrome launches with --no-sandbox, disabling Chrome's sandbox. Desktop attachment does not change the browser's launch flags. Resolve the explicit instance with bb browser instances --host <host-id> --json first. Never silently choose a different host or mode. Adding --tab <tab-id> takes control of an existing tab; do so only when the user asked to use that tab. The CLI uses the current thread, or --thread <id> outside a thread. Each session belongs to that thread.

CLI opening:

bb browser-automation open --backend local --headless --machine <host-id> --json
bb browser-automation open --backend desktop --machine <host-id> --desktop <instance-id> --json

Run scripts:

bb browser-automation run <session-id> --script 'const p = await browser.getPage("main"); await p.goto("https://example.com"); await p.snapshot()' --json
bb browser-automation run <session-id> --script 'const p = await browser.getPage("main"); await p.click("ref/e6"); await p.snapshot()' --json
bb browser-automation screenshot <session-id> --page main --json

Take a fresh snapshot before using refs after navigation or document changes. Use refs from that session's DevBrowser snapshot. Do not mix agent-browser refs or invent selectors. Prefer a cheap URL/text/snapshot check after each action; request a screenshot when visual verification matters. Use await p.shot({type:"jpeg",maxEdge:960,quality:70}); undefined inside scripts to return a bounded JPEG file.

run and screenshot return JSON with hostId and images, where each image has path, mimeType, width, and height. The path is in the browser session's temporary directory on that host. Use your image-reading tool on the path when you are on the same machine. If the browser host differs, fetch the image to local temporary storage first (substitute the returned path and host ID):

bb file read '<image-path>' --host '<host-id>' --json | node -e '
const fs = require("node:fs"), os = require("node:os"), path = require("node:path");
const file = JSON.parse(fs.readFileSync(0, "utf8"));
if (file.contentEncoding !== "base64") throw new Error("Expected binary image");
const destination = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "browser-image-")), "capture.jpg");
fs.writeFileSync(destination, Buffer.from(file.content, "base64"), {mode: 0o600});
console.log(destination);
'

Read the printed local path with your image-reading tool. Do not print base64 image bytes into the conversation. Read or copy captures before closing the session: cleanup removes its temporary directory. Remove local copies when finished.

A local headless open returns a previewDirective, for example ::browser-preview{session="<session-id>"}. Copy it into your next message exactly once as a standalone line, before you continue working. Do not wrap it in backticks or a code fence, and do not invent or edit the session ID. BB renders it as a live view of that browser in the chat, which the user can expand, so they can watch while you work. Desktop sessions return no directive; that browser is already visible in the side panel. bb browser-automation preview <session-id> --json reports the live frame's url, title, size, and sequence without image bytes; it is not a substitute for screenshot when you need to see the page.