BrowserCtl

A browser automation toolkit for AI agents using undetected-chromedriver with daemon-based session management.

Overview

BrowserCtl is a command-line interface for browser automation that integrates seamlessly with AI agents. It uses a daemon server architecture to maintain browser sessions across multiple command invocations, allowing you to execute multiple commands that operate on the same browser instance.

Architecture

The tool consists of two main components:

1. Daemon Server (browserctl daemon): A background process that manages browser sessions
2. CLI Client: Commands that communicate with the daemon via Unix sockets

Features

• Browser Automation: Open, close, and control browser sessions
• Page Navigation: Navigate to URLs, go back/forward, reload pages
• Element Interaction: Click, type, fill forms, drag and drop
• Tab Management: Create, close, and switch between tabs
• Storage Management: Handle cookies, localStorage, and sessionStorage
• Network Control: Route interception and network monitoring
• DevTools Integration: Console logs, performance tracing, element inspection
• Multi-Session Support: Run multiple isolated browser sessions
• Stealth Mode: Uses undetected-chromedriver to avoid detection

Installation

# Install using uv
uv tool install browserctl

# Or run directly
uv run browserctl --help

Quick Start

# Start the daemon (optional - will auto-start on first command)
browserctl daemon start

# Open a browser
browserctl open https://example.com

# Take a snapshot
browserctl snapshot

# Click an element (using ref from snapshot)
browserctl click e15

# Type text
browserctl type "search query"

# Press a key
browserctl press Enter

# Take a screenshot
browserctl screenshot

# Close the browser
browserctl close

# Stop the daemon
browserctl daemon stop

Daemon Management

The daemon server manages all browser sessions:

# Start daemon
browserctl daemon start

# Check daemon status
browserctl daemon status

# Stop daemon
browserctl daemon stop

# Restart daemon
browserctl daemon restart

# Run daemon in foreground (for debugging)
browserctl daemon start --foreground

Multi-Command Session Example

This demonstrates the key feature - multiple commands operating on the same browser:

# Command 1: Open browser in session "mysession"
browserctl open https://example.com --session mysession

# Command 2: Open new tab in the same session
browserctl tab-new https://example.com/other --session mysession

# Command 3: List tabs (shows both tabs)
browserctl tab-list --session mysession

# Command 4: Take screenshot
browserctl screenshot --session mysession

# Command 5: Close the session
browserctl close --session mysession

All these commands operate on the same browser instance because they use the same session name.

Commands

Core Commands

• open [URL] - Open a new browser session
• close - Close the browser session
• goto <URL> - Navigate to a URL
• snapshot - Take a page snapshot
• screenshot - Take a screenshot
• pdf - Save page as PDF
• resize <width> <height> - Resize viewport
• eval <script> - Execute JavaScript

Interaction Commands

• click <selector> - Click an element
• dblclick <selector> - Double-click an element
• type <text> - Type text into focused element
• fill <selector> <value> - Fill an input field
• press <key> - Press a key
• hover <selector> - Hover over an element
• drag <source> <target> - Drag and drop
• select <selector> <value> - Select option
• upload <file> - Upload a file
• check <selector> - Check checkbox
• uncheck <selector> - Uncheck checkbox

Navigation Commands

• go-back - Navigate back
• go-forward - Navigate forward
• reload - Reload page

Tab Commands

• tab-list - List all tabs
• tab-new [URL] - Open new tab
• tab-close [index] - Close tab
• tab-select <index> - Select tab

Storage Commands

• state-save [filename] - Save browser state
• state-load <filename> - Load browser state
• cookie-list - List cookies
• cookie-get <name> - Get cookie value
• cookie-set <name> <value> - Set cookie
• cookie-delete <name> - Delete cookie
• cookie-clear - Clear all cookies
• localstorage-list - List localStorage
• localstorage-get <key> - Get localStorage item
• localstorage-set <key> <value> - Set localStorage item
• localstorage-delete <key> - Delete localStorage item
• localstorage-clear - Clear localStorage
• sessionstorage-* - Similar commands for sessionStorage

Network Commands

• route <pattern> - Set network route
• route-list - List routes
• unroute [pattern] - Remove route

DevTools Commands

• console - Show console logs
• network - Show network logs
• run-code <code> - Run custom code
• tracing-start - Start performance tracing
• tracing-stop - Stop performance tracing
• pick - Pick element interactively
• highlight <selector> - Highlight element

Session Management

