browser

Browser automation — setup the bsession environment, fetch info from a website (one-shot), create scripted automations (one-shot or recurring), or debug exis...

Security Scan

The skill's behavior is broadly consistent with a browser-automation installer, but the install script performs system-modifying actions (curl|sh, Docker image builds, writing into ~/.openclaw and ~/.claude, optional open VNC) that warrant caution before installing or running.

Purpose & Capability

Name/description align with what the files and SKILL.md do: set up a bsession Docker container, run browser automation, scaffold and run scripts. Required binary (docker) is appropriate.

Instruction Scope

SKILL.md instructs the agent to run docker exec commands and read/modify files under ~/.bsession/workspace (scripts and conf), which is expected for this purpose. It also instructs running the provided install.sh; the instructions assume modifying files in the user's home and starting containers, which is within scope but has side effects the user should be aware of.

Install Mechanism

Although the skill is instruction-only, the included install.sh executes network-installed tooling (curl -LsSf https://astral.sh/uv/install.sh | sh), clones or copies project sources, builds Docker images, and starts containers — all actions that execute code from external sources and write to the host. This increases risk relative to a purely local/scripted install.

Credentials

The skill declares no environment variables or credentials. The install script writes a .env file under ~/.bsession and may set VNC_PASSWORD if provided, which is reasonable for the stated functionality. No unrelated secrets are requested.

Persistence & Privilege

The installer writes files into user directories, creates symlinks (bsession → ~/.local/bin), and copies SKILL.md/install.sh into ~/.openclaw/workspace/skills/browser and ~/.claude/skills/browser. This alters agent/skill directories and creates persistent system presence; users should expect persistent changes to their home directory and agent skill directories.

What to consider before installing

This skill appears to do what it says (install and run a browser automation container) but the installer makes persistent, privileged changes and pulls/executes external code. Before installing: 1) Inspect the bsession Dockerfile, session.py, entrypoint.sh and any image sources the repo references; 2) Avoid running the installer on a sensitive host — use an isolated VM or disposable environment; 3) Do not run the install script without reading it first: it runs curl | sh to install 'uv' and builds/starts containers; consider running with --no-start and review the built images; 4) If you need VNC, pass --vnc-password to avoid leaving an open VNC passwordless; 5) Note the script will copy files into ~/.openclaw and ~/.claude and create a symlink in ~/.local/bin — back up or review these locations if you rely on them. If you want a lower-risk audit, provide the bsession repo (or its Dockerfile/session.py) for review.

/browser skill

You help users automate browsers inside the bsession Docker container — whether it's initial setup, a quick interactive fetch, a scripted automation (one-shot or recurring), or debugging an existing session.

This is a global skill — it works from any repo. bsession is installed at ~/.bsession/, and the bsession CLI is on PATH.

Resolve paths

Before doing anything, determine how to reach bsession. Check in this order:

1. bsession on PATH → use bsession
2. ~/.bsession/bsession exists → use ~/.bsession/bsession
3. ./bsession in current directory → use ./bsession
4. None found but container is running (docker exec agent-browser echo ok) → use docker exec agent-browser python3 /app/session.py as the CLI

Similarly, resolve workspace:

1. ~/.bsession/workspace/ exists → use it
2. ./workspace/ in current directory → use it
3. Ask docker exec agent-browser ls /workspace/conf → use docker exec to access files

Use these resolved paths for all commands throughout the session.

Constants (defaults)

• BSESSION_HOME: ~/.bsession/ — where bsession source + docker-compose live
• WORKSPACE: ~/.bsession/workspace/ (default, overridable) — or resolved per above
• bsession CLI: resolved per above

Routing

Parse the user's slash command arguments:

• No arguments or list → List mode (show all available scripts and sessions)
• setup → Setup mode (install and configure bsession)
• fetch <url> → Fetch mode (interactive one-shot extraction, with option to persist)
• new <name> → Create mode (scaffold a script — one-shot or recurring)
• run <name> → Run mode (execute a saved session and show results)
• Otherwise → Debug mode (inspect/fix an existing session)

Pre-check (all modes except setup)

Before running any mode except setup, verify the container is running:

docker exec agent-browser echo ok 2>/dev/null

If this fails, tell the user to either:

• Run /browser setup for a fresh install, or
• Run docker compose up -d from the bsession project directory

---

List mode (/browser or /browser list)

Show all available scripts, their status, and what they do.

Step 1: Get session status

bsession list

Step 2: Read script docstrings

For each .py file in ~/.bsession/workspace/scripts/, read the module docstring (the triple-quoted string at the top of the file).

Step 3: Read conf files

For each .conf file in ~/.bsession/workspace/conf/, read the [env] section to show current configuration.

Step 4: Present as a table

Display a summary like:

