@askjo/camofox-browser 1.0.12

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,145 @@
+<div align="center">
+  <img src="camofox.png" alt="camofox-browser" width="200" />
+  <h1>camofox-browser</h1>
+  <p><strong>Headless browser server for AI agents with C++ anti-detection</strong></p>
+  <p>
+    <a href="https://github.com/jo-inc/camofox-browser/actions"><img src="https://img.shields.io/badge/build-passing-brightgreen" alt="Build" /></a>
+    <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License" /></a>
+    <a href="https://camoufox.com"><img src="https://img.shields.io/badge/engine-Camoufox-red" alt="Camoufox" /></a>
+    <a href="https://hub.docker.com"><img src="https://img.shields.io/badge/docker-ready-blue" alt="Docker" /></a>
+  </p>
+  <p>
+    Powered by <a href="https://camoufox.com">Camoufox</a> — a Firefox fork with fingerprint spoofing at the C++ level.<br/>
+    The same engine behind <a href="https://askjo.ai">askjo.ai</a>'s web scraping.
+  </p>
+</div>
+
+---
+
+## Why
+
+AI agents need to browse the real web. Playwright gets blocked. Headless Chrome gets fingerprinted. Stealth plugins become the fingerprint.
+
+Camoufox patches Firefox at the **C++ implementation level** — `navigator.hardwareConcurrency`, WebGL renderers, AudioContext, screen geometry, WebRTC — all spoofed before JavaScript ever sees them. No shims, no wrappers, no tells.
+
+This project wraps that engine in a REST API built for agents: accessibility snapshots instead of bloated HTML, stable element refs for clicking, and search macros for common sites.
+
+## Features
+
+- **C++ Anti-Detection** — bypasses Google, Cloudflare, and most bot detection
+- **Element Refs** — stable `e1`, `e2`, `e3` identifiers for reliable interaction
+- **Token-Efficient** — accessibility snapshots are 90% smaller than raw HTML
+- **Session Isolation** — separate cookies/storage per user
+- **Search Macros** — `@google_search`, `@youtube_search`, `@amazon_search`, and 10 more
+- **Docker Ready** — production Dockerfile with pre-baked Camoufox binary
+
+## Quick Start
+
+### OpenClaw Plugin
+
+```bash
+openclaw plugins install @askjo/camofox-browser
+```
+
+```yaml
+# ~/.openclaw/openclaw.json
+plugins:
+  entries:
+    camofox-browser:
+      enabled: true
+      config:
+        url: "http://localhost:9377"
+```
+
+**Tools:** `camofox_create_tab` · `camofox_snapshot` · `camofox_click` · `camofox_type` · `camofox_navigate` · `camofox_scroll` · `camofox_screenshot` · `camofox_close_tab` · `camofox_list_tabs`
+
+### Standalone
+
+```bash
+git clone https://github.com/jo-inc/camofox-browser
+cd camofox-browser
+npm install
+npm start  # downloads Camoufox on first run (~300MB)
+```
+
+### Docker
+
+```bash
+docker build -f Dockerfile.camoufox -t camofox-browser .
+docker run -p 3000:3000 camofox-browser
+```
+
+## Usage
+
+```bash
+# Create a tab
+curl -X POST http://localhost:3000/tabs \
+  -d '{"userId": "agent1", "sessionKey": "task1", "url": "https://example.com"}'
+
+# Get page snapshot with element refs
+curl "http://localhost:3000/tabs/TAB_ID/snapshot?userId=agent1"
+# → { "snapshot": "[button e1] Submit  [link e2] Learn more", ... }
+
+# Click by ref
+curl -X POST http://localhost:3000/tabs/TAB_ID/click \
+  -d '{"userId": "agent1", "ref": "e1"}'
+
+# Search with macros
+curl -X POST http://localhost:3000/tabs/TAB_ID/navigate \
+  -d '{"userId": "agent1", "macro": "@google_search", "query": "best coffee beans"}'
+```
+
+## API
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/tabs` | Create tab |
+| `GET` | `/tabs/:id/snapshot` | Accessibility snapshot with refs |
+| `POST` | `/tabs/:id/click` | Click element by ref |
+| `POST` | `/tabs/:id/type` | Type into element |
+| `POST` | `/tabs/:id/navigate` | Navigate to URL or macro |
+| `POST` | `/tabs/:id/scroll` | Scroll page |
+| `GET` | `/tabs/:id/screenshot` | Screenshot |
+| `GET` | `/tabs/:id/links` | All links on page |
+| `POST` | `/tabs/:id/back` | Go back |
+| `POST` | `/tabs/:id/forward` | Go forward |
+| `POST` | `/tabs/:id/refresh` | Refresh |
+| `DELETE` | `/tabs/:id` | Close tab |
+| `GET` | `/tabs?userId=X` | List tabs |
+| `DELETE` | `/sessions/:userId` | Close all user tabs |
+| `GET` | `/health` | Health check |
+
+## Search Macros
+
+`@google_search` · `@youtube_search` · `@amazon_search` · `@reddit_search` · `@wikipedia_search` · `@twitter_search` · `@yelp_search` · `@spotify_search` · `@netflix_search` · `@linkedin_search` · `@instagram_search` · `@tiktok_search` · `@twitch_search`
+
+## Architecture
+
+```
+Browser Instance
+└── User Session (BrowserContext) — isolated cookies/storage
+    ├── Tab Group (sessionKey: "conv1")
+    │   ├── Tab (google.com)
+    │   └── Tab (github.com)
+    └── Tab Group (sessionKey: "conv2")
+        └── Tab (amazon.com)
+```
+
+Sessions auto-expire after 30 minutes of inactivity.
+
+## Testing
+
+```bash
+npm test              # e2e tests
+npm run test:live     # live Google tests
+npm run test:debug    # with server output
+```
+
+## Credits
+
+- [Camoufox](https://camoufox.com) — Firefox-based browser with C++ anti-detection
+- [Amp](https://ampcode.com) — AI coding agent
+
+## License
+
+MIT

package/lib/macros.js

@@ -0,0 +1,30 @@
+const MACROS = {
+  '@google_search': (query) => `https://www.google.com/search?q=${encodeURIComponent(query || '')}`,
+  '@youtube_search': (query) => `https://www.youtube.com/results?search_query=${encodeURIComponent(query || '')}`,
+  '@amazon_search': (query) => `https://www.amazon.com/s?k=${encodeURIComponent(query || '')}`,
+  '@reddit_search': (query) => `https://www.reddit.com/search/?q=${encodeURIComponent(query || '')}`,
+  '@wikipedia_search': (query) => `https://en.wikipedia.org/wiki/Special:Search?search=${encodeURIComponent(query || '')}`,
+  '@twitter_search': (query) => `https://twitter.com/search?q=${encodeURIComponent(query || '')}`,
+  '@yelp_search': (query) => `https://www.yelp.com/search?find_desc=${encodeURIComponent(query || '')}`,
+  '@spotify_search': (query) => `https://open.spotify.com/search/${encodeURIComponent(query || '')}`,
+  '@netflix_search': (query) => `https://www.netflix.com/search?q=${encodeURIComponent(query || '')}`,
+  '@linkedin_search': (query) => `https://www.linkedin.com/search/results/all/?keywords=${encodeURIComponent(query || '')}`,
+  '@instagram_search': (query) => `https://www.instagram.com/explore/tags/${encodeURIComponent(query || '')}`,
+  '@tiktok_search': (query) => `https://www.tiktok.com/search?q=${encodeURIComponent(query || '')}`,
+  '@twitch_search': (query) => `https://www.twitch.tv/search?term=${encodeURIComponent(query || '')}`
+};
+
+function expandMacro(macro, query) {
+  const macroFn = MACROS[macro];
+  return macroFn ? macroFn(query) : null;
+}
+
+function getSupportedMacros() {
+  return Object.keys(MACROS);
+}
+
+module.exports = {
+  expandMacro,
+  getSupportedMacros,
+  MACROS
+};

