Octop Browser

Overview

Octop Browser is a lightweight browser-use style tool that makes an agent's browser usage more accurate and reliable. It launches a real Chromium and communicates directly with the Chrome DevTools Protocol (CDP) instead of routing every action through Playwright.

Key Features

• Direct CDP connection to a real Chromium browser without Playwright or an intermediate layer.
• Stable ref-based element targeting that survives layout reflows and re-renders.
• Token-efficient multi-level DOM builder that keeps prompts small.
• Profile-based login persistence across sessions.
• A stateless browser_tool with about 20 actions and a matching first-class CLI.
• Record and replay workflows as skill-guided agentic execution, plus an MCP server for any MCP-capable agent.

Use Cases

• Enabling AI agents to navigate, click, type, fill, and extract data from real web pages.
• Automating browser workflows such as form filling, screenshots, tab management, and history navigation.
• Recording a real browsing session and replaying it as skill-guided agentic execution.
• Exposing browser tools to any MCP-capable agent through the built-in MCP server.

Getting Started

• Install Python 3.11 or newer and run pip install octop-browser, then octop-browser install-browser to fetch a Chromium binary.
• Use as a library with BrowserSession.create(profile="default") or statelessly with browser_tool(action="navigate", url=..., profile="work").
• Use as a CLI with commands such as octop-browser --help, octop-browser navigate "https://example\.com" --profile work, and octop-browser dom-tree --profile work.
• Record a workflow with octop-browser record daemon-start, record start, record stop, record generate-skill, and replay run.

Deployment & Requirements

• Python 3.11+ (verified on 3.11 and 3.12).
• A Chromium or Chrome binary; install-browser auto-downloads one.
• Optional environment configuration such as BROWSER_USE_MODE, BROWSER_USE_CDP_WS_URL, and BROWSER_USE_PROFILES_DIR.
• For remote or Docker Chrome, set BROWSER_USE_CDP_WS_URL to connect directly to an existing DevTools WebSocket URL and skip the launcher.

Before You Adopt

• License: MIT. Review its terms before using, modifying, or distributing the project.
• The no-sandbox flag may be added automatically in container environments where the kernel denies unprivileged user namespaces.