agent-browser (browser inside the sandbox)

The CLI is already installed. Do not install it again, do not run agent-browser install, and never install a browser yourself: the sandbox pins its own Google Chrome. Run it with shell_exec and without skill_name. Every call is one command; the browser stays open between calls.

Start here

This file is only the map. Load the real usage guide from the CLI itself, so the instructions always match the installed version:

agent-browser skills get core        # workflows, common patterns, troubleshooting
agent-browser skills get core --full # adds the full command reference
agent-browser skills list            # specialized guides bundled with the CLI

For quick tasks the loop below is enough; read core before anything harder (waits, iframes, multiple tabs, downloads, auth flows).

Basic loop

agent-browser open https://example.com   # the window opens on the Desktop tab
agent-browser snapshot -i          # interactive elements as @e1, @e2, ...
agent-browser click @e2
agent-browser fill @e3 "text to type"
agent-browser screenshot /workspace/output/page.png
agent-browser close                # closes the browser; the screen stays

Run snapshot -i again after every page change: refs from an older snapshot go stale. agent-browser --help lists every other command.

Screens

The browser always opens as a visible window on the user's Desktop tab, so the user can watch it and take over. Do not ask the user whether to show it, and do not pass any flag to hide or show it. The user may click in the same window while you work: run snapshot -i again before acting if the page may have changed. Never ask for a password or code in the chat.

Logins and codes

When a page asks for a username, password or one-time code and the request_secure_form tool is available:

1. Call request_secure_form with the page's host as site.
2. Run agent-browser snapshot -i again, then call browser_fill_secret with the handle and the refs of the inputs.
3. Click the sign-in button yourself; the tool never submits.

Judge success by the statuses browser_fill_secret returns. Until you leave that page, do not take screenshots, do not click "show password", and do not read input values with get value or eval.

Without request_secure_form, or for a captcha, ask the user to type it into the window on their Desktop tab.

Rules

• Do not pass --session, --profile, --cdp, --auto-connect, --state or --executable-path. The sandbox supplies the profile, the session and the browser; those flags are discarded.
• Do not set DISPLAY, and do not target display :0. That screen belongs to other sessions.
• Close the browser only with agent-browser close. Never pkill/kill chrome or agent-browser processes: other sessions' browsers run on this machine too, and agent-browser close only ever touches this session's own browser.
• Cookie state is saved in a machine-level seed and restored before startup navigation. Live browsers mirror missing cookies and localStorage keys; existing keys are not overwritten. A receiving page may reload once idle. localStorage is shared from open pages, not persisted in the cookie seed. Cookie and password database files are shared; history, cache and IndexedDB stay in each profile. Signing out may affect shared login state. Windows remain on this session's screen. Never print cookie, password or token files.