Skip to content

AGENT_SETUP.md

Latest commit

 

History

History
151 lines (119 loc) · 6.41 KB

AGENT_SETUP.md

File metadata and controls

151 lines (119 loc) · 6.41 KB
Raw

Browser Use Terminal — agent setup

You are (probably) a coding agent reading this because a user pasted https://browser-use.com/skill into the chat. Follow this page top to bottom. It installs Browser Use Terminal, registers its skill with you, connects a browser, and verifies everything — then you can browse the web for your user. Every step is idempotent; re-run safely. Tell the user what you're doing as you go, and stop to ask only where this page says to.

What you get: a browser-use-terminal CLI you drive from shell commands — run Python against a real browser (navigate, click, type, screenshot, extract). You are the agent; you drive the browser.

1. Preflight

uname -s                 # Darwin or Linux. Windows: use WSL; native Windows is not supported yet.
command -v curl || command -v wget
command -v tar
python3 --version        # need 3.9+

If python3 is missing: macOS → xcode-select --install (or brew install python3); Debian/Ubuntu → sudo apt-get install -y python3; Fedora → sudo dnf install -y python3. If you cannot install it, ask the user to.

2. Install Browser Use Terminal

curl -fsSL https://browser-use.com/terminal/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"   # the installer edits the shell profile, but YOUR current shell needs this
browser-use-terminal --version         # verify

Notes: no sudo needed; binaries land in ~/.local/bin (browser, browser-use, browser-use-terminal, but); state lives in ~/.browser-use-terminal. Already installed? The same command updates it. Add the export PATH line to every later shell command in this session, or rely on the profile in new shells.

3. Register the skill with yourself

browser-use-terminal skill install

This writes the skill (full usage instructions for you) into every detected assistant home: ~/.claude/skills/, ~/.codex/skills/, ~/.config/opencode/skills/, ~/.agents/skills/. Claude Code, Codex, OpenCode, and anything reading those conventions will auto-discover it in new sessions.

If you are a different agent (none of those directories exist, or you know you don't read them): run browser-use-terminal skill show and persist its output wherever you read durable instructions (e.g. your AGENTS.md, rules file, or memory). If you can't persist anything, just read it now — this session can proceed either way.

4. Connect a browser (pick one)

Default — zero user interaction (recommended to start):

browser-use-terminal browser preference use managed-headless

This uses a disposable headless Chromium that persists across your commands. It requires a Chromium-family binary on the machine (Chrome, Chromium, or a Playwright Chromium). Check: ls "/Applications/Google Chrome.app" 2>/dev/null || command -v google-chrome chromium chromium-browser. If none exists: ask the user to install Chrome (or set CHROME_PATH=/path/to/chrome).

The user's real, logged-in Chrome (for tasks needing their accounts):

browser-use-terminal browser preference use local
browser-use-terminal browser connect local

One-time user action required: they must open chrome://inspect/#remote-debugging in Chrome and tick "Allow remote debugging for this browser instance". browser-use-terminal browser local setup walks them through it. Relay any needs-user-action JSON (user_prompt field) to the user verbatim and wait.

Cloud browser (headless server / clean remote IP; needs an API key from https://cloud.browser-use.com):

export BROWSER_USE_API_KEY=bu_...
browser-use-terminal browser preference use cloud

Cloud browsers bill until stopped (browser-use-terminal browser recover stop-owned-remote).

5. Verify end to end

browser-use-terminal browser exec <<'PY'
new_tab("https://example.com")
wait_for_load()
print(page_info()["title"])
print(capture_screenshot())
PY

Expected: it prints Example Domain and Screenshot saved to <absolute path>. Now view that screenshot with your own file-reading tool to confirm you can see pages: Claude Code → Read the path; Codex → view_image with the path; OpenCode → read the path; Gemini CLI → read_file; otherwise use whatever tool you have that displays a local image. If your model can't view images, skip this — you'll work from text state (page_info(), js(...)) instead.

If this step worked, setup is complete. Tell the user you're ready to browse.

6. Using it (crash course)

Full instructions are in the skill you installed (or browser-use-terminal skill show). The essentials:

  • Run Python against the live browser with heredocs. Helpers are pre-imported: new_tab(url), goto_url(url), page_info(), click_at_xy(x, y), type_text(text), press_key("Enter"), fill_input(sel, text), scroll(), wait_for_load(), wait_for_element(sel), capture_screenshot(), js(expr), cdp(method, **params), http_get(url).
  • The browser persists between commands; Python variables do not.
  • Screenshot-first workflow: screenshot → read coordinates off the image → click_at_xy (CSS pixels — divide image coordinates by js("window.devicePixelRatio")) → screenshot again to verify.
  • In the user's real Chrome, open work in new_tab(...), never goto_url over their active tab.
  • Auth walls: stop and ask the user. Never type credentials read off a screenshot.
  • Parallel workstreams: add --session <name> to browser commands.
  • Done for the day: browser-use-terminal browser recover stop-owned-browser (managed) or ... stop-owned-remote (cloud).

Troubleshooting

  • command not found → re-run export PATH="$HOME/.local/bin:$PATH".
  • browser is not connected → browser-use-terminal browser connect (uses the remembered preference) or re-run step 4.
  • Anything returning status: "needs-user-action" → show its user_prompt to the user exactly, wait, then retry.
  • Diagnostics: browser-use-terminal browser doctor and browser-use-terminal browser status --json.
  • A background daemon holds the browser connection between your commands (auto-started). If it misbehaves: browser-use-terminal browser daemon status, ... daemon logs, ... daemon stop (next command restarts it and reattaches).
  • Slow first command in each shell: the launcher checks for updates; set BUT_AUTO_UPDATE=0 to skip.

Full documentation: https://docs.browser-use.com/open-source/browser-use-terminal Source & issues: https://github.com/browser-use/terminal