bpilot-browser

name	bpilot-browser
description	Control headless browser sessions via the bpilot CLI. Each session runs in an isolated Selenium container with Chrome, accessible via noVNC for visual monitoring.

bpilot — Browser Pilot CLI

A CLI tool that controls browser sessions. Each session gets its own Docker container running Chrome + Selenium, with anti-bot stealth measures pre-configured.

Prerequisites

curl -fsSL http://localhost:8000/api/cli/install | bash
bpilot config set api-url http://localhost:8000
bpilot --help

The backend (browser-pilot-backend) must be running on the configured API URL. Run the install command even when bpilot already exists; older wrappers can stay in ~/.local/bin and hide newer commands such as device, lease, files, network-egress, session pause, or session unpause. If bpilot --help does not show the command you need, rerun the install command from the target Browser Pilot origin before continuing. For Agent usage, copy the real session id into every --session "<session-id>" argument.

Workflow

A typical stateless automation sequence:

# 1. Create a session.
bpilot session create --name "Task Name" --json
# Read the returned "id".

# 2. Optional: choose a managed network egress profile.
bpilot network-egress list --json
bpilot --session "<session-id>" session set-network "<egress-id-or-direct>"

# 3. Start the target session when you need the VNC port. This also recreates
# a missing container, starts an exited container, and resumes a paused one.
bpilot --session "<session-id>" session start

# 4. Navigate. The container auto-starts if it is not running.
bpilot --session "<session-id>" navigate https://example.com

# 5. Observe the page. Use --mode dom by default; switch to vision for visual cards/feeds.
bpilot --session "<session-id>" observe --mode dom --json

# 6. Interact.
bpilot --session "<session-id>" click 640 380
bpilot --session "<session-id>" click-element "a.login-btn"
bpilot --session "<session-id>" type "hello world"
bpilot --session "<session-id>" key Enter

# 7. Verify result.
bpilot --session "<session-id>" observe --mode dom --json

# 8. Screenshot for visual confirmation. Without --output, the JSON response
# contains a signed file.url and no base64 screenshot payload.
bpilot --session "<session-id>" screenshot --json
# Use --output when you also need a local copy.
bpilot --session "<session-id>" screenshot --output result.png

# 9. Inspect files captured by the browser session.
bpilot --session "<session-id>" files list --json

Commands Reference

Agent workflows should be stateless: do not use bpilot session use, shell variables, or saved active sessions. Pass the real id with --session "<session-id>" on every command that targets a browser session.

Add --json / -j to state-reading commands for machine-readable output.

Session Management

Command	Description
bpilot session list --json	List all sessions with container status
bpilot session create --name NAME --json	Create new session, returns ID
bpilot session create --name NAME --network-egress EGRESS_ID --json	Create a session bound to a managed network egress profile
bpilot --session "<session-id>" session start	Start, recreate, or resume the container for the target session
bpilot --session "<session-id>" session stop	Stop container for the target session
bpilot --session "<session-id>" session pause	Hibernate the container for the target session
bpilot --session "<session-id>" session unpause	Resume a hibernated container for the target session
bpilot --session "<session-id>" session set-network EGRESS_ID_OR_DIRECT	Switch the target session network egress
bpilot --session "<session-id>" session delete	Delete session and container; completed files are kept in Files
bpilot --session "<session-id>" session delete --delete-files	Delete session, container, and all completed files for that session

Network Egress

Command	Description
bpilot network-egress list --json	List Direct plus managed Clash/OpenVPN profiles
bpilot network-egress create --name NAME --type clash --config-file ./clash.yaml --json	Create a managed Clash profile
bpilot network-egress create --name NAME --type openvpn --config-url URL --json	Create a managed OpenVPN profile from a URL
bpilot network-egress update EGRESS_ID --config-file ./clash.yaml --json	Replace managed profile config
bpilot network-egress update EGRESS_ID --enable --json	Enable a managed profile
bpilot network-egress update EGRESS_ID --disable --json	Disable a managed profile
bpilot network-egress check EGRESS_ID --json	Check a managed profile
bpilot network-egress delete EGRESS_ID --json	Delete an unused managed profile