package/openclaw.plugin.json

@@ -0,0 +1,39 @@
+{
+  "id": "camofox-browser",
+  "name": "Camoufox Browser",
+  "description": "Anti-detection browser automation for AI agents using Camoufox (Firefox-based)",
+  "version": "1.0.11",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "url": {
+        "type": "string",
+        "description": "Camoufox browser server URL"
+      },
+      "port": {
+        "type": "number",
+        "description": "Server port (used if url not set)",
+        "default": 9377
+      },
+      "autoStart": {
+        "type": "boolean",
+        "description": "Auto-start the camofox-browser server with the Gateway",
+        "default": true
+      }
+    },
+    "additionalProperties": false
+  },
+  "uiHints": {
+    "url": {
+      "label": "Server URL",
+      "placeholder": "http://localhost:9377"
+    },
+    "port": {
+      "label": "Server Port",
+      "placeholder": "9377"
+    },
+    "autoStart": {
+      "label": "Auto-start server with Gateway"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@askjo/camofox-browser",
+  "version": "1.0.12",
+  "description": "Headless browser automation server and OpenClaw plugin for AI agents - anti-detection, element refs, and session isolation",
+  "main": "server-camoufox.js",
+  "license": "MIT",
+  "author": "Jo Inc <oss@askjo.ai>",
+  "homepage": "https://github.com/jo-inc/camofox-browser#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jo-inc/camofox-browser.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jo-inc/camofox-browser/issues"
+  },
+  "keywords": [
+    "browser",
+    "automation",
+    "headless",
+    "scraping",
+    "camofox",
+    "camoufox",
+    "anti-detection",
+    "ai-agent",
+    "openclaw",
+    "clawdbot",
+    "moltbot",
+    "playwright",
+    "firefox"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "server-camoufox.js",
+    "lib/",
+    "plugin.ts",
+    "openclaw.plugin.json",
+    "run-camoufox.sh",
+    "Dockerfile.camoufox",
+    "README.md",
+    "LICENSE"
+  ],
+  "openclaw": {
+    "extensions": ["plugin.ts"]
+  },
+  "scripts": {
+    "start": "node server-camoufox.js",
+    "start:chrome": "node server.js",
+    "test": "jest --runInBand --forceExit",
+    "test:e2e": "jest --runInBand --forceExit tests/e2e",
+    "test:live": "RUN_LIVE_TESTS=1 jest --runInBand --forceExit tests/live",
+    "test:debug": "DEBUG_SERVER=1 jest --runInBand --forceExit",
+    "postinstall": "npx camoufox-js fetch || true"
+  },
+  "dependencies": {
+    "camoufox-js": "^0.8.5",
+    "dotenv": "^17.2.3",
+    "express": "^4.18.2",
+    "playwright": "^1.50.0",
+    "playwright-core": "^1.58.0",
+    "playwright-extra": "^4.3.6",
+    "puppeteer-extra-plugin-stealth": "^2.11.2"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  }
+}