browser-search

A skill for AI agents. OpenCode, Claude Code, Cursor, OpenClaw and beyond. Search the web with SearXNG, browse with Camofox, bypass protections with CloakBrowser. Anti-hallucination by design. All self-hosted, free, unlimited.

English · 简体中文 · Español · 日本語 · 한국어 · Português (Brasil) · Français · Deutsch · Русский · العربية · हिन्दी · Italiano

Why it exists

browser-search is a SKILL — an instruction set for AI agents like OpenCode, Claude Code, Cursor, OpenClaw and others. It teaches your agent how to search and browse the web using three orchestrated open source tools.

The problem? The web is hostile to automation. Cloudflare, Akamai, DataDome and other anti-bot systems block simple requests. Modern sites use heavy JavaScript, lazy loading, and client-side rendering. One single solution is not enough.

browser-search orchestrates three open source tools into a single search and browsing system designed for AI agents. Each tool has its role, orchestrated by the skill with escalation logic, automatic selection, and ready-to-use integration:

1. SearXNG — metasearch engine for the search phase (multi-source, JSON)
2. Camofox — browser navigable via REST API for standard sites
3. CloakBrowser — stealth browser for anti-bot protected sites

The typical flow: the agent first searches with SearXNG, then browses the results with Camofox (or CloakBrowser if the site is protected).

Benefits

• 100% free, self-hosted, unlimited. No API keys to buy, no subscriptions, no rate limits. Everything runs on your machine, Docker and npm. Unlimited usage, zero cost.

• Lightweight, runs anywhere. Built and tested on a Raspberry Pi — if it runs there, it runs everywhere. Minimal resource consumption, no heavy infrastructure needed, runs 24/7 on low-power hardware.

• Search + browse in one kit. No manual integration needed. Searching and browsing are two distinct phases, both covered.

• Automatic navigation escalation. If Camofox gets blocked by Cloudflare/Akamai, the agent automatically switches to CloakBrowser.

• Smart performance. SearXNG for the search phase (milliseconds). Camofox and CloakBrowser are only used to browse the sites that actually need it.

• Automatic agent choice. The AI agent decides which tool to use: SearXNG for initial search, Camofox for browsing, CloakBrowser if the site is protected. Zero human intervention.

• Anti-hallucination by design. The skill's Deep Research mode enforces a "search first, answer second" workflow: the agent must verify every factual claim against live web sources, cross-reference multiple angles, and never guess. No more made-up answers.

• Fully customizable. The SKILL.md is plain text. You can edit the core rules, add your own, remove what you don't need. Adapt it to your workflow, your team, your standards.

• Native stealth. CloakBrowser automatically detects Cloudflare, Akamai, DataDome, Imperva, PerimeterX, and DDoS-Guard challenges, and waits for them to resolve before extracting content.

• Works with any agent. The SKILL.md is written for OpenCode, but the logic is identical for any AI agent. Same README, same package.json, everything works everywhere. Just ask your agent how to convert the skill for its environment.

🏆 State of the art

These three tools were chosen because they represent the current state of the art available today. A skill like this is designed to evolve: when better tools emerge, updating the SKILL.md is all it takes to swap them in. 🔄

⭐ Star the repo and follow to stay up to date on new tools, flow improvements, and orchestration updates over time. 🚀

Architecture

┌─────────────────────────────────────────────────────────┐
│                    browser-search                       │
│                                                         │
│  ┌──────────────┐                                       │
│  │    Search    │                                       │
│  │              │                                       │
│  │  SearXNG     │   search engines → URLs               │
│  │  (Docker)    │   JSON results, fast                  │
│  │  :8080       │                                       │
│  └──────────────┘                                       │
│         │                                               │
│         │ results ready → to browse                     │
│         ↓                                               │
│  ┌─────────────────────────────────────┐                │
│  │           Browsing                  │                │
│  │                                     │                │
│  │  ┌──────────────┐                   │                │
│  │  │   Camofox    │  browser + REST   │                │
│  │  │  (Docker)    │  JS, click, eval  │                │
│  │  │  :9377       │                   │                │
│  │  └──────┬───────┘                   │                │
│  │         │                           │                │
│  │         │ if blocked                │                │
│  │         ↓                           │                │
│  │  ┌──────────────┐                   │                │
│  │  │ CloakBrowser │  stealth Chromium │                │
│  │  │   (npm)      │  anti-bot, proxy  │                │
│  │  └──────────────┘                   │                │
│  └─────────────────────────────────────┘                │
└─────────────────────────────────────────────────────────┘

