@askjo/camofox-browser 1.4.1 → 1.5.1

package/Dockerfile

@@ -4,7 +4,7 @@ FROM node:20-slim
 # 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
+ARG ARCH=x86_64
 
 # Install dependencies for Camoufox (Firefox-based)
 RUN apt-get update && apt-get install -y \
@@ -23,33 +23,37 @@ RUN apt-get update && apt-get install -y \
     libxrender1 \
     libxss1 \
     libxtst6 \
+    # Mesa OpenGL/EGL for WebGL support (software rendering via llvmpipe)
+    # Without these, Firefox cannot create WebGL contexts — a major bot detection signal
+    libegl1-mesa \
+    libgl1-mesa-dri \
+    libgbm1 \
+    # Xvfb virtual display — runs Camoufox as if on a real desktop (better anti-detection)
+    xvfb \
     # Fonts
     fonts-liberation \
     fonts-noto-color-emoji \
     fontconfig \
     # Utils
     ca-certificates \
-    curl \
     unzip \
     # yt-dlp runtime dependency
     python3-minimal \
     && rm -rf /var/lib/apt/lists/*
 
-# Install yt-dlp for YouTube transcript extraction (no browser needed)
-RUN curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp \
-    && chmod +x /usr/local/bin/yt-dlp
-
-# Pre-bake Camoufox browser binary into image
-# This avoids downloading at runtime and pins the version
+# Pre-bake Camoufox browser binary into image via bind mount (downloaded by Makefile)
 # 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 \
+RUN --mount=type=bind,source=dist,target=/dist \
+    mkdir -p /root/.cache/camoufox \
+    && (unzip -q /dist/camoufox-${ARCH}.zip -d /root/.cache/camoufox || true) \
     && 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"
 
+# Install yt-dlp for YouTube transcript extraction (no browser needed)
+RUN --mount=type=bind,source=dist,target=/dist \
+    install -m 755 /dist/yt-dlp-${ARCH} /usr/local/bin/yt-dlp
+
 WORKDIR /app
 
 COPY package.json ./
@@ -61,6 +65,6 @@ COPY lib/ ./lib/
 ENV NODE_ENV=production
 ENV CAMOFOX_PORT=3000
 
-EXPOSE 3000
+EXPOSE 9377
 
 CMD ["sh", "-c", "node --max-old-space-size=${MAX_OLD_SPACE_SIZE:-128} server.js"]

package/README.md

@@ -11,12 +11,18 @@
   <p>
     Standing on the mighty shoulders of <a href="https://camoufox.com">Camoufox</a> - a Firefox fork with fingerprint spoofing at the C++ level.
     <br/><br/>
-    The same engine behind <a href="https://askjo.ai">askjo.ai</a>'s web browsing.
+    The same engine behind <a href="https://askjo.ai?ref=camofox">Jo</a> — an AI assistant that doesn't need you to babysit it. Runs half on your Mac, half on a dedicated cloud machine that only you use. Available on macOS, Telegram, and WhatsApp. <a href="https://askjo.ai?ref=camofox">Try the beta free →</a>
   </p>
 </div>
 
 <br/>
 
+```bash
+git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser
+npm install && npm start
+# → http://localhost:9377
+```
+
 ---
 
 ## Why
@@ -76,11 +82,28 @@ Default port is `9377`. See [Environment Variables](#environment-variables) for
 
 ### Docker
 
+The included `Makefile` auto-detects your CPU architecture and pre-downloads Camoufox + yt-dlp binaries outside the Docker build, so rebuilds are fast (~30s vs ~3min).
+
 ```bash
-docker build -t camofox-browser .
-docker run -p 9377:9377 camofox-browser
+# Build and start (auto-detects arch: aarch64 on M1/M2, x86_64 on Intel)
+make up
+
+# Stop and remove the container
+make down
+
+# Force a clean rebuild (e.g. after upgrading VERSION/RELEASE)
+make reset
+
+# Just download binaries (without building)
+make fetch
+
+# Override arch or version explicitly
+make up ARCH=x86_64
+make up VERSION=135.0.1 RELEASE=beta.24
 ```
 
+Note: `make fetch` (or `make build`) must be run first — the Dockerfile expects pre-downloaded binaries in `dist/`.
+
 ### Fly.io / Railway
 
 `fly.toml` and `railway.toml` are included. Deploy with `fly deploy` or connect the repo to Railway.
@@ -182,7 +205,7 @@ fly secrets set CAMOFOX_API_KEY="your-generated-key"
 
 Route all browser traffic through a proxy with automatic locale, timezone, and geolocation derived from the proxy's IP address via Camoufox's built-in GeoIP.
 
-Set these environment variables before starting the server:
+**Simple proxy (single endpoint):**
 
 ```bash
 export PROXY_HOST=166.88.179.132
@@ -192,6 +215,21 @@ export PROXY_PASSWORD=mypass
 npm start
 ```
 
+**Backconnect proxy (rotating sticky sessions):**
+
+For providers like Decodo, Bright Data, or Oxylabs that offer a single gateway endpoint with session-based sticky IPs:
+
+```bash
+export PROXY_STRATEGY=backconnect
+export PROXY_BACKCONNECT_HOST=gate.provider.com
+export PROXY_BACKCONNECT_PORT=7000
+export PROXY_USERNAME=myuser
+export PROXY_PASSWORD=mypass
+npm start
+```
+
+Each browser context gets a unique sticky session, so different users get different IP addresses. Sessions rotate automatically on proxy errors or Google blocks.
+
 Or in Docker:
 
 ```bash
@@ -322,6 +360,7 @@ Reddit macros return JSON directly (no HTML parsing needed):
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `CAMOFOX_PORT` | Server port | `9377` |
+| `PORT` | Server port (fallback, for platforms like Fly.io) | `9377` |
 | `CAMOFOX_API_KEY` | Enable cookie import endpoint (disabled if unset) | - |
 | `CAMOFOX_ADMIN_KEY` | Required for `POST /stop` | - |
 | `CAMOFOX_COOKIES_DIR` | Directory for cookie files | `~/.camofox/cookies` |
@@ -332,10 +371,17 @@ Reddit macros return JSON directly (no HTML parsing needed):
 | `HANDLER_TIMEOUT_MS` | Max time for any handler | `30000` (30s) |
 | `MAX_CONCURRENT_PER_USER` | Concurrent request cap per user | `3` |
 | `MAX_OLD_SPACE_SIZE` | Node.js V8 heap limit (MB) | `128` |
-| `PROXY_HOST` | Proxy hostname or IP | - |
-| `PROXY_PORT` | Proxy port | - |
+| `PROXY_STRATEGY` | Proxy mode: `backconnect` (rotating sticky sessions) or blank (single endpoint) | - |
+| `PROXY_PROVIDER` | Provider name for session format (e.g. `decodo`) | `decodo` |
+| `PROXY_HOST` | Proxy hostname or IP (simple mode) | - |
+| `PROXY_PORT` | Proxy port (simple mode) | - |
 | `PROXY_USERNAME` | Proxy auth username | - |
 | `PROXY_PASSWORD` | Proxy auth password | - |
+| `PROXY_BACKCONNECT_HOST` | Backconnect gateway hostname | - |
+| `PROXY_BACKCONNECT_PORT` | Backconnect gateway port | `7000` |
+| `PROXY_COUNTRY` | Target country for proxy geo-targeting | - |
+| `PROXY_STATE` | Target state/region for proxy geo-targeting | - |
+| `TAB_INACTIVITY_MS` | Close tabs idle longer than this | `300000` (5min) |
 
 ## Architecture
 
@@ -351,6 +397,8 @@ Browser Instance (Camoufox)
 
 Sessions auto-expire after 30 minutes of inactivity. The browser itself shuts down after 5 minutes with no active sessions, and relaunches on the next request.
 
+When a session's tab limit is reached, the oldest/least-used tab is automatically recycled instead of returning an error — so long-running agent sessions don't hit dead ends.
+
 ## Testing
 
 ```bash

package/lib/config.js

@@ -8,10 +8,41 @@
 import { join } from 'path';
 import os from 'os';
 
+/**
+ * Parse PROXY_PORTS env var into an array of port numbers.
+ * Supports range ("10001-10010") or comma-separated ("10001,10002,10003").
+ * Falls back to single PROXY_PORT if PROXY_PORTS is not set.
+ */
+function parseProxyPorts(portsEnv, singlePort) {
+  if (portsEnv) {
+    if (portsEnv.includes('-')) {
+      const [start, end] = portsEnv.split('-').map(s => parseInt(s.trim(), 10));
+      if (!isNaN(start) && !isNaN(end) && end >= start) {
+        return Array.from({ length: end - start + 1 }, (_, i) => start + i);
+      }
+    }
+    const parsed = portsEnv.split(',').map(s => parseInt(s.trim(), 10)).filter(n => !isNaN(n));
+    if (parsed.length > 0) return parsed;
+  }
+  if (singlePort) {
+    const p = parseInt(singlePort, 10);
+    if (!isNaN(p)) return [p];
+  }
+  return [];
+}
+
+function inferProxyStrategy(explicitStrategy) {
+  if (explicitStrategy) return explicitStrategy;
+  return 'round_robin';
+}
+
 function loadConfig() {
   return {
     port: parseInt(process.env.CAMOFOX_PORT || process.env.PORT || '9377', 10),
     nodeEnv: process.env.NODE_ENV || 'development',
+    flyMachineId: process.env.FLY_MACHINE_ID || '',
+    flyAppName: process.env.FLY_APP_NAME || '',
+    flyApiToken: process.env.FLY_API_TOKEN || '',
     adminKey: process.env.CAMOFOX_ADMIN_KEY || '',
     apiKey: process.env.CAMOFOX_API_KEY || '',
     cookiesDir: process.env.CAMOFOX_COOKIES_DIR || join(os.homedir(), '.camofox', 'cookies'),
@@ -21,15 +52,26 @@ function loadConfig() {
     tabInactivityMs: parseInt(process.env.TAB_INACTIVITY_MS) || 300000,
     maxSessions: parseInt(process.env.MAX_SESSIONS) || 50,
     maxTabsPerSession: parseInt(process.env.MAX_TABS_PER_SESSION) || 10,
-    maxTabsGlobal: parseInt(process.env.MAX_TABS_GLOBAL) || 10,
+    maxTabsGlobal: parseInt(process.env.MAX_TABS_GLOBAL) || 50,
     navigateTimeoutMs: parseInt(process.env.NAVIGATE_TIMEOUT_MS) || 25000,
     buildrefsTimeoutMs: parseInt(process.env.BUILDREFS_TIMEOUT_MS) || 12000,
     browserIdleTimeoutMs: parseInt(process.env.BROWSER_IDLE_TIMEOUT_MS) || 300000,
+    prometheusEnabled: process.env.PROMETHEUS_ENABLED === '1' || process.env.PROMETHEUS_ENABLED === 'true',
     proxy: {
+      strategy: inferProxyStrategy(process.env.PROXY_STRATEGY || ''),
+      providerName: process.env.PROXY_PROVIDER || 'decodo',
       host: process.env.PROXY_HOST || '',
       port: process.env.PROXY_PORT || '',
+      ports: parseProxyPorts(process.env.PROXY_PORTS, process.env.PROXY_PORT),
       username: process.env.PROXY_USERNAME || '',
       password: process.env.PROXY_PASSWORD || '',
+      backconnectHost: process.env.PROXY_BACKCONNECT_HOST || '',
+      backconnectPort: parseInt(process.env.PROXY_BACKCONNECT_PORT || '7000', 10),
+      country: process.env.PROXY_COUNTRY || '',
+      state: process.env.PROXY_STATE || '',
+      city: process.env.PROXY_CITY || '',
+      zip: process.env.PROXY_ZIP || '',
+      sessionDurationMinutes: parseInt(process.env.PROXY_SESSION_DURATION_MINUTES || '10', 10),
     },
     // Env vars forwarded to the server subprocess
     serverEnv: {
@@ -39,10 +81,20 @@ function loadConfig() {
       CAMOFOX_ADMIN_KEY: process.env.CAMOFOX_ADMIN_KEY,
       CAMOFOX_API_KEY: process.env.CAMOFOX_API_KEY,
       CAMOFOX_COOKIES_DIR: process.env.CAMOFOX_COOKIES_DIR,
+      PROXY_STRATEGY: process.env.PROXY_STRATEGY,
+      PROXY_PROVIDER: process.env.PROXY_PROVIDER,
       PROXY_HOST: process.env.PROXY_HOST,
       PROXY_PORT: process.env.PROXY_PORT,
+      PROXY_PORTS: process.env.PROXY_PORTS,
       PROXY_USERNAME: process.env.PROXY_USERNAME,
       PROXY_PASSWORD: process.env.PROXY_PASSWORD,
+      PROXY_BACKCONNECT_HOST: process.env.PROXY_BACKCONNECT_HOST,
+      PROXY_BACKCONNECT_PORT: process.env.PROXY_BACKCONNECT_PORT,
+      PROXY_COUNTRY: process.env.PROXY_COUNTRY,
+      PROXY_STATE: process.env.PROXY_STATE,
+      PROXY_CITY: process.env.PROXY_CITY,
+      PROXY_ZIP: process.env.PROXY_ZIP,
+      PROXY_SESSION_DURATION_MINUTES: process.env.PROXY_SESSION_DURATION_MINUTES,
     },
   };
 }

package/lib/downloads.js

@@ -149,85 +149,6 @@ async function getDownloadsList(tabState, { includeData = false, maxBytes = MAX_
   return downloads;
 }
 
-/**
- * In-page image extraction script for page.evaluate().
- * Returns image metadata and optionally inline data URLs.
- */
-async function extractPageImages(page, { includeData = false, maxBytes = MAX_DOWNLOAD_INLINE_BYTES, limit = 8 } = {}) {
-  return page.evaluate(
-    async ({ includeData, maxBytes, limit }) => {
-      const toDataUrl = (blob) =>
-        new Promise((resolve, reject) => {
-          const reader = new FileReader();
-          reader.onload = () => resolve(typeof reader.result === 'string' ? reader.result : '');
-          reader.onerror = () => reject(new Error('file_reader_failed'));
-          reader.readAsDataURL(blob);
-        });
-
-      const nodes = Array.from(document.querySelectorAll('img'));
-      const seen = new Set();
-      const candidates = [];
-
-      for (const node of nodes) {
-        const src = String(node.currentSrc || node.src || node.getAttribute('src') || '').trim();
-        if (!src || seen.has(src)) continue;
-        seen.add(src);
-        candidates.push({
-          src,
-          alt: String(node.alt || '').trim(),
-          width: Number(node.naturalWidth || node.width || 0) || undefined,
-          height: Number(node.naturalHeight || node.height || 0) || undefined,
-        });
-        if (candidates.length >= limit) break;
-      }
-
-      const results = [];
-      for (const image of candidates) {
-        const entry = { src: image.src, alt: image.alt, width: image.width, height: image.height };
-
-        if (includeData) {
-          try {
-            if (image.src.startsWith('data:')) {
-              const mimeMatch = image.src.match(/^data:([^;,]+)[;,]/i);
-              const isBase64 = /;base64,/i.test(image.src);
-              const payload = image.src.slice(image.src.indexOf(',') + 1);
-              const estimatedBytes = isBase64 ? Math.floor((payload.length * 3) / 4) : payload.length;
-              entry.mimeType = mimeMatch ? mimeMatch[1] : 'application/octet-stream';
-              entry.bytes = estimatedBytes;
-              if (estimatedBytes <= maxBytes) {
-                entry.dataUrl = image.src;
-              } else {
-                entry.dataSkipped = 'max_bytes_exceeded';
-              }
-            } else {
-              const response = await fetch(image.src, { credentials: 'include' });
-              if (response.ok) {
-                const blob = await response.blob();
-                entry.mimeType = blob.type || 'application/octet-stream';
-                entry.bytes = blob.size;
-                if (blob.size <= maxBytes) {
-                  entry.dataUrl = await toDataUrl(blob);
-                } else {
-                  entry.dataSkipped = 'max_bytes_exceeded';
-                }
-              } else {
-                entry.fetchError = `http_${response.status}`;
-              }
-            }
-          } catch (err) {
-            entry.fetchError = String(err?.message || err || 'image_fetch_failed');
-          }
-        }
-
-        results.push(entry);
-      }
-
-      return results;
-    },
-    { includeData, maxBytes, limit },
-  );
-}
-
 export {
   MAX_DOWNLOAD_INLINE_BYTES,
   sanitizeFilename,
@@ -236,5 +157,4 @@ export {
   clearSessionDownloads,
   attachDownloadListener,
   getDownloadsList,
-  extractPageImages,
 };

package/lib/fly.js

@@ -0,0 +1,54 @@
+/**
+ * Fly.io horizontal scaling helpers.
+ *
+ * Tab IDs encode the owning machine: "{machineId}_{uuid}"
+ * Requests for tabs on other machines get replayed via fly-replay header.
+ *
+ * When not running on Fly (no FLY_MACHINE_ID), all helpers are no-ops:
+ * makeTabId() returns a plain UUID and isLocalTab() always returns true.
+ */
+
+import crypto from 'crypto';
+
+export function createFlyHelpers(config) {
+  const machineId = config.flyMachineId || '';
+
+  function makeTabId() {
+    const uuid = crypto.randomUUID();
+    return machineId ? `${machineId}_${uuid}` : uuid;
+  }
+
+  function parseTabOwner(tabId) {
+    if (!machineId || !tabId) return null;
+    const idx = tabId.indexOf('_');
+    if (idx === -1) return null; // legacy tab ID (no machine prefix)
+    const candidate = tabId.slice(0, idx);
+    // Fly machine IDs are hex strings (14 chars). UUIDs start with 8 hex chars then '-'.
+    // If the candidate contains '-', it's a UUID segment, not a machine ID.
+    if (candidate.includes('-')) return null;
+    return candidate;
+  }
+
+  function isLocalTab(tabId) {
+    const owner = parseTabOwner(tabId);
+    return owner === null || owner === machineId;
+  }
+
+  /**
+   * Express middleware: replay requests for tabs owned by other machines.
+   * No-op when not running on Fly.
+   */
+  function replayMiddleware(log) {
+    return (req, res, next) => {
+      if (!machineId) return next();
+      const tabId = req.params.tabId;
+      if (!tabId || isLocalTab(tabId)) return next();
+      const owner = parseTabOwner(tabId);
+      log('info', 'fly-replay', { reqId: req.reqId, tabId, owner, self: machineId });
+      res.set('fly-replay', `instance=${owner}`);
+      res.status(307).send();
+    };
+  }
+
+  return { machineId, makeTabId, parseTabOwner, isLocalTab, replayMiddleware };
+}

package/lib/images.js

@@ -0,0 +1,88 @@
+/**
+ * In-page image extraction via Playwright page.evaluate().
+ *
+ * Separated from downloads.js to avoid OpenClaw scanner false positives
+ * (browser-side fetch inside page.evaluate + Node fs reads in same file).
+ */
+
+import { MAX_DOWNLOAD_INLINE_BYTES } from './downloads.js';
+
+/**
+ * Extract image metadata (and optionally inline data) from visible <img> elements.
+ */
+async function extractPageImages(page, { includeData = false, maxBytes = MAX_DOWNLOAD_INLINE_BYTES, limit = 8 } = {}) {
+  return page.evaluate(
+    async ({ includeData, maxBytes, limit }) => {
+      const toDataUrl = (blob) =>
+        new Promise((resolve, reject) => {
+          const reader = new FileReader();
+          reader.onload = () => resolve(typeof reader.result === 'string' ? reader.result : '');
+          reader.onerror = () => reject(new Error('file_reader_failed'));
+          reader.readAsDataURL(blob);
+        });
+
+      const nodes = Array.from(document.querySelectorAll('img'));
+      const seen = new Set();
+      const candidates = [];
+
+      for (const node of nodes) {
+        const src = String(node.currentSrc || node.src || node.getAttribute('src') || '').trim();
+        if (!src || seen.has(src)) continue;
+        seen.add(src);
+        candidates.push({
+          src,
+          alt: String(node.alt || '').trim(),
+          width: Number(node.naturalWidth || node.width || 0) || undefined,
+          height: Number(node.naturalHeight || node.height || 0) || undefined,
+        });
+        if (candidates.length >= limit) break;
+      }
+
+      const results = [];
+      for (const image of candidates) {
+        const entry = { src: image.src, alt: image.alt, width: image.width, height: image.height };
+
+        if (includeData) {
+          try {
+            if (image.src.startsWith('data:')) {
+              const mimeMatch = image.src.match(/^data:([^;,]+)[;,]/i);
+              const isBase64 = /;base64,/i.test(image.src);
+              const payload = image.src.slice(image.src.indexOf(',') + 1);
+              const estimatedBytes = isBase64 ? Math.floor((payload.length * 3) / 4) : payload.length;
+              entry.mimeType = mimeMatch ? mimeMatch[1] : 'application/octet-stream';
+              entry.bytes = estimatedBytes;
+              if (estimatedBytes <= maxBytes) {
+                entry.dataUrl = image.src;
+              } else {
+                entry.dataSkipped = 'max_bytes_exceeded';
+              }
+            } else {
+              const response = await fetch(image.src, { credentials: 'include' });
+              if (response.ok) {
+                const blob = await response.blob();
+                entry.mimeType = blob.type || 'application/octet-stream';
+                entry.bytes = blob.size;
+                if (blob.size <= maxBytes) {
+                  entry.dataUrl = await toDataUrl(blob);
+                } else {
+                  entry.dataSkipped = 'max_bytes_exceeded';
+                }
+              } else {
+                entry.fetchError = `http_${response.status}`;
+              }
+            }
+          } catch (err) {
+            entry.fetchError = String(err?.message || err || 'image_fetch_failed');
+          }
+        }
+
+        results.push(entry);
+      }
+
+      return results;
+    },
+    { includeData, maxBytes, limit },
+  );
+}
+
+export { extractPageImages };