@askjo/camofox-browser 1.4.0 → 1.5.0

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,25 @@ 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,
     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 +80,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/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/metrics.js

@@ -0,0 +1,168 @@
+// Prometheus metrics for camofox-browser.
+// Isolated in lib/ to keep process.env out of server.js (OpenClaw scanner rule).
+import client from 'prom-client';
+
+const register = new client.Registry();
+client.collectDefaultMetrics({ register });
+
+// --- Counters ---
+
+export const requestsTotal = new client.Counter({
+  name: 'camofox_requests_total',
+  help: 'Total HTTP requests by action and status',
+  labelNames: ['action', 'status'],
+  registers: [register],
+});
+
+export const tabLockTimeoutsTotal = new client.Counter({
+  name: 'camofox_tab_lock_timeouts_total',
+  help: 'Tab lock queue timeouts resulting in 503',
+  registers: [register],
+});
+
+export const failuresTotal = new client.Counter({
+  name: 'camofox_failures_total',
+  help: 'Total failures by type and action',
+  labelNames: ['type', 'action'],
+  registers: [register],
+});
+
+export const browserRestartsTotal = new client.Counter({
+  name: 'camofox_restarts_total',
+  help: 'Browser restarts by reason',
+  labelNames: ['reason'],
+  registers: [register],
+});
+
+export const tabsDestroyedTotal = new client.Counter({
+  name: 'camofox_tabs_destroyed_total',
+  help: 'Tabs force-destroyed by reason',
+  labelNames: ['reason'],
+  registers: [register],
+});
+
+export const sessionsExpiredTotal = new client.Counter({
+  name: 'camofox_sessions_expired_total',
+  help: 'Sessions expired due to inactivity',
+  registers: [register],
+});
+
+export const tabsReapedTotal = new client.Counter({
+  name: 'camofox_tabs_reaped_total',
+  help: 'Tabs reaped due to inactivity',
+  registers: [register],
+});
+
+export const tabsRecycledTotal = new client.Counter({
+  name: 'camofox_tabs_recycled_total',
+  help: 'Tabs recycled when tab limit reached',
+  registers: [register],
+});
+
+// --- Histograms ---
+
+export const requestDuration = new client.Histogram({
+  name: 'camofox_request_duration_seconds',
+  help: 'Request duration in seconds by action',
+  labelNames: ['action'],
+  buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60],
+  registers: [register],
+});
+
+export const pageLoadDuration = new client.Histogram({
+  name: 'camofox_page_load_duration_seconds',
+  help: 'Page load duration in seconds',
+  buckets: [0.5, 1, 2, 5, 10, 20, 30, 60],
+  registers: [register],
+});
+
+// --- Gauges ---
+
+export const activeTabsGauge = new client.Gauge({
+  name: 'camofox_active_tabs',
+  help: 'Current number of open browser tabs',
+  registers: [register],
+});
+
+export const tabLockQueueDepth = new client.Gauge({
+  name: 'camofox_tab_lock_queue_depth',
+  help: 'Current number of requests waiting for a tab lock',
+  registers: [register],
+});
+
+export const memoryUsageBytes = new client.Gauge({
+  name: 'camofox_memory_usage_bytes',
+  help: 'Process RSS memory usage in bytes',
+  registers: [register],
+});
+
+// Periodic memory reporter
+const MEMORY_INTERVAL_MS = 30_000;
+let memoryTimer = null;
+
+export function startMemoryReporter() {
+  if (memoryTimer) return;
+  const report = () => memoryUsageBytes.set(process.memoryUsage().rss);
+  report();
+  memoryTimer = setInterval(report, MEMORY_INTERVAL_MS);
+  memoryTimer.unref(); // don't keep process alive
+}
+
+export function stopMemoryReporter() {
+  if (memoryTimer) { clearInterval(memoryTimer); memoryTimer = null; }
+}
+
+// Helper: derive a short action name from Express route
+export function actionFromReq(req) {
+  const method = req.method;
+  const path = req.route?.path || req.path;
+  // POST /tabs -> create_tab, DELETE /tabs/:tabId -> delete_tab, etc.
+  if (path === '/tabs' && method === 'POST') return 'create_tab';
+  if (path === '/tabs/:tabId' && method === 'DELETE') return 'delete_tab';
+  if (path === '/tabs/group/:listItemId' && method === 'DELETE') return 'delete_tab_group';
+  if (path === '/sessions/:userId' && method === 'DELETE') return 'delete_session';
+  if (path === '/sessions/:userId/cookies' && method === 'POST') return 'set_cookies';
+  if (path === '/tabs/open' && method === 'POST') return 'open_url';
+  if (path === '/tabs' && method === 'GET') return 'list_tabs';
+  // /tabs/:tabId/<action>
+  const m = path.match(/^\/tabs\/:tabId\/(\w+)$/);
+  if (m) return m[1]; // navigate, snapshot, click, type, scroll, etc.
+  // legacy compat routes
+  if (['/start', '/stop', '/navigate', '/snapshot', '/act'].includes(path)) return path.slice(1);
+  if (path === '/youtube/transcript') return 'youtube_transcript';
+  if (path === '/health') return 'health';
+  if (path === '/metrics') return 'metrics';
+  return `${method.toLowerCase()}_${path.replace(/[/:]/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '')}`;
+}
+
+/**
+ * Classify an error into a failure type string for metrics labeling.
+ */
+export function classifyError(err) {
+  if (!err) return 'unknown';
+  const msg = err.message || '';
+
+  if (err.code === 'stale_refs' || err.name === 'StaleRefsError') return 'stale_refs';
+  if (msg === 'Tab lock queue timeout') return 'tab_lock_timeout';
+  if (msg === 'Tab destroyed') return 'tab_destroyed';
+  if (msg.includes('Target page, context or browser has been closed') ||
+      msg.includes('browser has been closed') ||
+      msg.includes('Context closed') ||
+      msg.includes('Browser closed')) return 'dead_context';
+  if (msg.includes('timed out after') ||
+      (msg.includes('Timeout') && msg.includes('exceeded'))) return 'timeout';
+  if (msg.includes('Maximum concurrent sessions')) return 'session_limit';
+  if (msg.includes('Maximum tabs per session') || msg.includes('Maximum global tabs')) return 'tab_limit';
+  if (msg.includes('concurrency limit reached')) return 'concurrency_limit';
+  if (msg.includes('NS_ERROR_PROXY') || msg.includes('proxy connection') ||
+      msg.includes('Proxy connection')) return 'proxy';
+  if (msg.includes('Browser launch timeout') || msg.includes('Failed to launch')) return 'browser_launch';
+  if (msg.includes('intercepts pointer events')) return 'click_intercepted';
+  if (msg.includes('not visible') || msg.includes('not an <input>')) return 'element_error';
+  if (msg.includes('Blocked URL scheme') || msg.includes('Invalid URL')) return 'invalid_url';
+  if (msg.includes('net::') || msg.includes('ERR_NAME') || msg.includes('ERR_CONNECTION')) return 'network';
+  if (msg.includes('Navigation failed') || msg.includes('ERR_ABORTED')) return 'nav_aborted';
+  return 'unknown';
+}
+
+export { register };