@askjo/camoufox-browser 1.0.0

package/.env.bak

@@ -0,0 +1,4 @@
+PROXY_HOST=166.88.179.132
+PROXY_PORT=46040
+PROXY_USERNAME=NleQYPIiORIbOYT
+PROXY_PASSWORD=936asYRvpdftjI6

package/.github/workflows/deploy.yml

@@ -0,0 +1,21 @@
+name: Deploy to Fly.io
+
+on:
+  push:
+    branches:
+      - master
+      - main
+
+jobs:
+  deploy:
+    name: Deploy to Fly.io
+    runs-on: ubuntu-latest
+    concurrency: deploy-group
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: superfly/flyctl-actions/setup-flyctl@master
+
+      - run: flyctl deploy --remote-only
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

package/AGENTS.md

@@ -0,0 +1,153 @@
+# camoufox-browser Agent Guide
+
+Headless browser automation server for AI agents. Run locally or deploy to any cloud provider.
+
+## Quick Start for Agents
+
+```bash
+# Install and start
+npm install && npm start
+# Server runs on http://localhost:3000
+```
+
+## Core Workflow
+
+1. **Create a tab** → Get `tabId`
+2. **Navigate** → Go to URL or use search macro
+3. **Get snapshot** → Receive page content with element refs (`e1`, `e2`, etc.)
+4. **Interact** → Click/type using refs
+5. **Repeat** steps 3-4 as needed
+
+## API Reference
+
+### Create Tab
+```bash
+POST /tabs
+{"userId": "agent1", "listItemId": "task1", "url": "https://example.com"}
+```
+Returns: `{"tabId": "abc123", "url": "...", "title": "..."}`
+
+### Navigate
+```bash
+POST /tabs/:tabId/navigate
+{"userId": "agent1", "url": "https://google.com"}
+# Or use macro:
+{"userId": "agent1", "macro": "@google_search", "query": "weather today"}
+```
+
+### Get Snapshot
+```bash
+GET /tabs/:tabId/snapshot?userId=agent1
+```
+Returns accessibility tree with refs:
+```
+[heading] Example Domain
+[paragraph] This domain is for use in examples.
+[link e1] More information...
+```
+
+### Click Element
+```bash
+POST /tabs/:tabId/click
+{"userId": "agent1", "ref": "e1"}
+# Or CSS selector:
+{"userId": "agent1", "selector": "button.submit"}
+```
+
+### Type Text
+```bash
+POST /tabs/:tabId/type
+{"userId": "agent1", "ref": "e2", "text": "hello world"}
+# Add enter: {"userId": "agent1", "ref": "e2", "text": "search query", "pressEnter": true}
+```
+
+### Scroll
+```bash
+POST /tabs/:tabId/scroll
+{"userId": "agent1", "direction": "down", "amount": 500}
+```
+
+### Navigation
+```bash
+POST /tabs/:tabId/back     {"userId": "agent1"}
+POST /tabs/:tabId/forward  {"userId": "agent1"}
+POST /tabs/:tabId/refresh  {"userId": "agent1"}
+```
+
+### Get Links
+```bash
+GET /tabs/:tabId/links?userId=agent1&limit=50
+```
+
+### Close Tab
+```bash
+DELETE /tabs/:tabId?userId=agent1
+```
+
+## Search Macros
+
+Use these instead of constructing URLs:
+
+| Macro | Site |
+|-------|------|
+| `@google_search` | Google |
+| `@youtube_search` | YouTube |
+| `@amazon_search` | Amazon |
+| `@reddit_search` | Reddit |
+| `@wikipedia_search` | Wikipedia |
+| `@twitter_search` | Twitter/X |
+| `@yelp_search` | Yelp |
+| `@linkedin_search` | LinkedIn |
+
+## Element Refs
+
+Refs like `e1`, `e2` are stable identifiers for page elements:
+
+1. Call `/snapshot` to get current refs
+2. Use ref in `/click` or `/type`
+3. Refs reset on navigation - get new snapshot after
+
+## Session Management
+
+- `userId` isolates cookies/storage between users
+- `listItemId` groups tabs by conversation/task
+- Sessions timeout after 30 minutes of inactivity
+- Delete all user data: `DELETE /sessions/:userId`
+
+## Running Engines
+
+### Camoufox (Default - Recommended)
+```bash
+npm start
+# Or: ./run-camoufox.sh
+```
+Firefox-based with anti-detection. Bypasses Google captcha.
+
+### Chrome (Legacy)
+```bash
+npm run start:chrome
+# Or: ./run.sh
+```
+Playwright + stealth plugin. May be blocked by Google.
+
+## Testing
+
+```bash
+npm test              # E2E tests
+npm run test:live     # Live Google tests
+npm run test:debug    # With server output
+```
+
+## Docker
+
+```bash
+docker build -f Dockerfile.camoufox -t camoufox-browser .
+docker run -p 3000:3000 camoufox-browser
+```
+
+## Key Files
+
+- `server-camoufox.js` - Camoufox engine (default)
+- `server.js` - Chrome engine (legacy)
+- `Dockerfile.camoufox` - Production container
+- `fly.toml` - Fly.io deployment config

