Octop Browser

octop-browser Browser Automation

You drive a real Chrome browser via the Chrome DevTools Protocol (CDP) by running the octop-browser CLI through the Bash tool. Each invocation attaches to the same Chrome process per profile, so a sequence of commands shares one persistent session.

Core Rules

1. Always run dom-tree before click — refs expire on navigation.
2. Default to --level interactive (~200-500 tokens) to get clickable/typeable elements.
3. Use --level minimal (~50 tokens) only to confirm page state or URL.
4. Use --level full (~1000-3000 tokens) only when reading page content.
5. Use --level structured when you need JSON for programmatic processing.
6. Never hardcode coordinates — always pass --ref from dom-tree.
7. Use named profiles to persist login state across runs: --profile work, --profile github.
8. On CDP error: run dom-tree --level minimal to check state, then retry.
9. Tear down with close-session --profile when finished — Chrome itself keeps running so you can reattach later.

Standard Workflow

# 1. Navigate
octop-browser navigate "https://example.com" --profile default

# 2. Get interactive elements with refs
octop-browser dom-tree --profile default
# Output:
#   [ref=inp_1] input[text] placeholder="Search"
#   [ref=btn_2] button "Search"

# 3. Act using refs — never coordinates
octop-browser click --ref inp_1 --profile default
octop-browser type "hello" --profile default
octop-browser click --ref btn_2 --profile default

# 4. (optional) capture proof
octop-browser screenshot --path /tmp/result.png --profile default

Add --json to any command when you want the full structured ToolResult (success / content / metrics / metadata / error) instead of the human-readable default.

Commands Reference

| Command | Required args | Common options | |---|---|---| | navigate | url | --profile, --json | | dom-tree | — | --level {minimal,interactive,full,structured} | | screenshot | — | --full-page, --element-ref REF, --path PATH | | click | one of --ref REF / --selector CSS / --xy X Y | | | type | text | --ref REF (click before typing) | | scroll | — | --direction {up,down,left,right}, --amount N | | hover | ref | | | eval-js | expression | | | go-back / go-forward / reload | — | | | list-tabs | — | | | new-tab | — | --url URL | | switch-tab | tab_id | | | close-tab | — | --tab-id ID | | close-session | — | (only --profile) |

All action commands accept --profile, --json, and one of --auto / --headed / --headless (the launch-mode flag is only honoured on the first call per profile — Chrome is reused after that).

Screenshots

screenshot writes a PNG to disk and prints its path (not base64). With --json, the response also includes metadata carrying url / title / width / height / size_kb / full_page.

• Default path: BROWSER_USE_SCREENSHOTS_DIR/octop-.png

(default ~/.octop-browser/screenshots/)

• --full-page — capture the entire scrollable page in one call
• --element-ref btn_2 — crop to a specific element (mutually exclusive

with --full-page; element wins)

• --path /tmp/latest.png — pin the file path; every call overwrites it

Configuration (environment variables)

All knobs are env-driven; no code changes between dev / CI / prod.

| Variable | Default | Use | |---|---|---| | BROWSER_USE_MODE | auto | auto / headed / headless (auto picks based on DISPLAY) | | BROWSER_USE_PROFILES_DIR | ~/.octop-browser/profiles | Where Chrome user-data-dirs live | | BROWSER_USE_SCREENSHOTS_DIR | ~/.octop-browser/screenshots | Default screenshot output directory | | BROWSER_USE_CHROME_BIN | auto-detect | Path to Chrome (also auto-detects Playwright's bundled Chromium) | | BROWSER_USE_CDP_HOST | localhost | Remote/Docker Chrome host | | BROWSER_USE_CDP_WS_URL | — | Bypass launcher; connect directly to a WS URL |

Login State Reuse

Profile data lives in ~/.octop-browser/profiles//. Reusing the same profile name in future sessions reuses Chrome cookies — no re-authentication needed.

# First run: log in manually (needs a desktop / headed mode)
octop-browser navigate "https://github.com/login" --profile github --headed
# ... complete login in browser ...

# All future runs: login reused automatically
octop-browser navigate "https://github.com" --profile github

Installation

pip install octop-browser

# Chrome or Chromium required:
# Ubuntu: sudo apt install chromium-browser
# macOS:  brew install --cask google-chrome
# Or, no system browser: octop-browser install-browser
#   (auto-installs `playwright` then downloads a Chromium binary; set
#    OCTOP_SKIP_PLAYWRIGHT_PIP=1 to skip the pip step)

Python API (alternative)

If you'd rather embed octop-browser in a Python script instead of shelling out, the same actions are available as from octop_browser import browser_tool returning a ToolResult. The CLI is the recommended path for skill / agent use — it's stateless from the caller's perspective and round-trips through the shell cleanly.

Repository

https://git.woa.com/orcakit/browser-use.git

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: TencentCloud
• Source: TencentCloud/octop-browser
• License: MIT
• Homepage: https://octop.cloud

Install and usage instructions live in the source repository linked above.