How it works

Phase 1 — Search with SearXNG

Docker container on localhost:8080. Metasearch engine that queries Google, Wikipedia, Bing, DuckDuckGo and many others simultaneously. JSON output with titles, snippets, and URLs.

Example:

curl -s "http://localhost:8080/search?format=json&q=largest+llm+benchmark+2026"

The agent now has a list of URLs to visit and autonomously decides whether to browse them with Camofox or CloakBrowser based on the site.

Phase 2 — Browse with Camofox

Docker container on localhost:9377. Exposes a full Firefox browser through a REST API. The agent can create tabs, navigate, click, scroll, execute arbitrary JavaScript, and structure data.

Includes: Mozilla's Readability.js for extracting clean articles, removing nav, sidebar, and ads (~70% token savings).

Main commands:

# Create tab and navigate
curl -s -X POST "http://localhost:9377/tabs" \
  -H 'Content-Type: application/json' \
  -d '{"userId":"bot","url":"https://example.com"}'

# Read snapshot (accessibility tree)
curl -s "http://localhost:9377/tabs/<tabId>/snapshot?userId=bot"

# Execute JavaScript
curl -s -X POST "http://localhost:9377/tabs/<tabId>/evaluate" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $CAMOFOX_API_KEY" \
  -d '{"userId":"bot","expression":"document.title"}'