package/Dockerfile.camoufox

@@ -0,0 +1,59 @@
+FROM node:20-slim
+
+# Pinned Camoufox version for reproducible builds
+# Update these when upgrading Camoufox
+ARG CAMOUFOX_VERSION=135.0.1
+ARG CAMOUFOX_RELEASE=beta.24
+ARG CAMOUFOX_URL=https://github.com/daijro/camoufox/releases/download/v${CAMOUFOX_VERSION}-${CAMOUFOX_RELEASE}/camoufox-${CAMOUFOX_VERSION}-${CAMOUFOX_RELEASE}-lin.x86_64.zip
+
+# Install dependencies for Camoufox (Firefox-based)
+RUN apt-get update && apt-get install -y \
+    # Firefox dependencies
+    libgtk-3-0 \
+    libdbus-glib-1-2 \
+    libxt6 \
+    libasound2 \
+    libx11-xcb1 \
+    libxcomposite1 \
+    libxcursor1 \
+    libxdamage1 \
+    libxfixes3 \
+    libxi6 \
+    libxrandr2 \
+    libxrender1 \
+    libxss1 \
+    libxtst6 \
+    # Fonts
+    fonts-liberation \
+    fonts-noto-color-emoji \
+    fontconfig \
+    # Utils
+    ca-certificates \
+    curl \
+    unzip \
+    && rm -rf /var/lib/apt/lists/*
+
+# Pre-bake Camoufox browser binary into image
+# This avoids downloading at runtime and pins the version
+# Note: unzip returns exit code 1 for warnings (Unicode filenames), so we use || true and verify
+RUN mkdir -p /root/.cache/camoufox \
+    && curl -L -o /tmp/camoufox.zip "${CAMOUFOX_URL}" \
+    && (unzip -q /tmp/camoufox.zip -d /root/.cache/camoufox || true) \
+    && rm /tmp/camoufox.zip \
+    && chmod -R 755 /root/.cache/camoufox \
+    && echo "{\"version\":\"${CAMOUFOX_VERSION}\",\"release\":\"${CAMOUFOX_RELEASE}\"}" > /root/.cache/camoufox/version.json \
+    && test -f /root/.cache/camoufox/camoufox-bin && echo "Camoufox installed successfully"
+
+WORKDIR /app
+
+COPY package.json ./
+RUN npm install --production
+
+COPY server-camoufox.js ./
+
+ENV NODE_ENV=production
+ENV PORT=3000
+
+EXPOSE 3000
+
+CMD ["node", "server-camoufox.js"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jo, Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,234 @@
+# camoufox-browser
+
+A headless browser automation server designed for AI agents. Powered by [Camoufox](https://camoufox.com) - a Firefox-based browser with C++ anti-detection that bypasses bot detection including Google captcha.
+
+This is the same browser engine that powers [askjo.ai](https://askjo.ai)'s web scraping capabilities.
+
+**Perfect for:** [OpenClaw](https://openclaw.ai), Claude Code, LangChain agents, AutoGPT, and any AI system that needs to browse the web.
+
+## Motivation
+
+AI agents need to browse the web, but current solutions have significant limitations:
+
+- **Playwright/Puppeteer + stealth plugins** get detected and blocked by Google, Cloudflare, and most anti-bot systems. JavaScript-level evasion isn't enough.
+- **Headless Chrome** is trivially fingerprinted. Sites check for hundreds of browser characteristics that reveal automation.
+- **API-based scrapers** (Browserless, ScrapingBee) work but cost money per request and add latency.
+- **Raw HTTP requests** can't handle JavaScript-rendered content or complex interactions.
+
+Camoufox solves this with **C++ level anti-detection** baked into the Firefox source code itself - not a plugin that can be detected, but fundamental changes to how the browser reports its fingerprint. This is the same approach used by commercial anti-detect browsers.
+
+This project wraps Camoufox in a simple REST API optimized for AI agents: accessibility snapshots instead of bloated HTML, stable element refs for reliable clicking, and search macros for common sites.
+
+## Features
+
+- **Anti-Detection** - Camoufox engine (Firefox-based) with C++ fingerprint spoofing, bypasses Google captcha
+- **Element Refs** - Stable `e1`, `e2`, `e3` references for clicking/typing
+- **Session Isolation** - Separate cookies/storage per user, tabs grouped by conversation
+- **Search Macros** - 13 built-in URL macros (`@google_search`, `@youtube_search`, etc.)
+- **Token-Efficient** - Accessibility snapshots instead of full HTML (90% smaller)
+- **Docker Ready** - Production Dockerfile with pre-baked Camoufox binary
+
+## Quick Start
+
+### OpenClaw Plugin
+
+Install as an OpenClaw plugin for agent tool access:
+
+```bash
+openclaw plugins install @jo-inc/camoufox-browser
+```
+
+Then start the server and configure:
+
+```yaml
+# ~/.openclaw/openclaw.json
+plugins:
+  entries:
+    camoufox-browser:
+      enabled: true
+      config:
+        url: "http://localhost:9377"
+```
+
+The plugin provides these agent tools:
+- `camoufox_create_tab` - Create a browser tab
+- `camoufox_snapshot` - Get page snapshot with element refs
+- `camoufox_click` - Click elements by ref
+- `camoufox_type` - Type into elements
+- `camoufox_navigate` - Navigate to URLs or use search macros
+- `camoufox_scroll` - Scroll the page
+- `camoufox_screenshot` - Take screenshots
+- `camoufox_close_tab` - Close tabs
+- `camoufox_list_tabs` - List open tabs
+
+### Standalone Server
+
+```bash
+# Clone and install
+git clone https://github.com/jo-inc/camoufox-browser
+cd camoufox-browser
+npm install
+
+# Start server (downloads Camoufox browser on first run)
+npm start                    # Default port 3000
+./run-camoufox.sh -p 3001    # Custom port
+
+# Server runs on http://localhost:3000
+```
+
+## API Overview
+
+### Create a Tab
+```bash
+curl -X POST http://localhost:3000/tabs \
+  -H "Content-Type: application/json" \
+  -d '{"userId": "user1", "listItemId": "conv1", "url": "https://example.com"}'
+```
+
+### Get Page Snapshot (with element refs)
+```bash
+curl "http://localhost:3000/tabs/TAB_ID/snapshot?userId=user1"
+```
+
+Response includes refs for interaction:
+```json
+{
+  "snapshot": "[button e1] Submit  [link e2] Learn more",
+  "refs": {
+    "e1": { "role": "button", "name": "Submit" },
+    "e2": { "role": "link", "name": "Learn more" }
+  },
+  "url": "https://example.com"
+}
+```
+
+### Click an Element
+```bash
+curl -X POST http://localhost:3000/tabs/TAB_ID/click \
+  -H "Content-Type: application/json" \
+  -d '{"userId": "user1", "ref": "e1"}'
+```
+
+### Search with Macros
+```bash
+curl -X POST http://localhost:3000/tabs/TAB_ID/navigate \
+  -H "Content-Type: application/json" \
+  -d '{"userId": "user1", "macro": "@google_search", "query": "best coffee beans"}'
+```
+
+## All Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Health check |
+| GET | `/tabs?userId=X` | List all tab groups for user |
+| POST | `/tabs` | Create new tab |
+| DELETE | `/tabs/:tabId` | Close tab |
+| POST | `/tabs/:tabId/navigate` | Navigate to URL or macro |
+| GET | `/tabs/:tabId/snapshot` | Get accessibility snapshot with refs |
+| POST | `/tabs/:tabId/click` | Click element by ref or selector |
+| POST | `/tabs/:tabId/type` | Type into element |
+| POST | `/tabs/:tabId/scroll` | Scroll page |
+| POST | `/tabs/:tabId/back` | Go back |
+| POST | `/tabs/:tabId/forward` | Go forward |
+| POST | `/tabs/:tabId/refresh` | Refresh page |
+| GET | `/tabs/:tabId/links` | Get all links |
+| GET | `/tabs/:tabId/screenshot` | Get screenshot |
+| DELETE | `/sessions/:userId` | Close all tabs for user |
+
+## Search Macros
+
+Navigate supports these macros for common sites:
+
+- `@google_search` - Google
+- `@youtube_search` - YouTube
+- `@amazon_search` - Amazon
+- `@reddit_search` - Reddit
+- `@wikipedia_search` - Wikipedia
+- `@twitter_search` - Twitter/X
+- `@yelp_search` - Yelp
+- `@spotify_search` - Spotify
+- `@netflix_search` - Netflix
+- `@linkedin_search` - LinkedIn
+- `@instagram_search` - Instagram
+- `@tiktok_search` - TikTok
+- `@twitch_search` - Twitch
+
+## Architecture
+
+```
+Browser Instance
+└── User Session (BrowserContext) - isolated cookies/storage
+    ├── Tab Group (listItemId: "conv1") - conversation A
+    │   ├── Tab (google.com)
+    │   └── Tab (github.com)
+    └── Tab Group (listItemId: "conv2") - conversation B
+        └── Tab (amazon.com)
+```
+
+- One browser instance shared across users
+- Separate BrowserContext per user (isolated cookies/storage)
+- Tabs grouped by `listItemId` (conversation/task)
+- 30-minute session timeout with automatic cleanup
+
+## Running Locally
+
+```bash
+# Start with default port (3000)
+./run-camoufox.sh
+# Or: npm start
+
+# Start with custom port
+./run-camoufox.sh -p 3001
+```
+
+First run downloads the Camoufox browser (~300MB).
+
+### Experimental
+
+See [`experimental/`](experimental/) for alternative browser engines.
+
+## Docker Deployment
+
+```bash
+# Build with Camoufox (recommended)
+docker build -f Dockerfile.camoufox -t camoufox-browser .
+
+# Run
+docker run -p 3000:3000 camoufox-browser
+```
+
+## Fly.io Deployment
+
+```bash
+fly launch --no-deploy
+fly deploy
+```
+
+## Testing
+
+```bash
+npm test                 # Run all e2e tests
+npm run test:live        # Run live Google tests (may hit captcha)
+npm run test:debug       # Show server output for debugging
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PORT` | Server port | 3000 |
+| `NODE_ENV` | Environment | development |
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a PR.
+
+## Credits
+
+- [Camoufox](https://camoufox.com) - Firefox-based browser with C++ anti-detection
+- [Amp](https://ampcode.com) - AI coding agent
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: camoufox-browser
+description: Control a headless Camoufox browser with anti-detection. Browse websites, search Google/YouTube/Amazon, click elements, fill forms, and extract content.
+globs:
+requirements:
+  bins:
+    - node
+    - npm
+---
+
+# camoufox-browser Skill
+
+You can control a headless Camoufox browser running at `http://localhost:9377`. Camoufox is a Firefox-based browser with C++ anti-detection that bypasses bot detection including Google captcha.
+
+This is the same browser engine that powers [askjo.ai](https://askjo.ai)'s web scraping.
+
+## Install as OpenClaw Plugin
+
+```bash
+# Clone and install
+git clone https://github.com/jo-inc/camoufox-browser ~/.openclaw/extensions/camoufox-browser
+cd ~/.openclaw/extensions/camoufox-browser
+npm install
+
+# Start the server (port 9377)
+./run-camoufox.sh -p 9377 &
+
+# Enable the plugin
+openclaw plugins enable camoufox-browser
+```
+
+Then add the tools to your agent allowlist:
+
+```bash
+openclaw configure --section agents
+# Add camoufox-browser to tools.allow
+```
+
+## Quick Start (Standalone)
+
+```bash
+cd {baseDir}
+npm install
+npm start
+```
+
+The server runs on port 3000 by default. Use `./run-camoufox.sh -p 9377` for custom port.
+
+Check health: `curl http://localhost:9377/health`
+
+## How to Use
+
+### 1. Create a Tab
+
+```bash
+curl -X POST http://localhost:9377/tabs \
+  -H "Content-Type: application/json" \
+  -d '{"userId": "openclaw", "listItemId": "task1", "url": "https://example.com"}'
+```
+
+Save the `tabId` from the response for subsequent requests.
+
+### 2. Get Page Content
+
+```bash
+curl "http://localhost:9377/tabs/TAB_ID/snapshot?userId=openclaw"
+```
+
+This returns an accessibility snapshot with element refs like `e1`, `e2`, `e3`. These refs are stable identifiers you use to click or type into elements.
+
+### 3. Click Elements
+
+Use the ref from the snapshot:
+
+```bash
+curl -X POST http://localhost:9377/tabs/TAB_ID/click \
+  -H "Content-Type: application/json" \
+  -d '{"userId": "openclaw", "ref": "e1"}'
+```
+
+### 4. Type Text
+
+```bash
+curl -X POST http://localhost:9377/tabs/TAB_ID/type \
+  -H "Content-Type: application/json" \
+  -d '{"userId": "openclaw", "ref": "e2", "text": "hello world", "pressEnter": true}'
+```
+
+### 5. Search with Macros
+
+Instead of navigating to search URLs, use macros:
+
+```bash
+curl -X POST http://localhost:9377/tabs/TAB_ID/navigate \
+  -H "Content-Type: application/json" \
+  -d '{"userId": "openclaw", "macro": "@google_search", "query": "weather in New York"}'
+```
+
+Available macros:
+- `@google_search` - Search Google
+- `@youtube_search` - Search YouTube
+- `@amazon_search` - Search Amazon
+- `@reddit_search` - Search Reddit
+- `@wikipedia_search` - Search Wikipedia
+- `@twitter_search` - Search Twitter/X
+
+### 6. Scroll the Page
+
+```bash
+curl -X POST http://localhost:9377/tabs/TAB_ID/scroll \
+  -H "Content-Type: application/json" \
+  -d '{"userId": "openclaw", "direction": "down", "amount": 500}'
+```
+
+### 7. Navigate Back/Forward
+
+```bash
+curl -X POST http://localhost:9377/tabs/TAB_ID/back \
+  -H "Content-Type: application/json" \
+  -d '{"userId": "openclaw"}'
+```
+
+### 8. Get All Links
+
+```bash
+curl "http://localhost:9377/tabs/TAB_ID/links?userId=openclaw&limit=50"
+```
+
+### 9. Close Tab When Done
+
+```bash
+curl -X DELETE "http://localhost:9377/tabs/TAB_ID?userId=openclaw"
+```
+
+## Workflow Pattern
+
+1. Create tab with initial URL
+2. Get snapshot to see page content and element refs
+3. Click/type using refs from snapshot
+4. Get new snapshot after each navigation (refs reset)
+5. Repeat until task complete
+6. Close tab
+
+## Tips
+
+- Always get a fresh snapshot after clicking links or submitting forms
+- Use `pressEnter: true` when typing in search boxes
+- Element refs (`e1`, `e2`) reset after navigation - always get new snapshot
+- Use macros for searching instead of constructing URLs manually
+- The browser has anti-detection so it works with Google, Amazon, etc.
+
+## All Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/tabs` | Create tab |
+| GET | `/tabs/:id/snapshot` | Get page content with refs |
+| POST | `/tabs/:id/navigate` | Go to URL or macro |
+| POST | `/tabs/:id/click` | Click element |
+| POST | `/tabs/:id/type` | Type text |
+| POST | `/tabs/:id/scroll` | Scroll page |
+| POST | `/tabs/:id/back` | Go back |
+| POST | `/tabs/:id/forward` | Go forward |
+| GET | `/tabs/:id/links` | Get all links |
+| DELETE | `/tabs/:id` | Close tab |

package/experimental/chromium/Dockerfile

@@ -0,0 +1,35 @@
+FROM debian:bookworm-slim
+
+# Install Chromium and dependencies
+RUN apt-get update && apt-get install -y \
+    chromium \
+    fonts-liberation \
+    fonts-noto-color-emoji \
+    libnss3 \
+    libatk-bridge2.0-0 \
+    libdrm2 \
+    libxkbcommon0 \
+    libgbm1 \
+    libasound2 \
+    libxshmfence1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Node.js
+RUN apt-get update && apt-get install -y \
+    nodejs \
+    npm \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY package.json ./
+RUN npm install --production
+
+COPY server.js ./
+
+ENV NODE_ENV=production
+ENV PORT=3000
+
+EXPOSE 3000
+
+CMD ["node", "server.js"]