agent-browser
A CLI that drives Chromium and answers with the page's accessibility tree —
a compact outline of what a person would see, with a short @eN reference on
every element you can act on. That is the whole reason it suits an agent: a
screenshot has to be looked at, an outline can be read, and the refs make the
next click unambiguous.
Load the guide from the CLI, not from here
agent-browser skills get core
That is the first command of any browser job. The CLI serves the guide for the
version that is actually installed, so the verbs, flags and output formats are
always the ones you have — which is why this file carries none of them.
agent-browser skills get core --full adds the complete command reference.
What is already true on this platform
The CLI and its browser are installed. Confirm it once, with
command -v agent-browser. If that fails, the CLI is not provisioned for
this run: say so in one line, record the walk as not run, and move on. Do not
search the filesystem for it, try npx, or install it — there is no
agent-browser install step to reach for, the browser is a chromium the
image already baked and points the CLI at, and a hunt for a binary that is
not there costs more than the walk it was for.
Chromium runs with --no-sandbox, and the environment already says so.
AGENT_BROWSER_ARGS=--no-sandbox is set in the image, so a command written
straight out of agent-browser skills get core works as written. You do not
add the flag and you do not remove it: the container has no usable chromium
sandbox to keep (no setuid helper, and the unprivileged user namespace the
browser falls back to is denied to it), so without the flag the browser does
not start at all. What contains it is the container — one-shot, unprivileged,
discarded with the run — not chromium's own boundary inside it.
If you ever meet an environment where that variable is NOT set, the symptom is
every browser command failing at launch, and the fix is to set it for the
session rather than per command:
export AGENT_BROWSER_ARGS=--no-sandbox
The CLI's --args "--no-sandbox" flag does the same thing for ONE invocation.
Prefer the export: a browser job is dozens of invocations against a daemon
that outlives each one, and the flag you forget is the command that fails.
Pitfalls
| Symptom |
Cause |
Fix |
Every command fails, starting with the first open, and nothing ever renders |
The browser is not launching at all. On this platform that is the sandbox: see "What is already true" above |
export AGENT_BROWSER_ARGS=--no-sandbox, once, then re-run the command unchanged. Do not start varying the command itself — the second and third guesses cost more than the export. |
An @eN ref no longer works |
Refs belong to the snapshot that produced them, and the page moved on |
Take a fresh snapshot and use its refs. |
A snapshot is empty, or an element that is plainly on the screen is "not found" — right after an open or a click that navigated |
The command returned when the document did; a single-page app paints after that, so you read the page one moment too early |
Wait for the network to settle before you snapshot. Believe the second reading, never the first — a blank page reported as a defect is a finding that costs somebody a fixing round. |
| A click never returns, and every command after it hangs or times out |
The click opened a native dialog — confirm, alert, prompt. It blocks the page, so nothing else can run until the dialog is answered |
Read the dialog section of agent-browser skills get core --full before the click that opens one, and drive it the way that reference says. Guessing at this costs tens of calls: the click that hangs is also the click you cannot undo. |
1---2name: agent-browser3description: The browser CLI a coding run drives a web page with — opening a URL, clicking through a screen, reading what actually rendered. Load before the first `agent-browser` command. For a web application this run built, load `mock-verification` first: that skill is the procedure, this one is only the tool. For an e2e test suite against a deployed system, `playwright-cli` and `aep-validation` own that instead.4---56# agent-browser78A CLI that drives Chromium and answers with the page's **accessibility tree** —9a compact outline of what a person would see, with a short `@eN` reference on10every element you can act on. That is the whole reason it suits an agent: a11screenshot has to be looked at, an outline can be read, and the refs make the12next click unambiguous.1314## Load the guide from the CLI, not from here1516```bash17agent-browser skills get core18```1920That is the first command of any browser job. The CLI serves the guide for the21version that is actually installed, so the verbs, flags and output formats are22always the ones you have — which is why this file carries none of them.23`agent-browser skills get core --full` adds the complete command reference.2425## What is already true on this platform2627- **The CLI and its browser are installed.** Confirm it once, with28 `command -v agent-browser`. If that fails, the CLI is not provisioned for29 this run: say so in one line, record the walk as not run, and move on. Do not30 search the filesystem for it, try `npx`, or install it — there is no31 `agent-browser install` step to reach for, the browser is a chromium the32 image already baked and points the CLI at, and a hunt for a binary that is33 not there costs more than the walk it was for.34- **Chromium runs with `--no-sandbox`, and the environment already says so.**35 `AGENT_BROWSER_ARGS=--no-sandbox` is set in the image, so a command written36 straight out of `agent-browser skills get core` works as written. You do not37 add the flag and you do not remove it: the container has no usable chromium38 sandbox to keep (no setuid helper, and the unprivileged user namespace the39 browser falls back to is denied to it), so without the flag the browser does40 not start at all. What contains it is the container — one-shot, unprivileged,41 discarded with the run — not chromium's own boundary inside it.4243 If you ever meet an environment where that variable is NOT set, the symptom is44 every browser command failing at launch, and the fix is to set it for the45 session rather than per command:4647 ```bash48 export AGENT_BROWSER_ARGS=--no-sandbox49 ```5051 The CLI's `--args "--no-sandbox"` flag does the same thing for ONE invocation.52 Prefer the export: a browser job is dozens of invocations against a daemon53 that outlives each one, and the flag you forget is the command that fails.5455## Pitfalls5657| Symptom | Cause | Fix |58|---|---|---|59| **Every** command fails, starting with the first `open`, and nothing ever renders | The browser is not launching at all. On this platform that is the sandbox: see "What is already true" above | `export AGENT_BROWSER_ARGS=--no-sandbox`, once, then re-run the command unchanged. Do not start varying the command itself — the second and third guesses cost more than the export. |60| An `@eN` ref no longer works | Refs belong to the snapshot that produced them, and the page moved on | Take a fresh snapshot and use its refs. |61| A snapshot is empty, or an element that is plainly on the screen is "not found" — right after an `open` or a click that navigated | The command returned when the document did; a single-page app paints after that, so you read the page one moment too early | Wait for the network to settle before you snapshot. Believe the second reading, never the first — a blank page reported as a defect is a finding that costs somebody a fixing round. |62| A click never returns, and every command after it hangs or times out | The click opened a **native** dialog — `confirm`, `alert`, `prompt`. It blocks the page, so nothing else can run until the dialog is answered | Read the dialog section of `agent-browser skills get core --full` **before** the click that opens one, and drive it the way that reference says. Guessing at this costs tens of calls: the click that hangs is also the click you cannot undo. |
wso2