# Browser Harness

> Install Browser Harness and drive a real browser from an agent, script or your own agent loop.

Install [Browser Harness](/reference/glossary/#browser-harness) and drive a real browser through bounded, recorded tools. Browser checks use it under the hood; use it directly when another agent or application needs browser control without the `blop` runner.

Browser Harness (`@blopai/browser-harness`) owns browser actions, sessions, screenshots, screencast frames and browser containers. It does not own browser checks, the agent loop, model calls, reporters or uploads to Blop Cloud; those belong to [`blop test`](/checks/).

## Choose an integration

| Integration | Use it when |
| --- | --- |
| [`blop-browser` CLI](/harness/cli/) | An agent or script needs one browser that persists across shell calls |
| [TypeScript API](/harness/library/) | Your application runs its own agent loop and embeds the tools |
| [Container sessions](/harness/containers/) | Browsers must run in reusable Docker containers |

## Prerequisites

- Node.js 22 or newer.
- Chrome or Chromium. If `doctor` finds neither, run `npx playwright install chromium`.

## Drive a browser from the CLI

1. Install the CLI:

   ```bash
   npm install --global @blopai/browser-harness
   ```

2. Check the browsers it can use and the saved configuration:

   ```bash
   blop-browser doctor --json
   ```

3. Open a page, read it, assert on it and close it:

   ```bash
   blop-browser open https://example.com
   blop-browser snapshot
   blop-browser expect-text "Learn more"
   blop-browser close
   ```

   `snapshot` lists controls with opaque references such as `e13`. Pass a reference unchanged to later actions, for example `blop-browser click e13`. Never invent or edit one.

4. Optional: install the agent skill, which teaches coding agents to use the CLI and verify outcomes:

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

   Or install it from the CLI into the project's `.agents/skills/`:

   ```bash
   blop-browser skill install --target agents --scope project
   ```

## Check it worked

`expect-text` exits `0` and prints `Found visible text: Learn more`. A missing text exits `1`.

## Design boundaries

Browser Harness exposes explicit tools only: no shell, no arbitrary JavaScript and no raw CDP commands. Every action is validated, bounded and recorded so the host keeps evidence. Read the [security model](/harness/security/) before you share a session across a process or network boundary.

## Next

- [CLI and sessions](/harness/cli/)
- [TypeScript API](/harness/library/)
- [Security model](/harness/security/)