Browser Harness

@blopai/browser-harness gives agents a controlled way to observe and operate real browsers. It provides the blop-browser CLI, a TypeScript tool API, persistent browser sessions, screenshots, screencast frames, and reusable Playwright or Camoufox containers.

The harness owns browser control. It does not own the Blop agent loop, test DSL, model calls, reporters, or platform uploads.

Choose an integration

Use the smallest interface that matches your host:

Integration	Use it when
blop-browser CLI	An agent or script needs a persistent browser across shell calls
TypeScript API	Your application embeds controlled tools in its own agent loop
Container sessions	Browsers must run in reusable Docker infrastructure

Install the CLI

The package requires Node.js 22 or newer. Install it globally, then check the available browsers and saved configuration:

npm install --global @blopai/browser-harness
blop-browser doctor --json

If Chromium isn’t installed, install the Playwright browser:

npx playwright install chromium

Run a browser workflow

The concise commands cover the common observe, act, and verify loop:

blop-browser open https://example.com
blop-browser snapshot
blop-browser expect-text "Example Domain"
blop-browser close

snapshot returns semantic references such as e1. Use those opaque references for later actions instead of inventing or editing them:

blop-browser snapshot
blop-browser click e1

Install the agent skill

The bundled skill teaches supported coding agents how to use the CLI safely and verify outcomes. Install it with the cross-agent skill installer:

npx skills add blop-oss/browser-harness --skill browser-harness

You can also inspect or install the skill through the CLI:

blop-browser skill show
blop-browser skill install --target agents --scope project

Design boundaries

The harness exposes explicit tools instead of arbitrary browser scripting. It has no shell tool, page.evaluate tool, or unrestricted CDP command surface. Actions are bounded, validated, and recorded so the host can retain evidence.

Read the security model before exposing a browser session across process or network boundaries.

Next steps

Continue with CLI and sessions for agent-driven workflows, or use the TypeScript API to embed the harness in your own runtime.