agent browser - Moses Yebei

The Problem

AI agents need a reliable way to control a headless browser without writing custom Selenium or Playwright scripts. Existing CLI tools are either heavyweight Node‑only solutions or require separate language bindings, making integration noisy and slow for agents that already run in a Rust or Node environment.

What This Does

agent-browser ships a native Rust binary (cli/src/main.rs) that drives Chromium via Playwright under the hood, falling back to a JavaScript implementation when the native build isn’t available. The CLI is exposed through the bin/agent-browser wrapper, which forwards commands to the Rust binary. Core browser actions live in src/browser.ts (high‑cognitive‑load, 1.6 k lines) and are orchestrated by src/actions.ts, while the low‑level protocol handling resides in src/protocol.ts.

The documentation site (docs/) is a Next.js app that renders the README‑style help pages, reusing UI components such as docs/src/components/code-block.tsx. The Docker configuration (docker/Dockerfile.build) builds a reproducible image that bundles both the Rust binary and the Node runtime.

How It Is Wired

Execution starts at cli/src/main.rs – the compiled entry point for the agent-browser command. main.rs parses CLI flags (cli/src/flags.rs) and dispatches to sub‑commands defined in cli/src/commands.rs. Each command creates a Browser instance from src/browser.ts, which internally:

Calls install() from cli/src/install.rs (deep nesting, max indentation depth 8) to ensure Chromium is present.
Opens a Playwright session via the protocol module (src/protocol.ts).
Executes the requested action (click, type, snapshot, etc.) by invoking functions exported from src/actions.ts.

src/actions.ts imports src/browser.ts (5 inbound edges) and src/protocol.ts (3 edges), making it a central hub; changes here ripple across the CLI. The daemon module (src/daemon.ts) runs a background server for streaming snapshots but has no inbound imports, indicating it is only invoked explicitly.

The import graph contains 32 internal modules with 17 edges and no circular dependencies. The most‑connected module is src/browser (Ca 5, Ce 2, instability 0.29), followed by src/actions (Ca 3, Ce 3, instability 0.5). The docs UI components are isolated, each with a single import edge.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/agent-browser
cd agent-browser

# Install dependencies (pnpm) and build the Rust binary
pnpm install
pnpm build:native   # requires rustup (see https://rustup.rs)

# Install Chromium for the CLI
pnpm link --global   # makes `agent-browser` globally available
agent-browser install   # downloads the browser binary

# Example command sequence
agent-browser open https://example.com
agent-browser snapshot
agent-browser click @e2
agent-browser close

The agent-browser install step runs the code in cli/src/install.rs. All runtime configuration is driven by command‑line flags; no external config files are required.

Real‑World Use

A microservice that generates automated UI reports can invoke the CLI from a Node worker:

const { execSync } = require('child_process');
execSync('agent-browser open https://myapp.internal');
execSync('agent-browser snapshot > report.json');

The worker receives a JSON accessibility tree, enabling an LLM to reason about page structure without parsing raw HTML.

Code Health & Issues

HIGH – Pin GitHub Actions to commit SHA (.github/workflows/ci.yml).
HIGH – Upgrade vulnerable next@16.1.1 (CVE‑2026‑44575).
MEDIUM – Declare least‑privilege GITHUB_TOKEN permissions.
MEDIUM – Enable Dependabot/Renovate for automatic updates.
MEDIUM – Pin Docker base image by digest (docker/Dockerfile.build).
MEDIUM – Add dependency‑vulnerability scan to CI.
MEDIUM – Set persist-credentials: false on checkout step.
MEDIUM – Add non‑root USER in Dockerfile.
MEDIUM – Review/disable postinstall script in package.json.
LOW – Set timeout-minutes on CI jobs.

Additional static findings: three oversized files (src/actions.ts, src/browser.ts, src/protocol.ts) each exceed 1 600 lines, and deep nesting appears in cli/src/commands.rs, cli/src/main.rs, and cli/src/install.rs. Repeated UI fragments across several docs pages suggest a DRY improvement.

The Bottom Line

agent-browser delivers a fast, Rust‑backed CLI for headless browser control with a Node fallback, suitable for AI‑driven automation pipelines. The codebase functions but suffers from large, deeply nested modules and several security‑focused hygiene gaps that should be addressed before production use. Teams comfortable with Rust and Node can adopt it quickly, provided they apply the listed hardening fixes.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

62 files

TSX14
TypeScript13
Rust6
YAML4
JSON4
Markdown3

ReactNext.jsDocker

Module dependencies

The 10 most depended-upon modules of 32, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_src_browser["browser"] n1_src_actions["actions"] n2_src_protocol["protocol"] n3_src_types["types"] n4_src_stream_server["stream-server"] n5_s_src_components_copy_button["copy-button"] n6_src_snapshot["snapshot"] n7_src_daemon["daemon"] n8_cs_src_components_code_block["code-block"] n9_src_actions_test["actions.test"] n8_cs_src_components_code_block --> n5_s_src_components_copy_button n9_src_actions_test --> n1_src_actions n1_src_actions --> n0_src_browser n1_src_actions --> n3_src_types n1_src_actions --> n2_src_protocol n0_src_browser --> n3_src_types n0_src_browser --> n6_src_snapshot n7_src_daemon --> n0_src_browser n7_src_daemon --> n2_src_protocol n7_src_daemon --> n1_src_actions n7_src_daemon --> n4_src_stream_server n2_src_protocol --> n3_src_types n4_src_stream_server --> n0_src_browser n4_src_stream_server --> n1_src_actions

Dependencies

6 of 24 declared dependencies are a major version behind. Resolved 22 of 24 against the registry.

Package	Declared	Latest	Behind
`@types/node`	^20	26.2.0	6 major
`typescript`	^5	7.0.2	2 major
`lint-staged`	^15.2.11	17.3.0	2 major
`shiki`	^3.21.0	4.4.3	1 major
`eslint`	^9	10.8.1	1 major
`zod`	^3.22.4	4.4.3	1 major

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium7

low1

Pin third-party GitHub Actions to a commit SHAhigh2 occurrences

.github/workflows

pnpm/action-setup@v4, dtolnay/rust-toolchain@stable

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Upgrade the pinned dependency carrying a published advisoryhigh31 occurrences

next@16.1.1 CVE-2026-44575 (high) +30 more

The pinned version is the one that installs, so a published advisory against it describes this deployment rather than a hypothetical one, and the advisory is also a public description of how to exploit it.

Fix: Upgrade to the fixed version named in the advisory, then commit the lockfile.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/ci.yml

1 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

3 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

docker/Dockerfile.build

rust:1.85-bookworm

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

docker/Dockerfile.build

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Review the install lifecycle script and disable scripts in CImedium

package.json

postinstall

Install scripts are the execution vector for every npm compromise from event-stream onward, and a postinstall that fetches a binary makes the build depend on a URL nobody reviews.

Fix: Move the work into an explicit build step, or set ignore-scripts in CI and run it by name.

Set timeout-minutes on the workflow jobslow

.github/workflows/ci.yml

1 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.