• list - List all browser sessions
• close-all - Close all sessions
• kill-all - Kill all browser processes
• delete-data - Delete session data

Multi-Session Support

Run multiple isolated browser sessions:

# Session 1
browserctl -s=session1 open https://site1.com

# Session 2
browserctl -s=session2 open https://site2.com

# Work with session 1
browserctl -s=session1 snapshot

# Work with session 2
browserctl -s=session2 snapshot

# Close all
browserctl close-all

Options

Global Options

• -s, --session <name> - Browser session name
• --raw - Output raw data without formatting
• --json - Output as JSON

Browser Options

• --browser <type> - Browser type (chrome, firefox, webkit, msedge)
• --persistent - Use persistent profile
• --profile <path> - Custom profile directory
• --headed - Run in headed mode (visible browser)
• --config <file> - Configuration file

Element Selectors

Elements can be selected using:

1. Refs - From snapshot (e.g., e15)
2. CSS Selectors - Standard CSS (e.g., #main > button.submit)
3. selenium Locators -
4. Test IDs - (e.g., getByTestId('submit-button'))

Examples

Form Submission

browserctl open https://example.com/form
browserctl snapshot
browserctl fill e1 "user@example.com"
browserctl fill e2 "password123"
browserctl click e3
browserctl snapshot
browserctl close

Multi-Tab Workflow

browserctl open https://example.com
browserctl tab-new https://example.com/other
browserctl tab-list
browserctl tab-select 0
browserctl snapshot
browserctl close

Authentication Flow

# Save authentication state
browserctl open https://app.example.com/login
browserctl fill "#email" "user@example.com"
browserctl fill "#password" "password"
browserctl click "#submit"
browserctl state-save auth.json
browserctl close

# Later, load authentication state
browserctl open https://app.example.com
browserctl state-load auth.json

Architecture

The project is structured as follows:

browserctl/
├── src/
│   ├── stealth_cli/          # Main package entry point
│   │   └── __init__.py
│   └── cli_client/           # CLI implementation
│       ├── __init__.py       # Typer app and command definitions
│       ├── browser.py        # Browser manager and session handling
│       └── commands/         # Command implementations
│           ├── core_commands.py
│           ├── interaction_commands.py
│           ├── navigation_commands.py
│           ├── tab_commands.py
│           ├── storage_commands.py
│           ├── network_commands.py
│           ├── devtools_commands.py
│           └── session_commands.py
├── pyproject.toml
└── README.md

Dependencies

• typer - CLI framework
• undetected-chromedriver - Stealth browser automation
• selenium - Browser automation framework
• pydantic - Data validation
• loguru - Logging

Development

# Install dependencies
uv sync

# Run CLI
uv run browserctl --help

# Run tests
python test_basic.py

License

MIT License

Contributing

Contributions are welcome! Please submit pull requests or open issues on the repository.

检测网站

https://bot.sannysoft.com/

1. BrowserLeaks

BrowserLeaks 显示泄露的个人数据，并提供相关文章帮助你理解每个部分和如何更好地保护自己。

检测项目

• IP 地址
• JavaScript
• WebRTC 泄露测试
• Canvas 指纹
• WebGL 报告
• 字体指纹
• 地理位置 API
• 功能检测
• 内容过滤器
• Java Applet
• Flash Player
• Silverlight

注意在使用前阅读其隐私政策以确保数据不被第三方服务收集。

2. AmIUnique

AmIUnique 不仅提供关于配置的信息，还研究浏览器指纹的多样性。点击主页上的“查看我的浏览器指纹”按钮即可测试。

检测信息

• 操作系统
• 浏览器及版本
• 时区和语言
• HTTP headers 属性
• JavaScript 属性

3. Cover Your Tracks

Cover Your Tracks 帮助你了解自己在追踪器面前的表现，并提供保护建议。

功能

• 提供详细的检测结果
• 提供保护建议

4. Device Info

Device Info 测试多个浏览器指纹指标，提供详细信息。

5. CreepJS

CreepJS 提供详细的指纹分析，显示用户相同元素的比例。

6. BrowserSPY

BrowserSPY 自 1999 年起提供服务，允许用户选择特定元素进行测试。

7. Leaks Radar

Leaks Radar 提供基本信息，并在“指纹”部分提供浏览器指纹知识。

8. Pixelscan

Pixelscan 检测浏览器指纹参数之间的不规则连接。

9. Iphey

Iphey 检查你的数字身份是否可信，提供详细信息。