@askjo/camofox-browser 1.0.12 → 1.0.13

package/{Dockerfile.camoufox → Dockerfile}

@@ -49,11 +49,12 @@ WORKDIR /app
 COPY package.json ./
 RUN npm install --production
 
-COPY server-camoufox.js ./
+COPY server.js ./
+COPY lib/ ./lib/
 
 ENV NODE_ENV=production
-ENV PORT=3000
+ENV CAMOFOX_PORT=3000
 
 EXPOSE 3000
 
-CMD ["node", "server-camoufox.js"]
+CMD ["node", "server.js"]

package/README.md

@@ -1,7 +1,7 @@
 <div align="center">
-  <img src="camofox.png" alt="camofox-browser" width="200" />
+  <img src="fox.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><strong>Anti-detection browser server for AI agents, powered by Camoufox</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>
@@ -9,8 +9,8 @@
     <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.
+    Built on <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 browsing.
   </p>
 </div>
 
@@ -28,10 +28,10 @@ This project wraps that engine in a REST API built for agents: accessibility sna
 
 - **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
+- **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
+- **Deploy Anywhere** — Docker, Fly.io, Railway
 
 ## Quick Start
 
@@ -41,16 +41,6 @@ This project wraps that engine in a REST API built for agents: accessibility sna
 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
@@ -62,52 +52,84 @@ npm install
 npm start  # downloads Camoufox on first run (~300MB)
 ```
 
+Default port is `9377`. Set `CAMOFOX_PORT` to override.
+
 ### Docker
 
 ```bash
-docker build -f Dockerfile.camoufox -t camofox-browser .
-docker run -p 3000:3000 camofox-browser
+docker build -t camofox-browser .
+docker run -p 9377:9377 camofox-browser
 ```
 
+### Fly.io / Railway
+
+`fly.toml` and `railway.toml` are included. Deploy with `fly deploy` or connect the repo to Railway.
+
 ## Usage
 
 ```bash
 # Create a tab
-curl -X POST http://localhost:3000/tabs \
+curl -X POST http://localhost:9377/tabs \
+  -H 'Content-Type: application/json' \
   -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"
+# Get accessibility snapshot with element refs
+curl "http://localhost:9377/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 \
+curl -X POST http://localhost:9377/tabs/TAB_ID/click \
+  -H 'Content-Type: application/json' \
   -d '{"userId": "agent1", "ref": "e1"}'
 
-# Search with macros
-curl -X POST http://localhost:3000/tabs/TAB_ID/navigate \
+# Type into an element
+curl -X POST http://localhost:9377/tabs/TAB_ID/type \
+  -H 'Content-Type: application/json' \
+  -d '{"userId": "agent1", "ref": "e2", "text": "hello", "pressEnter": true}'
+
+# Navigate with a search macro
+curl -X POST http://localhost:9377/tabs/TAB_ID/navigate \
+  -H 'Content-Type: application/json' \
   -d '{"userId": "agent1", "macro": "@google_search", "query": "best coffee beans"}'
 ```
 
 ## API
 
+### Tab Lifecycle
+
 | 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` | Create tab with initial URL |
+| `GET` | `/tabs?userId=X` | List open tabs |
+| `GET` | `/tabs/:id/stats` | Tab stats (tool calls, visited URLs) |
+| `DELETE` | `/tabs/:id` | Close tab |
+| `DELETE` | `/tabs/group/:groupId` | Close all tabs in a group |
+| `DELETE` | `/sessions/:userId` | Close all tabs for a user |
+
+### Page Interaction
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/tabs/:id/snapshot` | Accessibility snapshot with element refs |
+| `POST` | `/tabs/:id/click` | Click element by ref or CSS selector |
+| `POST` | `/tabs/:id/type` | Type text into element |
+| `POST` | `/tabs/:id/press` | Press a keyboard key |
+| `POST` | `/tabs/:id/scroll` | Scroll page (up/down/left/right) |
+| `POST` | `/tabs/:id/navigate` | Navigate to URL or search macro |
+| `POST` | `/tabs/:id/wait` | Wait for selector or timeout |
+| `GET` | `/tabs/:id/links` | Extract all links on page |
+| `GET` | `/tabs/:id/screenshot` | Take screenshot |
 | `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 |
+| `POST` | `/tabs/:id/refresh` | Refresh page |
+
+### Server
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
 | `GET` | `/health` | Health check |
+| `POST` | `/start` | Start browser engine |
+| `POST` | `/stop` | Stop browser engine |
 
 ## Search Macros
 
@@ -116,7 +138,7 @@ curl -X POST http://localhost:3000/tabs/TAB_ID/navigate \
 ## Architecture
 
 ```
-Browser Instance
+Browser Instance (Camoufox)
 └── User Session (BrowserContext) — isolated cookies/storage
     ├── Tab Group (sessionKey: "conv1")
     │   ├── Tab (google.com)
@@ -130,15 +152,22 @@ Sessions auto-expire after 30 minutes of inactivity.
 ## Testing
 
 ```bash
