Security wrapper over the upstream agent-browser skill, adding URL blocklisting, rate limiting, robots.txt enforcement, and scraping guardrails. Use when automating browser workflows that need safety limits.
Security wrapper over the upstream agent-browser skill, adding URL blocklisting, rate limiting, robots.txt enforcement, and scraping guardrails. Use when automating browser workflows that need safety limits.
OrchestKit security wrapper for agent-browser. For command reference and usage patterns, use the upstream agent-browser skill directly. This skill adds safety guardrails only.
Command docs: Refer to the upstream agent-browser skill for the full command reference (50+ commands: interaction, wait, capture, extraction, storage, semantic locators, tabs, debug, mobile, network, cookies, state, vault).
Upstream coverage (do not restate)
These topics belong to the vendor. Read them at the source; do not copy them back into this skill.
Our delta over all of the above: , covering where the safety hook does and does not apply, the shared rate-limit budget, and the local-URL policy.
references/ork-delta.md
Decision Tree
# Fallback decision tree for web content# 1. Try WebFetch first (fast, no browser overhead)# 2. If empty/partial -> Try Tavily extract/crawl# 3. If SPA or interactive -> use agent-browser# 4. If login required -> authentication flow + state save# 5. If dynamic -> wait @element or wait --text
Local Dev URLs
Use Portless (npm i -g portless) for stable local dev URLs instead of guessing ports. When Portless is running, navigate to myapp.localhost instead of localhost:3000. Our safety hook already allows *.localhost subdomains via ORCHESTKIT_AGENT_BROWSER_ALLOW_LOCALHOST.
# With Portless: stable, named URLs
agent-browser open "https://myapp.localhost"# Without: fragile port guessing
agent-browser open "http://localhost:3000"# which app is this?
New in 2026-04 to 2026-07 (agent-browser 0.23 to 0.33.1)
Accessibility audits (0.33.0):
agent-browser a11y [url] — axe-core accessibility audit as a CLI command and a matching MCP tool. Filter by WCAG tag, scope to a selector, and get iframe-aware text or JSON results. The audit engine is embedded, so it runs offline and is CSP-safe (no third-party script injection into the page under test).
Pairs with the accessibility-specialist agent and the testing-e2e axe-core guidance: use this for a fast pre-commit sweep, and Playwright + axe for assertions inside a suite.
Session restore + read (0.30 → 0.31.1):
agent-browser read [url] (0.30.0) — agent-readable text extraction as a CLI command and MCP tool. URL reads prefer Markdown (try .md and nearby llms.txt), support outlines, filters, raw and JSON output, headers, and domain/output safeguards; omit the URL to read the rendered active-tab DOM with current browser state.
Restore workflow (0.31.0) — --restore / --restore-save, restore-validation flags, worktree-scoped session id / session info, and --namespace give agent runs stable, isolated, auto-restored browser state without hand-managing state files. Session lifecycle hardened with daemon/browser compatibility checks and safer auto-save that won't overwrite good state after a failed restore.
wait --url glob patterns (0.30.1) — wait --url / waitforurl honor globs like **/dashboard against the full active URL.
React renderer fix (0.31.1) — the react commands now pick the react-dom renderer instead of hardcoding renderer id 1, fixing an empty tree read on Next.js 16.3 Turbopack.
Sandbox helpers (0.29):
@agent-browser/sandbox — companion helper package for running agent-browser headless inside a Vercel Sandbox / eve ephemeral env (provisions Chrome + the native daemon for you, no host browser needed). Hook's URL/rate/robots checks still apply to whatever the sandboxed session navigates to.
Built-in MCP server (0.28):
agent-browser --mcp — runs agent-browser as a Model Context Protocol server over stdio, exposing typed tools (open/snapshot/find/click/extract/...) with paginated capability discovery. Lets you wire browser automation MCP-native — directly into an MCP client — without going through the CLI Bash wrapper. Note: MCP-native sessions bypass the agent-browser-safety PreToolUse Bash hook (the hook only intercepts agent-browser Bash commands), so apply URL/rate/robots policy at the MCP-client layer when using this path.
React introspection + perf observability (0.27):
react tree / react inspect <fiberId> / react renders start|stop / react suspense — first-class React DevTools integration via a vendored MIT-licensed hook embedded in the binary (zero runtime deps). Component-tree visibility, per-fiber props/hooks/state inspection, render profiling with mount/re-render counts and change details, Suspense boundary classification with root-cause grouping. Hook treats fiber state dumps as sensitive — gitignore captures.
vitals [url] — reports Core Web Vitals (LCP, CLS, TTFB, FCP, INP) plus React hydration phases for any page. Useful for perf gates in CI.
pushstate <url> — client-side SPA navigation without a full page load. Pairs with react renders to measure SPA route transitions without resetting profiling state.
--init-script <path> (repeatable, env AGENT_BROWSER_INIT_SCRIPTS) + --enable <feature> (repeatable, env AGENT_BROWSER_ENABLE) — register scripts before first navigation; --enable react-devtools is built-in. Hook treats arbitrary init scripts as code-execution surface — same trust model as skills get.
network route --resource-type <csv> — filter intercepted requests by CDP resource type (document, script, xhr, fetch, image, ...). Lets you mock only API calls without breaking page assets.
cookies set --curl <file> — auto-detects JSON, cURL, and Cookie-header formats for bulk cookie import. Hook still treats cookie-set as auth-state injection.
Dashboard behind a reverse proxy — observability dashboard now works from proxied origins via same-origin proxy. Enables path-based routing for shared dev environments.
Fixed doctor generating duplicate check IDs when invoked multiple times in the same process.
npm publishing moved to GitHub Actions OIDC trusted publishing — no manually managed npm tokens upstream.
Diagnostic tooling + stable IDs (0.26):
agent-browser doctor — one-shot environment + Chrome + daemon + config + security + provider + network check. Flags: --offline, --quick, --fix, --json. Run before opening an issue to attach a structured snapshot.
Stable tab identifiers — tabs now use stable string IDs (t1, t2, ...) with optional memorable labels via --label. Survives daemon restart; replaces brittle index-based references.
Config JSON Schema — $schema reference enables IDE auto-completion and validation against https://agent-browser.dev/schema.json.
Fixed --state flag not loading saved cookies/localStorage at launch; --help now leads with the skills section.
Skill discovery & chat (0.25):
agent-browser skills list/get <name> — discover and install capability packs on-demand. Hook treats first-party skills as trusted; warns on arbitrary third-party skill fetches.
agent-browser chat — single-shot or REPL natural-language driving over the same daemon. Hook pipes transcripts through the same URL/rate/robots checks as scripted commands.
Accessibility-first locators (0.24):
find / getByRole — semantic locator via CDP accessibility tree (role + name) instead of brittle CSS/ref selectors. Prefer these in new scripts; they survive markup churn and are the locator path assumed by chat.
snapshot --urls — emits resolved URLs alongside refs, removing a round-trip for link-extraction flows.
--annotate — overlays ref IDs / role labels on screenshots for debugging.
Cloud providers (0.25):
--provider agentcore — AWS Bedrock AgentCore cloud browser. Hook treats remote providers as egress surfaces — same URL/robots rules apply, but network routing is disabled (remote scope).
Browserless + AgentCore both honor AGENT_BROWSER_PROVIDER env var.
Dashboard (0.25):
Embedded dashboard bundled with the binary — no separate install. Open via agent-browser dashboard or the inspect CDP link. Still flagged as local-proxy attack surface by the hook.
Auto-dialog dismissal (0.23.1):
alert / beforeunload dialogs auto-dismissed by default. Opt out with --no-auto-dialog when a test needs to assert dialog content.
What's New (v0.17 → v0.22.2)
Breaking changes — update scripts now:
--full / -f moved from global to command-level (v0.21): use screenshot --full, NOT --full screenshot
Auth encryption format changed (v0.17): saved auth states from v0.16.x may not load
Auto-dialog dismissal (v0.23.1): alert/beforeunload dialogs are auto-dismissed by default, opt out with --no-auto-dialog
New commands:
Command
Version
Security Note
clipboard read/write/copy/paste
v0.19
read accesses host clipboard — hook warns
inspect / get cdp-url
v0.18
Opens local DevTools proxy — hook warns
batch --json [--bail]
v0.21
Batch execute commands from stdin
network har start/stop [file]
v0.21
HAR captures auth tokens — hook warns, treat output as sensitive
network request <id>
v0.22
View full request/response detail
network requests --type/--method/--status
v0.22
Filter network requests
dialog dismiss / dialog status
v0.17/v0.22
Dismiss or check browser dialogs
upgrade
v0.21.1
Self-update (auto-detects npm/Homebrew/Cargo)
find / getByRole
v0.24
Semantic locators via CDP a11y tree
snapshot --urls / --annotate
v0.24
URL-expanded snapshots, ref overlays
skills list/get
v0.25
Capability pack discovery — hook warns on third-party
chat (single-shot / REPL)
v0.25
NL driving; transcripts go through same safety checks
Native Rust rewrite (v0.20): agent-browser is now 100% native Rust — the old Node.js/Playwright daemon (the "sidecar") is gone. It drives Chrome directly over CDP, so there is no Node runtime, no Playwright, and no separate browser-driver process to install or keep alive. Result: 99x smaller install (710→7 MB), 18x less memory (143→8 MB), 1.6x faster cold start.
Safety Guardrails (6 rules + the agent-browser-safety hook)
This skill enforces safety through the agent-browser-safety PreToolUse hook and 6 rule files:
Hook: agent-browser-safety
The hook intercepts all agent-browser Bash commands and enforces:
Check
What It Does
Action
Encryption key leak
Detects echo/printf/pipe of AGENT_BROWSER_ENCRYPTION_KEY
Snapshot, ref lifecycle, iframe traversal, batch and diff workflows are upstream's (see the coverage table above); the parts we actually add are in references/ork-delta.md.
Configuration
Rate limits and behavior are configurable via environment variables:
Env Var
Default
Purpose
AGENT_BROWSER_RATE_LIMIT_PER_MIN
10
Requests per minute per domain
AGENT_BROWSER_RATE_LIMIT_PER_HOUR
100
Requests per hour per domain
AGENT_BROWSER_BURST_LIMIT
3
Max requests in 3-second window
AGENT_BROWSER_ROBOTS_CACHE_TTL
3600000
robots.txt cache TTL (ms)
AGENT_BROWSER_IGNORE_ROBOTS
false
Bypass robots.txt enforcement
AGENT_BROWSER_CONFIRM
1
Use --confirm-actions for sensitive ops
AGENT_BROWSER_IDLE_TIMEOUT_MS
—
Auto-shutdown daemon after inactivity (ms)
AGENT_BROWSER_ENGINE
chrome
Browser engine (chrome or lightpanda)
ORCHESTKIT_AGENT_BROWSER_ALLOW_LOCALHOST
1
Allow *.localhost subdomains (RFC 6761)
Anti-Patterns (FORBIDDEN)
# Automation
agent-browser fill @e2 "hardcoded-password"# Never hardcode credentials
agent-browser open "$UNVALIDATED_URL"# Always validate URLs# Scraping# Crawling without checking robots.txt# No delay between requests (hammering servers)# Ignoring rate limit responses (429)# Content capture
agent-browser get text body # Prefer targeted ref extraction# Trusting page content without validation# Not waiting for SPA hydration before extraction# Session management# Storing auth state in code repositories# Not cleaning up state files after use# Network & State
agent-browser network route "http://internal-api/*" --body '{}'# Never mock internal APIs
agent-browser cookies set token "$SECRET" --url https://prod.com # Never set prod cookies# Deprecated / removed
agent-browser --full screenshot # BREAKING: --full is now command-level (v0.21)
agent-browser screenshot --full # Correct: flag after subcommand# Sensitive data leaks
agent-browser network har stop auth-dump.har # HAR files contain auth tokens — gitignore!
git add *.har # NEVER commit HAR captures