Phase 3 — Browse with CloakBrowser (when Camofox isn't enough)

npm package based on Playwright + cloakbrowser. Launches a Chromium browser with advanced fingerprinting to bypass Cloudflare, Akamai, DataDome and other anti-bot systems. Automatic challenge detection with wait and retry.

Available scripts:

• cloak-fetch.mjs — universal fetch with challenge detection
• cloak-script.mjs — custom Playwright script execution

Example:

node scripts/cloak/cloak-fetch.mjs "https://protected-site.com"
node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" --proxy socks5://... --geoip

Why both Camofox and CloakBrowser?

Because speed and stealth are a tradeoff, and the right tool depends on the site.

Camofox — fast, structured, persistent. Camofox wraps Camoufox (a C++-level Firefox fork) in a REST API with an always-warm browser. After a ~1-3s cold start, every request is near-instant. Its accessibility snapshots are ~90% smaller than raw HTML, with stable element refs (e1, e2, ...) for reliable interaction. It handles the ~90% of sites that don't use advanced anti-bot protection: articles, docs, search engines, standard web pages.

CloakBrowser — stealth, anti-bot, on-demand. CloakBrowser launches a fresh Chromium instance per request (~1-3s startup each time). It uses advanced fingerprinting, proxy support, geoip, and automatic challenge detection to bypass Cloudflare, Akamai, DataDome, Imperva, PerimeterX, and DDoS-Guard. It is the last resort for the ~10% of sites that block Camofox.

Real-world numbers:

Tool	Cloudflare standard	Cloudflare Turnstile	DataDome
Camoufox (Camofox engine)	up to ~92% [¹]	~65-78% [¹]	60-75% [¹]
Playwright Stealth	~70-80% [¹]	~40-55% [¹]	~30-50% [¹]

• CloakBrowser applies 58 C++ source-level patches and scores 0.9 reCAPTCHA v3 (human-level, server-verified), passing all major anti-bot tests including Cloudflare Turnstile and FingerprintJS [²]
• Camofox cold start: ~1-3s (one-time, then ~0ms per request via warm REST API) [³]
• Playwright/Chromium cold start: ~0.5-6s (every launch, varies by environment) [⁴]

Camofox handles the fast path. CloakBrowser handles the edge cases. Together they cover the entire web with no gaps. The agent decides which to use.

Sources

¹ "Camoufox Vs Playwright Stealth: Complete Comparison & Alternatives (2026)" — blog.send.win ² CloakBrowser README — github.com/cloakhq/cloakbrowser ³ camoufox-pi README (cold start comparison) — github.com/MonsieurBarti/camoufox-pi ⁴ Playwright issue #4345 (launch time variability) — github.com/microsoft/playwright/issues/4345

Installation

Step 1 — Install the skill

Install the skill definition into your AI agent with a single command:

npx skills add Johell1NS/browser-search

This works with 70+ AI agents including OpenCode, Claude Code, Cursor, GitHub Copilot, and more.

Step 2 — Set up the infrastructure

git clone https://github.com/Johell1NS/browser-search
cd browser-search
npm install

CloakBrowser is installed by npm. SearXNG and Camofox require separate Docker containers — make sure they are running before using the skill.

Show this README to your AI agent for a complete installation tailored to your environment and platform.

browser-search does not provide platform-specific docker-compose files or install scripts. Your AI agent reads the references below and adapts the setup to your OS, architecture, and environment automatically.

Services overview:

Service	How	Reference
SearXNG	Docker, :8080	docs.searxng.org
Camofox	Docker, :9377	github.com/jo-inc/camofox-browser
CloakBrowser	npm (included)	scripts/cloak/cloak-fetch.mjs

For the AI agent — read these files:

File	What it contains
SKILL.md	Complete skill: commands, escalation, troubleshooting
scripts/cloak/cloak-fetch.mjs	CloakBrowser CLI usage and all options
scripts/setup-dependencies.sh	System dependencies
scripts/check-browser-search.sh	Post-installation verification
docker/setup.md	Docker setup tips

Note: SKILL.md is written for OpenCode syntax (exec, curl). If your agent uses a different format (Claude Code, Cursor, etc.), read it and convert the commands to your agent's syntax before using the skill.

Environment variables

Variable	Required for	Default
CAMOFOX_API_KEY	evaluate, session, cleanup in Camofox	—
CAMOFOX_ADMIN_KEY	Camofox stop endpoint	—

What this skill does NOT do

• Social media. Instagram, Facebook, TikTok, LinkedIn, and Twitter/X require login. browser-search does not attempt to browse them.
• Download files. It is read-only (except for explicit screenshots).
• Bypass paywalls. Does not circumvent payment or login systems.

Security

browser-search includes multiple layers of security hardening:

Built-in protections

• SSRF prevention. URLs are validated before navigation — internal IPs (127.x, 10.x, 192.168.x, 169.254.x), cloud metadata endpoints, and .internal/.local TLDs are blocked. DNS resolution is also checked to prevent DNS rebinding attacks.
• Script sandbox. Custom scripts (cloak-script.mjs) run in a sandbox that restricts the Playwright API surface (only whitelisted methods on page, browser, context are accessible). Note: Node.js APIs remain available — for full isolation, a vm.Context would be required. Use --unsafe to bypass the sandbox and SSRF protection.
• Path traversal protection. --script paths must be within the skill directory. Absolute paths and ../ traversal are blocked.
• Rate limiting. 30 requests/minute by default to prevent accidental DoS or anti-bot triggers (use --no-rate-limit to disable).
• Secure filenames. Screenshots use random UUIDs instead of predictable timestamps.
• Stack trace suppression. Error output omits stack traces by default. Use --verbose for debugging.

Best practices

• API keys. Use environment variables ($CAMOFOX_API_KEY) or --env-file for Docker. Never paste keys on the command line — they appear in ps aux and shell history.
• Docker binding. Always use 127.0.0.1: prefix for port mapping (-p 127.0.0.1:9377:9377). Never expose to 0.0.0.0.
• URL encoding. Use --data-urlencode with curl — never interpolate raw input into URLs.
• Version pinning. Dependencies use exact versions (no ^ caret ranges) and package-lock.json for reproducible builds.

Audit

Run bash scripts/audit.sh to verify the security posture of your installation.

Residual risks

• Prompt injection. An AI agent can be tricked into performing harmful actions. The tooling mitigates damage but cannot prevent a fully compromised agent.
• Supply chain. CloakBrowser downloads a Chromium binary from cloakbrowser.dev. The binary is SHA-256 verified but proprietary.
• Browser automation. Any tool with browser access has inherent risks. Run in isolated environments when possible.

Get involved

browser-search is open source and free. If you find it useful:

• ⭐ Star the repo — helps others discover it
• 🐛 Open an issue — report bugs or suggest features
• 🔀 Submit a PR — fix, improve, extend
• 💬 Share it — with your team, on Reddit, Twitter, Discord
• 🧠 Adapt it — fork it, tweak the SKILL.md, make it yours

Every contribution, no matter how small, makes this better.

FAQ

See FAQ.md for frequently asked questions about installation, architecture, design decisions, and common issues.

License

MIT