-npm test              # e2e tests
-npm run test:live     # live Google tests
+npm test              # all tests
+npm run test:e2e      # e2e tests only
+npm run test:live     # live site tests (Google, macros)
 npm run test:debug    # with server output
 ```
 
+## npm
+
+```bash
+npm install @askjo/camofox-browser
+```
+
 ## Credits
 
 - [Camoufox](https://camoufox.com) — Firefox-based browser with C++ anti-detection
-- [Amp](https://ampcode.com) — AI coding agent
+- [OpenClaw](https://openclaw.ai) — Open-source AI agent framework
 
 ## License
 

package/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "camofox-browser",
-  "name": "Camoufox Browser",
+  "name": "Camofox Browser",
   "description": "Anti-detection browser automation for AI agents using Camoufox (Firefox-based)",
   "version": "1.0.11",
   "configSchema": {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@askjo/camofox-browser",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "Headless browser automation server and OpenClaw plugin for AI agents - anti-detection, element refs, and session isolation",
-  "main": "server-camoufox.js",
+  "main": "server.js",
   "license": "MIT",
   "author": "Jo Inc <oss@askjo.ai>",
   "homepage": "https://github.com/jo-inc/camofox-browser#readme",
@@ -32,21 +32,22 @@
     "node": ">=18"
   },
   "files": [
-    "server-camoufox.js",
+    "server.js",
     "lib/",
     "plugin.ts",
     "openclaw.plugin.json",
-    "run-camoufox.sh",
-    "Dockerfile.camoufox",
+    "run.sh",
+    "Dockerfile",
     "README.md",
     "LICENSE"
   ],
   "openclaw": {
-    "extensions": ["plugin.ts"]
+    "extensions": [
+      "plugin.ts"
+    ]
   },
   "scripts": {
-    "start": "node server-camoufox.js",
-    "start:chrome": "node server.js",
+    "start": "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",

package/plugin.ts

@@ -105,10 +105,10 @@ async function startServer(
   port: number,
   log: PluginApi["log"]
 ): Promise<ChildProcess> {
-  const serverPath = join(pluginDir, "server-camoufox.js");
+  const serverPath = join(pluginDir, "server.js");
   const proc = spawn("node", [serverPath], {
     cwd: pluginDir,
-    env: { ...process.env, PORT: String(port) },
+    env: { ...process.env, CAMOFOX_PORT: String(port) },
     stdio: ["ignore", "pipe", "pipe"],
     detached: false,
   });

package/{run-camoufox.sh → run.sh}

@@ -1,16 +1,16 @@
 #!/bin/bash
-# Local development script for camoufox-browser
-# Usage: ./run-camoufox.sh [-p port]
-# Example: ./run-camoufox.sh -p 3001
+# Local development script for camofox-browser
+# Usage: ./run.sh [-p port]
+# Example: ./run.sh -p 3001
 
-PORT=3000
+CAMOFOX_PORT=3000
 while getopts "p:" opt; do
   case $opt in
-    p) PORT="$OPTARG" ;;
+    p) CAMOFOX_PORT="$OPTARG" ;;
     *) echo "Usage: $0 [-p port]"; exit 1 ;;
   esac
 done
-export PORT
+export CAMOFOX_PORT
 
 # Install deps if needed
 if [ ! -d "node_modules" ]; then
@@ -30,8 +30,8 @@ if ! command -v nodemon &> /dev/null; then
     npm install -g nodemon
 fi
 
-echo "Starting camoufox-browser on http://localhost:$PORT (with auto-reload)"
-echo "Logs: /tmp/camoufox-browser.log"
-nodemon --watch server-camoufox.js --exec "node server-camoufox.js" 2>&1 | while IFS= read -r line; do
+echo "Starting camofox-browser on http://localhost:$CAMOFOX_PORT (with auto-reload)"
+echo "Logs: /tmp/camofox-browser.log"
+nodemon --watch server.js --exec "node server.js" 2>&1 | while IFS= read -r line; do
   echo "[$(date '+%Y-%m-%d %H:%M:%S')] $line"
-done | tee -a /tmp/camoufox-browser.log
+done | tee -a /tmp/camofox-browser.log

package/{server-camoufox.js → server.js}

@@ -1269,20 +1269,44 @@ app.post('/act', async (req, res) => {
 });
 
 // Graceful shutdown
-process.on('SIGTERM', async () => {
-  console.log('Shutting down...');
+let shuttingDown = false;
+
+async function gracefulShutdown(signal) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  console.log(`${signal} received, shutting down...`);
+
+  const forceTimeout = setTimeout(() => {
+    console.error('Shutdown timed out after 10s, forcing exit');
+    process.exit(1);
+  }, 10000);
+  forceTimeout.unref();
+
+  server.close();
+
   for (const [userId, session] of sessions) {
     await session.context.close().catch(() => {});
   }
   if (browser) await browser.close().catch(() => {});
   process.exit(0);
-});
+}
+
+process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+process.on('SIGINT', () => gracefulShutdown('SIGINT'));
 
-const PORT = process.env.PORT || 9377;
-app.listen(PORT, async () => {
-  console.log(`🦊 camoufox-browser listening on port ${PORT}`);
-  // Pre-launch browser so it's ready for first request
-  await ensureBrowser().catch(err => {
+const PORT = process.env.CAMOFOX_PORT || 9377;
+const server = app.listen(PORT, () => {
+  console.log(`camofox-browser listening on port ${PORT}`);
+  ensureBrowser().catch(err => {
     console.error('Failed to pre-launch browser:', err.message);
   });
 });
+
+server.on('error', (err) => {
+  if (err.code === 'EADDRINUSE') {
+    console.error(`FATAL: Port ${PORT} is already in use. Set CAMOFOX_PORT env var to use a different port.`);
+    process.exit(1);
+  }
+  console.error('Server error:', err);
+  process.exit(1);
+});