Read networkEgressId, networkEgressName, networkEgressType, networkEgressStatus, and networkEgressHealthError from bpilot session list --json to inspect a session's current network setting. Use direct with session set-network to clear a managed egress binding.

Browser Primitives

Command	Description
bpilot --session "<session-id>" navigate <url>	Navigate to URL
bpilot --session "<session-id>" observe --mode dom --json	Get page URL, title, visible text, and DOM interactive elements with coordinates
bpilot --session "<session-id>" observe --mode vision --json	Get YOLOv8 visual candidate boxes and groups with click-ready coordinates
bpilot --session "<session-id>" observe --mode mix --json	Use DOM first and visual fallback when DOM observe returns no elements
bpilot --session "<session-id>" click <x> <y>	Click at coordinates from observe
bpilot --session "<session-id>" click-element <selector>	Click element by CSS selector
bpilot --session "<session-id>" type <text>	Type into focused input
bpilot --session "<session-id>" key <key>	Press key: Enter, Tab, Escape, Backspace, ArrowUp, ArrowDown, etc.
bpilot --session "<session-id>" scroll <delta-y> [--delta-x N]	Scroll page; positive delta-y means down
bpilot --session "<session-id>" tabs --json	List browser tabs
bpilot --session "<session-id>" switch-tab [--handle H | --index I]	Switch tab
bpilot --session "<session-id>" page-info --json	Get current URL and title
bpilot --session "<session-id>" screenshot [--output FILE]	Store screenshot in FileStore and return a signed file URL; --output also exports a local copy
bpilot --session "<session-id>" logs [--tail N]	View container diagnostic logs

Session Files

Command	Description
bpilot --session "<session-id>" files list --json	List session files; each item includes status as downloading or completed

Configuration

Command	Description
bpilot config init	Interactive setup
bpilot config set <key> <value>	Set config (api-url, api-token)
bpilot config show	Show current config

Example: Boss直聘 QR Code Login

bpilot session create --name "Boss直聘" --json
# Read the returned id, for example: a1b2c3d4-...

bpilot --session "a1b2c3d4-..." navigate https://zhipin.com
# Navigates, container auto-starts if needed.

bpilot --session "a1b2c3d4-..." observe --json
# Find the "我要招聘" link.

bpilot --session "a1b2c3d4-..." click-element "a[href*='intent=1']"
# Clicks "我要招聘", navigates to login page.

bpilot --session "a1b2c3d4-..." observe --json
# Find the "APP扫码登录" tab.

bpilot --session "a1b2c3d4-..." click 540 66
# Click "APP扫码登录" tab using coordinates from observe.

bpilot --session "a1b2c3d4-..." observe --json
# Verify: should show QR code image element.

bpilot --session "a1b2c3d4-..." screenshot --output qr-code.png
# Save QR code screenshot for user to scan.

Important Notes

• Stateless session targeting: For Agent usage, copy the real session id into every --session "<session-id>" argument. Do not rely on session use, shell variables, or saved active_session.
• Container start/resume: Browser commands automatically start the container if it is not running. bpilot --session "<session-id>" session start is still the explicit recovery command: it creates a missing container, starts a stopped/exited container, and resumes a paused container. Use session unpause when you specifically want the resume verb.
• Anti-bot stealth: Each container runs Chrome with fingerprint spoofing, human-like click/type patterns, and timezone override (Asia/Shanghai).
• Per-call sessions: Each CLI command creates and destroys a WebDriver session to minimize detection. This adds small overhead per command but prevents anti-bot triggers.
• Observe before click: Always run bpilot --session "<session-id>" observe --json to get current element coordinates before clicking. Coordinates change when the page updates. Use --mode dom for normal links/forms/buttons, --mode vision for image/video feeds and complex visual layouts, and --mode mix when you want DOM first with a visual fallback.
• Vision labels are weak hints: Treat visual labels as candidate regions, not final semantic truth. Combine bbox position, nearby text, DOM hints, and task intent before clicking.
• Files: For Agent workflows, inspect bpilot --session "<session-id>" files list --json. Use the file item status field to distinguish downloading from completed; completed items include the backend file url.