Session       Status    Type        Description
─────────────────────────────────────────────────────────────────
uscis         running   recurring   USCIS case status monitor
price-check   stopped   one-shot    Amazon product price scraper

Available commands:
  /browser <name>           debug a session
  /browser new <name>       create a new automation
  /browser fetch <url>      quick one-shot fetch

---

Setup mode (/browser setup)

Run the install script:

bash ~/.openclaw/workspace/skills/browser/scripts/install.sh

Or with options:

bash ~/.openclaw/workspace/skills/browser/scripts/install.sh --workspace /path/to/workspace
bash ~/.openclaw/workspace/skills/browser/scripts/install.sh --vnc-password secret
bash ~/.openclaw/workspace/skills/browser/scripts/install.sh --repo https://github.com/gaxxx/bsession.git

Ask the user for custom options before running. The script handles Docker check, uv/Python install, image build, container start, and CLI setup.

---

Fetch mode (/browser fetch <url>)

One-shot: open a URL, extract information, return it. No script, no conf file, no loop.

Step 1: Find an available CDP port

docker exec agent-browser python3 -c "
import urllib.request
try:
    urllib.request.urlopen('http://localhost:9222/json/version', timeout=2)
    print('IN_USE')
except:
    print('FREE')
"

If 9222 is in use, try 9223, 9224, etc. Start a temporary Chrome on a free port:

docker exec agent-browser python3 -c "
import sys; sys.path.insert(0, '/app')
from lib.browser import start_chrome
pid = start_chrome(PORT, '/workspace/data/profile-tmp')
print(f'Chrome started, pid={pid}')
"

Step 2: Navigate and extract

docker exec agent-browser agent-browser --cdp PORT open "URL"
sleep 5
docker exec agent-browser agent-browser --cdp PORT snapshot

Handle Cloudflare if detected:

docker exec agent-browser python3 -c "
import sys; sys.path.insert(0, '/app')
from lib.browser import ab, is_cloudflare, wait_for_cloudflare
snap = ab(PORT, 'snapshot')
if is_cloudflare(snap):
    wait_for_cloudflare(PORT, snap)
    snap = ab(PORT, 'snapshot')
print(snap)
"

Step 3: Parse and interact

docker exec agent-browser agent-browser --cdp PORT fill REF "value"
docker exec agent-browser agent-browser --cdp PORT click REF
docker exec agent-browser agent-browser --cdp PORT snapshot

Step 4: Return results

Parse the relevant information and present it cleanly.

Step 5: Offer to persist

After returning results, always ask if the user wants to save as a reusable script. If yes, create a one-shot script + conf in ~/.bsession/workspace/.

Step 6: Cleanup

docker exec agent-browser python3 -c "
import sys; sys.path.insert(0, '/app')
from lib.browser import stop_chrome
stop_chrome(PORT)
"

---

Create mode (/browser new <name>)

Ask the user:

1. What URL(s) to target
2. One-shot or recurring?
3. What to detect / extract
4. Where to send results (webhook, file, etc.)
5. Env vars needed

Then scaffold ~/.bsession/workspace/conf/<name>.conf and ~/.bsession/workspace/scripts/<name>.py following the conventions in the reference section below.

---

Run mode (/browser run <name>)

1. Verify session exists: bsession show <name>
2. Run it: bsession run <name>
3. Wait and tail logs: bsession logs <name> -n 50
4. Present results. If failed, switch to debug mode.

---

Debug mode (/browser <session-id>)

1. Gather state: bsession list, bsession show <id>, read logs and script
2. Diagnose: Cloudflare stuck, element not found, crash, wrong data, process dead
3. Fix the script or conf, then bsession restart <id>

---

Script conventions

Imports:

import os, re, sys, time
sys.path.insert(0, "/app")
from lib.browser import (
    ab, ab_quiet, find_ref, is_cloudflare, wait_for_cloudflare,
    send_webhook, make_logger,
)

Config from env vars:

port = int(os.environ.get("CDP_PORT", 9222))
session_name = os.environ.get("SESSION_NAME", "<name>")
webhook_url = os.environ.get("N8N_WEBHOOK_URL", "")
check_interval = int(os.environ.get("CHECK_INTERVAL", 1800))

Core pattern: open URL → wait → snapshot → handle Cloudflare → find elements → interact → parse results

One-shot: execute and exit. Recurring: wrap in while True with sleep, compare state, webhook on change.

Reference: lib/browser.py

• ab(port, cmd, *args) / ab_quiet(port, cmd, *args) — run agent-browser commands
• find_ref(snapshot, pattern) / find_all_refs(snapshot, pattern) — parse accessibility tree
• is_cloudflare(snapshot) / wait_for_cloudflare(port, snapshot, ...) — Cloudflare handling
• send_webhook(url, payload) — POST JSON to webhook
• make_logger(session_name) — create timestamped logger