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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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
