{"owner":"jo-inc","repo":"camofox-browser","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# camofox-browser Agent Guide\n\nHeadless browser automation server for AI agents. Run locally or deploy to any cloud provider.\n\n## Quick Start for Agents\n\n```bash\n# Install and start\nnpm install && npm start\n# Server runs on http://localhost:9377\n```\n\n## Core Workflow\n\n1. **Create a tab** -> Get `tabId`\n2. **Navigate** -> Go to URL or use search macro\n3. **Get snapshot** -> Receive page content with element refs (`e1`, `e2`, etc.)\n4. **Interact** -> Click/type using refs\n5. **Repeat** steps 3-4 as needed\n\n## API Reference\n\n### Create Tab\n```bash\nPOST /tabs\n{\"userId\": \"agent1\", \"sessionKey\": \"task1\", \"url\": \"https://example.com\"}\n```\nReturns: `{\"tabId\": \"abc123\", \"url\": \"...\", \"title\": \"...\"}`\n\n### Navigate\n```bash\nPOST /tabs/:tabId/navigate\n{\"userId\": \"agent1\", \"url\": \"https://google.com\"}\n# Or use macro:\n{\"userId\": \"agent1\", \"macro\": \"@google_search\", \"query\": \"weather today\"}\n```\n\n### Get Snapshot\n```bash\nGET /tabs/:tabId/snapshot?userId=agent1\n```\nReturns accessibility tree with refs:\n```\n[heading] Example Domain\n[paragraph] This domain is for use in examples.\n[link e1] More information...\n```\n\n### Click Element\n```bash\nPOST /tabs/:tabId/click\n{\"userId\": \"agent1\", \"ref\": \"e1\"}\n# Or CSS selector:\n{\"userId\": \"agent1\", \"selector\": \"button.submit\"}\n```\n\n### Type Text\n```bash\nPOST /tabs/:tabId/type\n{\"userId\": \"agent1\", \"ref\": \"e2\", \"text\": \"hello world\"}\n# Add enter: {\"userId\": \"agent1\", \"ref\": \"e2\", \"text\": \"search query\", \"pressEnter\": true}\n```\n\n### Scroll\n```bash\nPOST /tabs/:tabId/scroll\n{\"userId\": \"agent1\", \"direction\": \"down\", \"amount\": 500}\n```\n\n### Navigation\n```bash\nPOST /tabs/:tabId/back     {\"userId\": \"agent1\"}\nPOST /tabs/:tabId/forward  {\"userId\": \"agent1\"}\nPOST /tabs/:tabId/refresh  {\"userId\": \"agent1\"}\n```\n\n### Get Links\n```bash\nGET /tabs/:tabId/links?userId=agent1&limit=50\n```\n\n### Close Tab\n```bash\nDELETE /tabs/:tabId?userId=agent1\n```\n\n## Search Macros\n\nUse these instead of constructing URLs:\n\n| Macro | Site |\n|-------|------|\n| `@google_search` | Google |\n| `@youtube_search` | YouTube |\n| `@amazon_search` | Amazon |\n| `@reddit_search` | Reddit |\n| `@wikipedia_search` | Wikipedia |\n| `@twitter_search` | Twitter/X |\n| `@yelp_search` | Yelp |\n| `@linkedin_search` | LinkedIn |\n\n## Element Refs\n\nRefs like `e1`, `e2` are stable identifiers for page elements:\n\n1. Call `/snapshot` to get current refs\n2. Use ref in `/click` or `/type`\n3. Refs reset on navigation - get new snapshot after\n\n## Session Management\n\n- `userId` isolates cookies/storage between users\n- `sessionKey` groups tabs by conversation/task (legacy: `listItemId` also accepted)\n- Sessions timeout after 30 minutes of inactivity\n- Delete all user data: `DELETE /sessions/:userId`\n\n## Running Engines\n\n### Camoufox (Default)\n```bash\nnpm start\n# Or: ./run.sh\n```\nFirefox-based with anti-detection. Bypasses Google captcha.\n\n## Testing\n\n```bash\nnpm test                          # All tests (unit + e2e + plugin)\nnpm run test:plugins              # All plugin tests\nnpm run test:e2e                  # E2E tests\nnpm run test:live                 # Live Google tests\nnpm run test:debug                # With server output\nnpx jest plugins/youtube          # Single plugin's tests\n```\n\n## Docker\n\n```bash\ndocker build -t camofox-browser .\ndocker run -p 9377:9377 camofox-browser\n```\n\n## Key Files\n\n- `server.js` - Camoufox engine (routes + browser logic only -- NO `process.env` or `child_process`)\n- `lib/openapi.js` - OpenAPI spec generation via swagger-jsdoc + docs route setup\n- `lib/config.js` - All `process.env` reads centralized here\n- `plugins/youtube/youtube.js` - YouTube transcript extraction via yt-dlp (`child_process` isolated here)\n- `lib/launcher.js` - Subprocess spawning (`child_process` isolated here)\n- `lib/cookies.js` - Cookie file I/O\n- `lib/metrics.js` - Prometheus metrics (lazy-loaded, off by default -- set `PROMETHEUS_ENABLED=1`)\n- `lib/request-utils.js` - HTTP request classification helpers (`actionFromReq`, `classifyError`)\n- `lib/snapshot.js` - Accessibility tree snapshot\n- `lib/macros.js` - Search macro URL expansion\n- `lib/plugins.js` - Plugin loader and event bus\n- `lib/auth.js` - Shared auth middleware (API key / loopback)\n- `camofox.config.json` - Plugin configuration (which plugins to load)\n- `plugins/` - Plugin directory (loaded per camofox.config.json)\n- `plugins/youtube/` - Default plugin: YouTube transcript extraction\n- `scripts/install-plugin-deps.sh` - Installs plugin deps (apt.txt + post-install.sh)\n- `plugins/vnc/index.js` - VNC plugin routes (no `child_process` -- spawning isolated in `vnc-launcher.js`)\n- `plugins/vnc/vnc-launcher.js` - VNC process management (`child_process` isolated here)\n- `plugins/persistence/index.js` - Session persistence lifecycle hooks\n- `lib/persistence.js` - Atomic storage state read/write\n- `lib/inflight.js` - Inflight request coalescing\n- `lib/tmp-cleanup.js` - Orphaned temp file cleanup\n- `lib/reporter.js` - Crash/hang reporter with anonymization + GitHub App auth (see README \"Crash Reporter\" for setup)\n- `Dockerfile` - Production container with default plugin deps pre-installed\n\n## OpenAPI Spec (REQUIRED for route changes)\n\nThe API spec is auto-generated from `@openapi` JSDoc comments in `server.js` via [swagger-jsdoc](https://github.com/Surnet/swagger-jsdoc). It's served at `GET /openapi.json` (machine-readable) and `GET /docs` ([swagger-stripey](https://github.com/skyfallsin/swagger-stripey) three-panel UI).\n\n**When adding, modifying, or removing a route, you MUST update the `@openapi` JSDoc block above it.**\n\nEvery route handler in `server.js` has a JSDoc comment block directly above it like:\n\n```js\n/**\n * @openapi\n * /tabs/{tabId}/click:\n *   post:\n *     tags: [Interaction]\n *     summary: Click an element\n *     parameters:\n *       - name: tabId\n *         in: path\n *         required: true\n *         schema:\n *           type: string\n *     requestBody:\n *       required: true\n *       content:\n *         application/json:\n *           schema:\n *             type: object\n *             required: [userId]\n *             properties:\n *               userId:\n *                 type: string\n *               ref:\n *                 type: string\n *     responses:\n *       200:\n *         description: Click result.\n *         content:\n *           application/json:\n *             schema:\n *               type: object\n *       404:\n *         description: Tab not found.\n *         content:\n *           application/json:\n *             schema:\n *               $ref: '#/components/schemas/Error'\n */\napp.post('/tabs/:tabId/click', async (req, res) => {\n```\n\n**Rules:**\n- New routes: add a `@openapi` JSDoc block immediately above the `app.get/post/delete(...)` call\n- Path params use `{tabId}` syntax (not `:tabId`) in the JSDoc YAML\n- Tag must be one of: `System`, `Tabs`, `Navigation`, `Interaction`, `Content`, `Sessions`, `Browser`, `Legacy`\n- Every operation must have `tags`, `summary`, and `responses`\n- Include `requestBody` for POST/PUT/DELETE routes that accept JSON\n- Include `parameters` for path params and required query params\n- Mark backward-compat endpoints with `deprecated: true`\n- Removing a route: delete the `@openapi` block along with the handler\n- **After any route change, run `npm run generate-openapi`** to regenerate the committed `openapi.json`. The test suite will fail if it's stale.\n- Run `npx jest tests/unit/openapi.test.js` to verify coverage -- the test fails if any route is missing from the spec, if a stale route exists, or if `openapi.json` is out of date\n- Reusable schemas go in `components.schemas` in `lib/openapi.js` (the `swaggerDefinition`); reference them via `$ref: '#/components/schemas/Name'`\n\n## Telemetry\n\n**No credentials are embedded in this package.** `lib/reporter.js` is a stateless HTTP client that sends anonymized crash/hang telemetry to a Cloudflare Worker endpoint (`camofox-telemetry.askjo.workers.dev`). The endpoint holds the GitHub App credentials as environment secrets -- see `workers/crash-reporter/index.ts`. The source is in-repo and auditable.\n\n- **Architecture**: `lib/reporter.js` (client, no secrets, no `fs`) -> POST -> Cloudflare Worker endpoint -> GitHub Issues\n- **`lib/reporter.js`** has ZERO credentials, ZERO private keys, ZERO `fs` imports. It only does `fetch()` to the telemetry endpoint.\n- **`lib/resources.js`** handles `fs`-based resource snapshots (reading /proc on Linux) -- separated from reporter.js so no file-read + network-send pattern exists in any single file. No `child_process` import.\n- **Anonymization** is in `lib/reporter.js` L28-290 -- text scrubbing (`anonymize()`), URL anonymization (`createUrlAnonymizer()`), and tab health tracking (`createTabHealthTracker()`)\n- **Public domain list** (~120 entries) determines which domains are shown verbatim vs HMAC-hashed\n- **Tests**: `tests/unit/crashRelay.test.js` (telemetry client), `tests/unit/crashRelayWorker.test.js` (worker contract), `tests/unit/noSecrets.test.js` (asserts no key material in shipped files)\n- Self-hosted endpoint: see README \"Self-hosted telemetry endpoint\" section\n- Disable with `CAMOFOX_CRASH_REPORT_ENABLED=false`\n\n## Code Separation Conventions\n\nThe codebase separates concerns across files for clarity and auditability:\n\n- **Configuration**: `process.env` reads live in `lib/config.js`, which exports a plain config object. No other file reads environment variables directly.\n- **Subprocess management**: `child_process` usage lives in dedicated launcher modules (`lib/launcher.js`, `plugins/youtube/youtube.js`, `plugins/vnc/vnc-launcher.js`), not in route handlers.\n- **Route handlers**: `server.js` defines Express routes but delegates env/config reads and subprocess spawning to the modules above.\n- **Metrics**: `lib/metrics.js` lazy-loads prom-client. `lib/request-utils.js` handles HTTP method classification.\n\nWhen adding features that need env vars or subprocesses, put that code in a `lib/` module and import the result into `server.js`.\n\n## Plugin System\n\nPlugins extend camofox-browser with new endpoints, background processes, and lifecycle hooks. The server auto-loads all plugins from `plugins/<name>/index.js` on startup.\n\n### Creating a Plugin\n\n```\nplugins/\n  my-plugin/\n    index.js        Required -- exports register(app, ctx)\n    apt.txt         Optional -- system packages (one per line)\n    post-install.sh Optional -- executable hook for binary downloads\n    *.test.js       Optional -- Jest tests (auto-discovered)\n```\n\n```js\n// plugins/my-plugin/index.js\n\nexport function register(app, ctx) {\n  const { sessions, config, log, events, auth, ensureBrowser, getSession, destroySession,\n          withUserLimit, safePageClose, normalizeUserId, validateUrl, safeError,\n          buildProxyUrl, proxyPool, failuresTotal } = ctx;\n\n  // Register Express routes (auth() enforces API key or loopback)\n  app.get('/my-endpoint', auth(), async (req, res) => {\n    const session = sessions.get(req.params.userId);\n    res.json({ ok: true });\n  });\n\n  // Listen to lifecycle events\n  events.on('browser:launched', ({ browser, display }) => {\n    log('info', 'browser is up', { display });\n  });\n\n  events.on('session:created', ({ userId, context }) => {\n    log('info', 'new session', { userId });\n  });\n\n  events.on('tab:navigated', ({ userId, tabId, url }) => {\n    log('info', 'navigation', { userId, tabId, url });\n  });\n}\n```\n\n### Plugin Context (`ctx`)\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `sessions` | `Map` | Live sessions: `userId -> { context, tabGroups, lastAccess }` |\n| `config` | `object` | Server CONFIG (port, apiKey, nodeEnv, proxy, etc.) |\n| `log` | `function` | `log(level, msg, fields)` -- structured JSON logging |\n| `events` | `EventEmitter` | Plugin event bus (29 events -- see below) |\n| `auth` | `function` | `auth()` returns Express middleware enforcing API key / loopback |\n| `ensureBrowser` | `async function` | Launch browser if not running, return browser instance |\n| `getSession` | `async function` | `getSession(userId)` -- get or create a session |\n| `destroySession` | `async function` | `destroySession(userId, { reason })` -- tear down and await a session close |\n| `withUserLimit` | `async function` | `withUserLimit(userId, fn)` -- run `fn` within per-user concurrency limit |\n| `safePageClose` | `async function` | `safePageClose(page)` -- close a page with timeout guard |\n| `normalizeUserId` | `function` | `normalizeUserId(id)` -- coerce to string for map keys |\n| `validateUrl` | `function` | `validateUrl(url)` -- returns error string or null |\n| `safeError` | `function` | `safeError(err)` -- sanitize error for client response |\n| `buildProxyUrl` | `function` | `buildProxyUrl(pool, proxyConfig)` -- get proxy URL for external requests |\n| `proxyPool` | `object\\|null` | Proxy pool instance (null if no proxy configured) |\n| `failuresTotal` | `Counter` | Prometheus counter: `failuresTotal.labels(type, action).inc()` |\n| `createMetric` | `async function` | Create a Prometheus metric registered to the shared registry (see below) |\n| `metricsRegistry` | `function` | `metricsRegistry()` -- raw prom-client Registry or null |\n\n### Events (29)\n\n28 emitted by core, 1 (`session:storage:export`) emitted by plugins.\n\n#### Browser Lifecycle\n| Event | Payload | Mutating? |\n|-------|---------|-----------|\n| `browser:launching` | `{ options }` | (ok) Modify launch options in-place |\n| `browser:launched` | `{ browser, display }` | |\n| `browser:restart` | `{ reason }` | |\n| `browser:closed` | `{ reason }` | |\n| `browser:error` | `{ error }` | |\n\n#### Session Lifecycle\n| Event | Payload | Mutating? |\n|-------|---------|-----------|\n| `session:creating` | `{ userId, contextOptions }` | (ok) Modify context options in-place |\n| `session:created` | `{ userId, context }` | |\n| `session:destroyed` | `{ userId, reason }` | |\n| `session:expired` | `{ userId, idleMs }` | |\n\n#### Tab Lifecycle\n| Event | Payload |\n|-------|---------|\n| `tab:created` | `{ userId, tabId, page, url }` |\n| `tab:navigated` | `{ userId, tabId, url, prevUrl }` |\n| `tab:destroyed` | `{ userId, tabId, reason }` |\n| `tab:recycled` | `{ userId, tabId }` |\n| `tab:error` | `{ userId, tabId, error }` |\n\n#### Content\n| Event | Payload |\n|-------|---------|\n| `tab:snapshot` | `{ userId, tabId, snapshot }` |\n| `tab:screenshot` | `{ userId, tabId, buffer }` |\n| `tab:evaluate` | `{ userId, tabId, expression }` |\n| `tab:evaluated` | `{ userId, tabId, result }` |\n\n#### Input\n| Event | Payload |\n|-------|---------|\n| `tab:click` | `{ userId, tabId, ref, selector }` |\n| `tab:type` | `{ userId, tabId, text, ref, mode }` |\n| `tab:scroll` | `{ userId, tabId, direction, amount }` |\n| `tab:press` | `{ userId, tabId, key }` |\n\n#### Downloads\n| Event | Payload |\n|-------|---------|\n| `tab:download:start` | `{ userId, tabId, filename, url }` |\n| `tab:download:complete` | `{ userId, tabId, filename, path, size }` |\n\n#### Cookies / Auth\n| Event | Payload |\n|-------|---------|\n| `session:cookies:import` | `{ userId, count }` |\n| `session:storage:export` | `{ userId, storageState }` |\n\n#### Server\n| Event | Payload |\n|-------|---------|\n| `server:starting` | `{ port }` |\n| `server:started` | `{ port, pid }` |\n| `server:shutdown` | `{ signal }` |\n\n### Mutating Hooks\n\n`browser:launching`, `session:creating`, `session:created`, and `session:destroyed` are emitted via `events.emitAsync()` -- the server awaits all listeners (including async ones) before proceeding. This ensures async work like loading storage state from disk completes before the context is created.\n\nOther events use regular `events.emit()` (fire-and-forget).\n\nModify payload objects in-place:\n\n```js\n// Change Xvfb resolution (e.g., for VNC plugin)\nevents.on('browser:launching', ({ options }) => {\n  options.virtual_display_resolution = '1920x1080x24';\n});\n\n// Inject saved auth state into new sessions\nevents.on('session:creating', ({ userId, contextOptions }) => {\n  const saved = loadStorageState(userId);\n  if (saved) contextOptions.storageState = saved;\n});\n```\n\n### System Packages (`apt.txt`) and Post-Install Hooks\n\nPlugins that need system packages list them one per line in `apt.txt`:\n\n```\n# plugins/vnc/apt.txt\nx11vnc\nnovnc\npython3-websockify\n```\n\nFor binary downloads or setup not available via apt, add an executable `post-install.sh`:\n\n```bash\n# plugins/youtube/post-install.sh\n#!/bin/sh\nset -e\ncurl -fL https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp\nchmod +x /usr/local/bin/yt-dlp\n```\n\nBoth are run by `scripts/install-plugin-deps.sh` during Docker build.\n\n### Configuration (`camofox.config.json`)\n\n`camofox.config.json` controls which plugins are loaded at runtime and during Docker build:\n\n```json\n{\n  \"id\": \"camofox-browser\",\n  \"name\": \"Camofox Browser\",\n  \"version\": \"1.5.2\",\n  \"plugins\": [\"youtube\"]\n}\n```\n\n- **`plugins`** -- array of plugin directory names to load. Only these are loaded at startup and have deps installed during build.\n- If the file is missing or has no `plugins` key, **all** plugins in `plugins/` are loaded (backward-compatible).\n- This is camofox's own config. `openclaw.plugin.json` is separate -- it tells the OpenClaw Gateway how to configure camofox as an external service.\n\n### Installing Plugins\n\nUse the plugin manager to install third-party plugins from git or local paths:\n\n```bash\n# Install from git\nnpm run plugin install https://github.com/user/camofox-screenshot-plugin\nnpm run plugin install git:github.com/user/my-plugin\n\n# Install from local directory\nnpm run plugin install ./path/to/my-plugin\n\n# List installed plugins\nnpm run plugin list\n\n# Remove a plugin\nnpm run plugin remove my-plugin\n```\n\nThe installer copies the plugin into `plugins/`, adds it to `camofox.config.json`, and runs `npm install` for any npm dependencies. System deps (`apt.txt`, `post-install.sh`) are flagged but must be installed manually or via Docker rebuild.\n\nPlugin sources can be:\n- **Git repos** where the root has `index.js` with `register()` (installed as one plugin)\n- **Git repos** with a `plugins/` subdirectory (each subdirectory installed as a separate plugin)\n- **Local directories** with `index.js` and `register()`\n\n### Default Plugins\n\nThree plugins ship by default:\n\n- **youtube** -- YouTube transcript extraction (enabled by default)\n- **persistence** -- Per-user session state persistence to `~/.camofox/profiles/` (enabled by default)\n- **vnc** -- Interactive browser login via noVNC (disabled by default, requires `ENABLE_VNC=1`)\n\nThe `youtube` plugin ships as a default plugin -- it's listed in `camofox.config.json` and included in the base Docker image with its deps pre-installed. The base image runs `scripts/install-plugin-deps.sh` which reads the config and installs `apt.txt` packages + `post-install.sh` hooks for listed plugins.\n\nThe `with-plugins` Dockerfile stage is for rebuilding after adding third-party plugins:\n\n```bash\ndocker build --target with-plugins -t camofox-browser .\n```\n\nThe `with-plugins` stage re-runs `install-plugin-deps.sh` to pick up any new plugins added to `plugins/`.\n\n### Code Separation Rules\n\nPlugins follow the same separation conventions as core (see \"Code Separation Conventions\" above):\n- **No `process.env` in plugin files that also have route handlers** -- read config from `ctx.config`\n- **No `child_process` in plugin files that also have route handlers** -- spawn from a separate `lib/` module\n\n### Custom Metrics\n\nPlugins create Prometheus metrics via `ctx.createMetric()`. Returns a no-op stub when Prometheus is disabled -- no null checks needed.\n\n```js\n// In register(app, ctx):\nconst transcriptsTotal = await ctx.createMetric('counter', {\n  name: 'camofox_youtube_transcripts_total',\n  help: 'YouTube transcripts extracted',\n  labelNames: ['method'],\n});\n\n// Use anywhere -- works whether Prometheus is enabled or not\ntranscriptsTotal.labels('yt-dlp').inc();\n```\n\nSupported types: `'counter'`, `'histogram'`, `'gauge'`. Options are standard [prom-client](https://github.com/siimon/prom-client) options (`name`, `help`, `labelNames`, `buckets`, etc.). Metrics auto-register to the shared registry and appear on `/metrics`.\n\nFor advanced use, `ctx.metricsRegistry()` returns the raw prom-client `Registry` (or `null` when disabled).\n\n### Example: YouTube Transcript Plugin\n\nThe YouTube plugin (`plugins/youtube/`) is the reference implementation. It extracts transcripts via yt-dlp with browser fallback, using `ctx` helpers for auth, logging, browser access, and concurrency control.\n\n```\nplugins/\n  youtube/\n    index.js        # register(app, ctx) -- route handler + browser fallback\n    youtube.js      # yt-dlp process management + transcript parsing\n    youtube.test.js # parser unit tests\n    apt.txt         # python3-minimal (yt-dlp runtime dep)\n    post-install.sh # downloads yt-dlp binary\n```\n\n```js\n// plugins/youtube/index.js (simplified)\nimport { detectYtDlp, hasYtDlp, ensureYtDlp, ytDlpTranscript } from './youtube.js';\nimport { classifyError } from '../../lib/request-utils.js';\n\nexport async function register(app, ctx) {\n  const { log, config, sessions, ensureBrowser, getSession,\n          withUserLimit, safePageClose, normalizeUserId,\n          validateUrl, safeError, buildProxyUrl, proxyPool,\n          failuresTotal } = ctx;\n\n  await detectYtDlp(log);\n\n  app.post('/youtube/transcript', ctx.auth(), async (req, res) => {\n    // ... validate URL, extract videoId, try yt-dlp then browser fallback\n  });\n\n  async function browserTranscript(reqId, url, videoId, lang) {\n    return await withUserLimit('__yt_transcript__', async () => {\n      await ensureBrowser();\n      const session = await getSession('__yt_transcript__');\n      const page = await session.context.newPage();\n      // ... intercept captions, parse transcript\n      await safePageClose(page);\n    });\n  }\n}\n```\n\nKey patterns:\n- **Auth**: `ctx.auth()` middleware on the route\n- **Logging**: `ctx.log('info', ...)` -- never `console.log`\n- **Browser access**: `ctx.ensureBrowser()` + `ctx.getSession()` for browser-backed features\n- **Concurrency**: `ctx.withUserLimit()` to respect per-user limits\n- **Metrics**: `ctx.failuresTotal.labels(...)` for core counters, `ctx.createMetric()` for custom\n- **Code separation**: `child_process` in `youtube.js`, route handler in `index.js` -- separate files\n- **System deps**: `apt.txt` lists packages installed via `scripts/install-plugin-deps.sh`\n"},"files":{"AGENTS.md":"# camofox-browser Agent Guide\n\nHeadless browser automation server for AI agents. Run locally or deploy to any cloud provider.\n\n## Quick Start for Agents\n\n```bash\n# Install and start\nnpm install && npm start\n# Server runs on http://localhost:9377\n```\n\n## Core Workflow\n\n1. **Create a tab** -> Get `tabId`\n2. **Navigate** -> Go to URL or use search macro\n3. **Get snapshot** -> Receive page content with element refs (`e1`, `e2`, etc.)\n4. **Interact** -> Click/type using refs\n5. **Repeat** steps 3-4 as needed\n\n## API Reference\n\n### Create Tab\n```bash\nPOST /tabs\n{\"userId\": \"agent1\", \"sessionKey\": \"task1\", \"url\": \"https://example.com\"}\n```\nReturns: `{\"tabId\": \"abc123\", \"url\": \"...\", \"title\": \"...\"}`\n\n### Navigate\n```bash\nPOST /tabs/:tabId/navigate\n{\"userId\": \"agent1\", \"url\": \"https://google.com\"}\n# Or use macro:\n{\"userId\": \"agent1\", \"macro\": \"@google_search\", \"query\": \"weather today\"}\n```\n\n### Get Snapshot\n```bash\nGET /tabs/:tabId/snapshot?userId=agent1\n```\nReturns accessibility tree with refs:\n```\n[heading] Example Domain\n[paragraph] This domain is for use in examples.\n[link e1] More information...\n```\n\n### Click Element\n```bash\nPOST /tabs/:tabId/click\n{\"userId\": \"agent1\", \"ref\": \"e1\"}\n# Or CSS selector:\n{\"userId\": \"agent1\", \"selector\": \"button.submit\"}\n```\n\n### Type Text\n```bash\nPOST /tabs/:tabId/type\n{\"userId\": \"agent1\", \"ref\": \"e2\", \"text\": \"hello world\"}\n# Add enter: {\"userId\": \"agent1\", \"ref\": \"e2\", \"text\": \"search query\", \"pressEnter\": true}\n```\n\n### Scroll\n```bash\nPOST /tabs/:tabId/scroll\n{\"userId\": \"agent1\", \"direction\": \"down\", \"amount\": 500}\n```\n\n### Navigation\n```bash\nPOST /tabs/:tabId/back     {\"userId\": \"agent1\"}\nPOST /tabs/:tabId/forward  {\"userId\": \"agent1\"}\nPOST /tabs/:tabId/refresh  {\"userId\": \"agent1\"}\n```\n\n### Get Links\n```bash\nGET /tabs/:tabId/links?userId=agent1&limit=50\n```\n\n### Close Tab\n```bash\nDELETE /tabs/:tabId?userId=agent1\n```\n\n## Search Macros\n\nUse these instead of constructing URLs:\n\n| Macro | Site |\n|-------|------|\n| `@google_search` | Google |\n| `@youtube_search` | YouTube |\n| `@amazon_search` | Amazon |\n| `@reddit_search` | Reddit |\n| `@wikipedia_search` | Wikipedia |\n| `@twitter_search` | Twitter/X |\n| `@yelp_search` | Yelp |\n| `@linkedin_search` | LinkedIn |\n\n## Element Refs\n\nRefs like `e1`, `e2` are stable identifiers for page elements:\n\n1. Call `/snapshot` to get current refs\n2. Use ref in `/click` or `/type`\n3. Refs reset on navigation - get new snapshot after\n\n## Session Management\n\n- `userId` isolates cookies/storage between users\n- `sessionKey` groups tabs by conversation/task (legacy: `listItemId` also accepted)\n- Sessions timeout after 30 minutes of inactivity\n- Delete all user data: `DELETE /sessions/:userId`\n\n## Running Engines\n\n### Camoufox (Default)\n```bash\nnpm start\n# Or: ./run.sh\n```\nFirefox-based with anti-detection. Bypasses Google captcha.\n\n## Testing\n\n```bash\nnpm test                          # All tests (unit + e2e + plugin)\nnpm run test:plugins              # All plugin tests\nnpm run test:e2e                  # E2E tests\nnpm run test:live                 # Live Google tests\nnpm run test:debug                # With server output\nnpx jest plugins/youtube          # Single plugin's tests\n```\n\n## Docker\n\n```bash\ndocker build -t camofox-browser .\ndocker run -p 9377:9377 camofox-browser\n```\n\n## Key Files\n\n- `server.js` - Camoufox engine (routes + browser logic only -- NO `process.env` or `child_process`)\n- `lib/openapi.js` - OpenAPI spec generation via swagger-jsdoc + docs route setup\n- `lib/config.js` - All `process.env` reads centralized here\n- `plugins/youtube/youtube.js` - YouTube transcript extraction via yt-dlp (`child_process` isolated here)\n- `lib/launcher.js` - Subprocess spawning (`child_process` isolated here)\n- `lib/cookies.js` - Cookie file I/O\n- `lib/metrics.js` - Prometheus metrics (lazy-loaded, off by default -- set `PROMETHEUS_ENABLED=1`)\n- `lib/request-utils.js` - HTTP request classification helpers (`actionFromReq`, `classifyError`)\n- `lib/snapshot.js` - Accessibility tree snapshot\n- `lib/macros.js` - Search macro URL expansion\n- `lib/plugins.js` - Plugin loader and event bus\n- `lib/auth.js` - Shared auth middleware (API key / loopback)\n- `camofox.config.json` - Plugin configuration (which plugins to load)\n- `plugins/` - Plugin directory (loaded per camofox.config.json)\n- `plugins/youtube/` - Default plugin: YouTube transcript extraction\n- `scripts/install-plugin-deps.sh` - Installs plugin deps (apt.txt + post-install.sh)\n- `plugins/vnc/index.js` - VNC plugin routes (no `child_process` -- spawning isolated in `vnc-launcher.js`)\n- `plugins/vnc/vnc-launcher.js` - VNC process management (`child_process` isolated here)\n- `plugins/persistence/index.js` - Session persistence lifecycle hooks\n- `lib/persistence.js` - Atomic storage state read/write\n- `lib/inflight.js` - Inflight request coalescing\n- `lib/tmp-cleanup.js` - Orphaned temp file cleanup\n- `lib/reporter.js` - Crash/hang reporter with anonymization + GitHub App auth (see README \"Crash Reporter\" for setup)\n- `Dockerfile` - Production container with default plugin deps pre-installed\n\n## OpenAPI Spec (REQUIRED for route changes)\n\nThe API spec is auto-generated from `@openapi` JSDoc comments in `server.js` via [swagger-jsdoc](https://github.com/Surnet/swagger-jsdoc). It's served at `GET /openapi.json` (machine-readable) and `GET /docs` ([swagger-stripey](https://github.com/skyfallsin/swagger-stripey) three-panel UI).\n\n**When adding, modifying, or removing a route, you MUST update the `@openapi` JSDoc block above it.**\n\nEvery route handler in `server.js` has a JSDoc comment block directly above it like:\n\n```js\n/**\n * @openapi\n * /tabs/{tabId}/click:\n *   post:\n *     tags: [Interaction]\n *     summary: Click an element\n *     parameters:\n *       - name: tabId\n *         in: path\n *         required: true\n *         schema:\n *           type: string\n *     requestBody:\n *       required: true\n *       content:\n *         application/json:\n *           schema:\n *             type: object\n *             required: [userId]\n *             properties:\n *               userId:\n *                 type: string\n *               ref:\n *                 type: string\n *     responses:\n *       200:\n *         description: Click result.\n *         content:\n *           application/json:\n *             schema:\n *               type: object\n *       404:\n *         description: Tab not found.\n *         content:\n *           application/json:\n *             schema:\n *               $ref: '#/components/schemas/Error'\n */\napp.post('/tabs/:tabId/click', async (req, res) => {\n```\n\n**Rules:**\n- New routes: add a `@openapi` JSDoc block immediately above the `app.get/post/delete(...)` call\n- Path params use `{tabId}` syntax (not `:tabId`) in the JSDoc YAML\n- Tag must be one of: `System`, `Tabs`, `Navigation`, `Interaction`, `Content`, `Sessions`, `Browser`, `Legacy`\n- Every operation must have `tags`, `summary`, and `responses`\n- Include `requestBody` for POST/PUT/DELETE routes that accept JSON\n- Include `parameters` for path params and required query params\n- Mark backward-compat endpoints with `deprecated: true`\n- Removing a route: delete the `@openapi` block along with the handler\n- **After any route change, run `npm run generate-openapi`** to regenerate the committed `openapi.json`. The test suite will fail if it's stale.\n- Run `npx jest tests/unit/openapi.test.js` to verify coverage -- the test fails if any route is missing from the spec, if a stale route exists, or if `openapi.json` is out of date\n- Reusable schemas go in `components.schemas` in `lib/openapi.js` (the `swaggerDefinition`); reference them via `$ref: '#/components/schemas/Name'`\n\n## Telemetry\n\n**No credentials are embedded in this package.** `lib/reporter.js` is a stateless HTTP client that sends anonymized crash/hang telemetry to a Cloudflare Worker endpoint (`camofox-telemetry.askjo.workers.dev`). The endpoint holds the GitHub App credentials as environment secrets -- see `workers/crash-reporter/index.ts`. The source is in-repo and auditable.\n\n- **Architecture**: `lib/reporter.js` (client, no secrets, no `fs`) -> POST -> Cloudflare Worker endpoint -> GitHub Issues\n- **`lib/reporter.js`** has ZERO credentials, ZERO private keys, ZERO `fs` imports. It only does `fetch()` to the telemetry endpoint.\n- **`lib/resources.js`** handles `fs`-based resource snapshots (reading /proc on Linux) -- separated from reporter.js so no file-read + network-send pattern exists in any single file. No `child_process` import.\n- **Anonymization** is in `lib/reporter.js` L28-290 -- text scrubbing (`anonymize()`), URL anonymization (`createUrlAnonymizer()`), and tab health tracking (`createTabHealthTracker()`)\n- **Public domain list** (~120 entries) determines which domains are shown verbatim vs HMAC-hashed\n- **Tests**: `tests/unit/crashRelay.test.js` (telemetry client), `tests/unit/crashRelayWorker.test.js` (worker contract), `tests/unit/noSecrets.test.js` (asserts no key material in shipped files)\n- Self-hosted endpoint: see README \"Self-hosted telemetry endpoint\" section\n- Disable with `CAMOFOX_CRASH_REPORT_ENABLED=false`\n\n## Code Separation Conventions\n\nThe codebase separates concerns across files for clarity and auditability:\n\n- **Configuration**: `process.env` reads live in `lib/config.js`, which exports a plain config object. No other file reads environment variables directly.\n- **Subprocess management**: `child_process` usage lives in dedicated launcher modules (`lib/launcher.js`, `plugins/youtube/youtube.js`, `plugins/vnc/vnc-launcher.js`), not in route handlers.\n- **Route handlers**: `server.js` defines Express routes but delegates env/config reads and subprocess spawning to the modules above.\n- **Metrics**: `lib/metrics.js` lazy-loads prom-client. `lib/request-utils.js` handles HTTP method classification.\n\nWhen adding features that need env vars or subprocesses, put that code in a `lib/` module and import the result into `server.js`.\n\n## Plugin System\n\nPlugins extend camofox-browser with new endpoints, background processes, and lifecycle hooks. The server auto-loads all plugins from `plugins/<name>/index.js` on startup.\n\n### Creating a Plugin\n\n```\nplugins/\n  my-plugin/\n    index.js        Required -- exports register(app, ctx)\n    apt.txt         Optional -- system packages (one per line)\n    post-install.sh Optional -- executable hook for binary downloads\n    *.test.js       Optional -- Jest tests (auto-discovered)\n```\n\n```js\n// plugins/my-plugin/index.js\n\nexport function register(app, ctx) {\n  const { sessions, config, log, events, auth, ensureBrowser, getSession, destroySession,\n          withUserLimit, safePageClose, normalizeUserId, validateUrl, safeError,\n          buildProxyUrl, proxyPool, failuresTotal } = ctx;\n\n  // Register Express routes (auth() enforces API key or loopback)\n  app.get('/my-endpoint', auth(), async (req, res) => {\n    const session = sessions.get(req.params.userId);\n    res.json({ ok: true });\n  });\n\n  // Listen to lifecycle events\n  events.on('browser:launched', ({ browser, display }) => {\n    log('info', 'browser is up', { display });\n  });\n\n  events.on('session:created', ({ userId, context }) => {\n    log('info', 'new session', { userId });\n  });\n\n  events.on('tab:navigated', ({ userId, tabId, url }) => {\n    log('info', 'navigation', { userId, tabId, url });\n  });\n}\n```\n\n### Plugin Context (`ctx`)\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `sessions` | `Map` | Live sessions: `userId -> { context, tabGroups, lastAccess }` |\n| `config` | `object` | Server CONFIG (port, apiKey, nodeEnv, proxy, etc.) |\n| `log` | `function` | `log(level, msg, fields)` -- structured JSON logging |\n| `events` | `EventEmitter` | Plugin event bus (29 events -- see below) |\n| `auth` | `function` | `auth()` returns Express middleware enforcing API key / loopback |\n| `ensureBrowser` | `async function` | Launch browser if not running, return browser instance |\n| `getSession` | `async function` | `getSession(userId)` -- get or create a session |\n| `destroySession` | `async function` | `destroySession(userId, { reason })` -- tear down and await a session close |\n| `withUserLimit` | `async function` | `withUserLimit(userId, fn)` -- run `fn` within per-user concurrency limit |\n| `safePageClose` | `async function` | `safePageClose(page)` -- close a page with timeout guard |\n| `normalizeUserId` | `function` | `normalizeUserId(id)` -- coerce to string for map keys |\n| `validateUrl` | `function` | `validateUrl(url)` -- returns error string or null |\n| `safeError` | `function` | `safeError(err)` -- sanitize error for client response |\n| `buildProxyUrl` | `function` | `buildProxyUrl(pool, proxyConfig)` -- get proxy URL for external requests |\n| `proxyPool` | `object\\|null` | Proxy pool instance (null if no proxy configured) |\n| `failuresTotal` | `Counter` | Prometheus counter: `failuresTotal.labels(type, action).inc()` |\n| `createMetric` | `async function` | Create a Prometheus metric registered to the shared registry (see below) |\n| `metricsRegistry` | `function` | `metricsRegistry()` -- raw prom-client Registry or null |\n\n### Events (29)\n\n28 emitted by core, 1 (`session:storage:export`) emitted by plugins.\n\n#### Browser Lifecycle\n| Event | Payload | Mutating? |\n|-------|---------|-----------|\n| `browser:launching` | `{ options }` | (ok) Modify launch options in-place |\n| `browser:launched` | `{ browser, display }` | |\n| `browser:restart` | `{ reason }` | |\n| `browser:closed` | `{ reason }` | |\n| `browser:error` | `{ error }` | |\n\n#### Session Lifecycle\n| Event | Payload | Mutating? |\n|-------|---------|-----------|\n| `session:creating` | `{ userId, contextOptions }` | (ok) Modify context options in-place |\n| `session:created` | `{ userId, context }` | |\n| `session:destroyed` | `{ userId, reason }` | |\n| `session:expired` | `{ userId, idleMs }` | |\n\n#### Tab Lifecycle\n| Event | Payload |\n|-------|---------|\n| `tab:created` | `{ userId, tabId, page, url }` |\n| `tab:navigated` | `{ userId, tabId, url, prevUrl }` |\n| `tab:destroyed` | `{ userId, tabId, reason }` |\n| `tab:recycled` | `{ userId, tabId }` |\n| `tab:error` | `{ userId, tabId, error }` |\n\n#### Content\n| Event | Payload |\n|-------|---------|\n| `tab:snapshot` | `{ userId, tabId, snapshot }` |\n| `tab:screenshot` | `{ userId, tabId, buffer }` |\n| `tab:evaluate` | `{ userId, tabId, expression }` |\n| `tab:evaluated` | `{ userId, tabId, result }` |\n\n#### Input\n| Event | Payload |\n|-------|---------|\n| `tab:click` | `{ userId, tabId, ref, selector }` |\n| `tab:type` | `{ userId, tabId, text, ref, mode }` |\n| `tab:scroll` | `{ userId, tabId, direction, amount }` |\n| `tab:press` | `{ userId, tabId, key }` |\n\n#### Downloads\n| Event | Payload |\n|-------|---------|\n| `tab:download:start` | `{ userId, tabId, filename, url }` |\n| `tab:download:complete` | `{ userId, tabId, filename, path, size }` |\n\n#### Cookies / Auth\n| Event | Payload |\n|-------|---------|\n| `session:cookies:import` | `{ userId, count }` |\n| `session:storage:export` | `{ userId, storageState }` |\n\n#### Server\n| Event | Payload |\n|-------|---------|\n| `server:starting` | `{ port }` |\n| `server:started` | `{ port, pid }` |\n| `server:shutdown` | `{ signal }` |\n\n### Mutating Hooks\n\n`browser:launching`, `session:creating`, `session:created`, and `session:destroyed` are emitted via `events.emitAsync()` -- the server awaits all listeners (including async ones) before proceeding. This ensures async work like loading storage state from disk completes before the context is created.\n\nOther events use regular `events.emit()` (fire-and-forget).\n\nModify payload objects in-place:\n\n```js\n// Change Xvfb resolution (e.g., for VNC plugin)\nevents.on('browser:launching', ({ options }) => {\n  options.virtual_display_resolution = '1920x1080x24';\n});\n\n// Inject saved auth state into new sessions\nevents.on('session:creating', ({ userId, contextOptions }) => {\n  const saved = loadStorageState(userId);\n  if (saved) contextOptions.storageState = saved;\n});\n```\n\n### System Packages (`apt.txt`) and Post-Install Hooks\n\nPlugins that need system packages list them one per line in `apt.txt`:\n\n```\n# plugins/vnc/apt.txt\nx11vnc\nnovnc\npython3-websockify\n```\n\nFor binary downloads or setup not available via apt, add an executable `post-install.sh`:\n\n```bash\n# plugins/youtube/post-install.sh\n#!/bin/sh\nset -e\ncurl -fL https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp\nchmod +x /usr/local/bin/yt-dlp\n```\n\nBoth are run by `scripts/install-plugin-deps.sh` during Docker build.\n\n### Configuration (`camofox.config.json`)\n\n`camofox.config.json` controls which plugins are loaded at runtime and during Docker build:\n\n```json\n{\n  \"id\": \"camofox-browser\",\n  \"name\": \"Camofox Browser\",\n  \"version\": \"1.5.2\",\n  \"plugins\": [\"youtube\"]\n}\n```\n\n- **`plugins`** -- array of plugin directory names to load. Only these are loaded at startup and have deps installed during build.\n- If the file is missing or has no `plugins` key, **all** plugins in `plugins/` are loaded (backward-compatible).\n- This is camofox's own config. `openclaw.plugin.json` is separate -- it tells the OpenClaw Gateway how to configure camofox as an external service.\n\n### Installing Plugins\n\nUse the plugin manager to install third-party plugins from git or local paths:\n\n```bash\n# Install from git\nnpm run plugin install https://github.com/user/camofox-screenshot-plugin\nnpm run plugin install git:github.com/user/my-plugin\n\n# Install from local directory\nnpm run plugin install ./path/to/my-plugin\n\n# List installed plugins\nnpm run plugin list\n\n# Remove a plugin\nnpm run plugin remove my-plugin\n```\n\nThe installer copies the plugin into `plugins/`, adds it to `camofox.config.json`, and runs `npm install` for any npm dependencies. System deps (`apt.txt`, `post-install.sh`) are flagged but must be installed manually or via Docker rebuild.\n\nPlugin sources can be:\n- **Git repos** where the root has `index.js` with `register()` (installed as one plugin)\n- **Git repos** with a `plugins/` subdirectory (each subdirectory installed as a separate plugin)\n- **Local directories** with `index.js` and `register()`\n\n### Default Plugins\n\nThree plugins ship by default:\n\n- **youtube** -- YouTube transcript extraction (enabled by default)\n- **persistence** -- Per-user session state persistence to `~/.camofox/profiles/` (enabled by default)\n- **vnc** -- Interactive browser login via noVNC (disabled by default, requires `ENABLE_VNC=1`)\n\nThe `youtube` plugin ships as a default plugin -- it's listed in `camofox.config.json` and included in the base Docker image with its deps pre-installed. The base image runs `scripts/install-plugin-deps.sh` which reads the config and installs `apt.txt` packages + `post-install.sh` hooks for listed plugins.\n\nThe `with-plugins` Dockerfile stage is for rebuilding after adding third-party plugins:\n\n```bash\ndocker build --target with-plugins -t camofox-browser .\n```\n\nThe `with-plugins` stage re-runs `install-plugin-deps.sh` to pick up any new plugins added to `plugins/`.\n\n### Code Separation Rules\n\nPlugins follow the same separation conventions as core (see \"Code Separation Conventions\" above):\n- **No `process.env` in plugin files that also have route handlers** -- read config from `ctx.config`\n- **No `child_process` in plugin files that also have route handlers** -- spawn from a separate `lib/` module\n\n### Custom Metrics\n\nPlugins create Prometheus metrics via `ctx.createMetric()`. Returns a no-op stub when Prometheus is disabled -- no null checks needed.\n\n```js\n// In register(app, ctx):\nconst transcriptsTotal = await ctx.createMetric('counter', {\n  name: 'camofox_youtube_transcripts_total',\n  help: 'YouTube transcripts extracted',\n  labelNames: ['method'],\n});\n\n// Use anywhere -- works whether Prometheus is enabled or not\ntranscriptsTotal.labels('yt-dlp').inc();\n```\n\nSupported types: `'counter'`, `'histogram'`, `'gauge'`. Options are standard [prom-client](https://github.com/siimon/prom-client) options (`name`, `help`, `labelNames`, `buckets`, etc.). Metrics auto-register to the shared registry and appear on `/metrics`.\n\nFor advanced use, `ctx.metricsRegistry()` returns the raw prom-client `Registry` (or `null` when disabled).\n\n### Example: YouTube Transcript Plugin\n\nThe YouTube plugin (`plugins/youtube/`) is the reference implementation. It extracts transcripts via yt-dlp with browser fallback, using `ctx` helpers for auth, logging, browser access, and concurrency control.\n\n```\nplugins/\n  youtube/\n    index.js        # register(app, ctx) -- route handler + browser fallback\n    youtube.js      # yt-dlp process management + transcript parsing\n    youtube.test.js # parser unit tests\n    apt.txt         # python3-minimal (yt-dlp runtime dep)\n    post-install.sh # downloads yt-dlp binary\n```\n\n```js\n// plugins/youtube/index.js (simplified)\nimport { detectYtDlp, hasYtDlp, ensureYtDlp, ytDlpTranscript } from './youtube.js';\nimport { classifyError } from '../../lib/request-utils.js';\n\nexport async function register(app, ctx) {\n  const { log, config, sessions, ensureBrowser, getSession,\n          withUserLimit, safePageClose, normalizeUserId,\n          validateUrl, safeError, buildProxyUrl, proxyPool,\n          failuresTotal } = ctx;\n\n  await detectYtDlp(log);\n\n  app.post('/youtube/transcript', ctx.auth(), async (req, res) => {\n    // ... validate URL, extract videoId, try yt-dlp then browser fallback\n  });\n\n  async function browserTranscript(reqId, url, videoId, lang) {\n    return await withUserLimit('__yt_transcript__', async () => {\n      await ensureBrowser();\n      const session = await getSession('__yt_transcript__');\n      const page = await session.context.newPage();\n      // ... intercept captions, parse transcript\n      await safePageClose(page);\n    });\n  }\n}\n```\n\nKey patterns:\n- **Auth**: `ctx.auth()` middleware on the route\n- **Logging**: `ctx.log('info', ...)` -- never `console.log`\n- **Browser access**: `ctx.ensureBrowser()` + `ctx.getSession()` for browser-backed features\n- **Concurrency**: `ctx.withUserLimit()` to respect per-user limits\n- **Metrics**: `ctx.failuresTotal.labels(...)` for core counters, `ctx.createMetric()` for custom\n- **Code separation**: `child_process` in `youtube.js`, route handler in `index.js` -- separate files\n- **System deps**: `apt.txt` lists packages installed via `scripts/install-plugin-deps.sh`\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# camofox-browser Agent Guide\n\nHeadless browser automation server for AI agents. Run locally or deploy to any cloud provider.\n\n## Quick Start for Agents\n\n```bash\n# Install and start\nnpm install && npm start\n# Server runs on http://localhost:9377\n```\n\n## Core Workflow\n\n1. **Create a tab** -> Get `tabId`\n2. **Navigate** -> Go to URL or use search macro\n3. **Get snapshot** -> Receive page content with element refs (`e1`, `e2`, etc.)\n4. **Interact** -> Click/type using refs\n5. **Repeat** steps 3-4 as needed\n\n## API Reference\n\n### Create Tab\n```bash\nPOST /tabs\n{\"userId\": \"agent1\", \"sessionKey\": \"task1\", \"url\": \"https://example.com\"}\n```\nReturns: `{\"tabId\": \"abc123\", \"url\": \"...\", \"title\": \"...\"}`\n\n### Navigate\n```bash\nPOST /tabs/:tabId/navigate\n{\"userId\": \"agent1\", \"url\": \"https://google.com\"}\n# Or use macro:\n{\"userId\": \"agent1\", \"macro\": \"@google_search\", \"query\": \"weather today\"}\n```\n\n### Get Snapshot\n```bash\nGET /tabs/:tabId/snapshot?userId=agent1\n```\nReturns accessibility tree with refs:\n```\n[heading] Example Domain\n[paragraph] This domain is for use in examples.\n[link e1] More information...\n```\n\n### Click Element\n```bash\nPOST /tabs/:tabId/click\n{\"userId\": \"agent1\", \"ref\": \"e1\"}\n# Or CSS selector:\n{\"userId\": \"agent1\", \"selector\": \"button.submit\"}\n```\n\n### Type Text\n```bash\nPOST /tabs/:tabId/type\n{\"userId\": \"agent1\", \"ref\": \"e2\", \"text\": \"hello world\"}\n# Add enter: {\"userId\": \"agent1\", \"ref\": \"e2\", \"text\": \"search query\", \"pressEnter\": true}\n```\n\n### Scroll\n```bash\nPOST /tabs/:tabId/scroll\n{\"userId\": \"agent1\", \"direction\": \"down\", \"amount\": 500}\n```\n\n### Navigation\n```bash\nPOST /tabs/:tabId/back     {\"userId\": \"agent1\"}\nPOST /tabs/:tabId/forward  {\"userId\": \"agent1\"}\nPOST /tabs/:tabId/refresh  {\"userId\": \"agent1\"}\n```\n\n### Get Links\n```bash\nGET /tabs/:tabId/links?userId=agent1&limit=50\n```\n\n### Close Tab\n```bash\nDELETE /tabs/:tabId?userId=agent1\n```\n\n## Search Macros\n\nUse these instead of constructing URLs:\n\n| Macro | Site |\n|-------|------|\n| `@google_search` | Google |\n| `@youtube_search` | YouTube |\n| `@amazon_search` | Amazon |\n| `@reddit_search` | Reddit |\n| `@wikipedia_search` | Wikipedia |\n| `@twitter_search` | Twitter/X |\n| `@yelp_search` | Yelp |\n| `@linkedin_search` | LinkedIn |\n\n## Element Refs\n\nRefs like `e1`, `e2` are stable identifiers for page elements:\n\n1. Call `/snapshot` to get current refs\n2. Use ref in `/click` or `/type`\n3. Refs reset on navigation - get new snapshot after\n\n## Session Management\n\n- `userId` isolates cookies/storage between users\n- `sessionKey` groups tabs by conversation/task (legacy: `listItemId` also accepted)\n- Sessions timeout after 30 minutes of inactivity\n- Delete all user data: `DELETE /sessions/:userId`\n\n## Running Engines\n\n### Camoufox (Default)\n```bash\nnpm start\n# Or: ./run.sh\n```\nFirefox-based with anti-detection. Bypasses Google captcha.\n\n## Testing\n\n```bash\nnpm test                          # All tests (unit + e2e + plugin)\nnpm run test:plugins              # All plugin tests\nnpm run test:e2e                  # E2E tests\nnpm run test:live                 # Live Google tests\nnpm run test:debug                # With server output\nnpx jest plugins/youtube          # Single plugin's tests\n```\n\n## Docker\n\n```bash\ndocker build -t camofox-browser .\ndocker run -p 9377:9377 camofox-browser\n```\n\n## Key Files\n\n- `server.js` - Camoufox engine (routes + browser logic only -- NO `process.env` or `child_process`)\n- `lib/openapi.js` - OpenAPI spec generation via swagger-jsdoc + docs route setup\n- `lib/config.js` - All `process.env` reads centralized here\n- `plugins/youtube/youtube.js` - YouTube transcript extraction via yt-dlp (`child_process` isolated here)\n- `lib/launcher.js` - Subprocess spawning (`child_process` isolated here)\n- `lib/cookies.js` - Cookie file I/O\n- `lib/metrics.js` - Prometheus metrics (lazy-loaded, off by default -- set `PROMETHEUS_ENABLED=1`)\n- `lib/request-utils.js` - HTTP request classification helpers (`actionFromReq`, `classifyError`)\n- `lib/snapshot.js` - Accessibility tree snapshot\n- `lib/macros.js` - Search macro URL expansion\n- `lib/plugins.js` - Plugin loader and event bus\n- `lib/auth.js` - Shared auth middleware (API key / loopback)\n- `camofox.config.json` - Plugin configuration (which plugins to load)\n- `plugins/` - Plugin directory (loaded per camofox.config.json)\n- `plugins/youtube/` - Default plugin: YouTube transcript extraction\n- `scripts/install-plugin-deps.sh` - Installs plugin deps (apt.txt + post-install.sh)\n- `plugins/vnc/index.js` - VNC plugin routes (no `child_process` -- spawning isolated in `vnc-launcher.js`)\n- `plugins/vnc/vnc-launcher.js` - VNC process management (`child_process` isolated here)\n- `plugins/persistence/index.js` - Session persistence lifecycle hooks\n- `lib/persistence.js` - Atomic storage state read/write\n- `lib/inflight.js` - Inflight request coalescing\n- `lib/tmp-cleanup.js` - Orphaned temp file cleanup\n- `lib/reporter.js` - Crash/hang reporter with anonymization + GitHub App auth (see README \"Crash Reporter\" for setup)\n- `Dockerfile` - Production container with default plugin deps pre-installed\n\n## OpenAPI Spec (REQUIRED for route changes)\n\nThe API spec is auto-generated from `@openapi` JSDoc comments in `server.js` via [swagger-jsdoc](https://github.com/Surnet/swagger-jsdoc). It's served at `GET /openapi.json` (machine-readable) and `GET /docs` ([swagger-stripey](https://github.com/skyfallsin/swagger-stripey) three-panel UI).\n\n**When adding, modifying, or removing a route, you MUST update the `@openapi` JSDoc block above it.**\n\nEvery route handler in `server.js` has a JSDoc comment block directly above it like:\n\n```js\n/**\n * @openapi\n * /tabs/{tabId}/click:\n *   post:\n *     tags: [Interaction]\n *     summary: Click an element\n *     parameters:\n *       - name: tabId\n *         in: path\n *         required: true\n *         schema:\n *           type: string\n *     requestBody:\n *       required: true\n *       content:\n *         application/json:\n *           schema:\n *             type: object\n *             required: [userId]\n *             properties:\n *               userId:\n *                 type: string\n *               ref:\n *                 type: string\n *     responses:\n *       200:\n *         description: Click result.\n *         content:\n *           application/json:\n *             schema:\n *               type: object\n *       404:\n *         description: Tab not found.\n *         content:\n *           application/json:\n *             schema:\n *               $ref: '#/components/schemas/Error'\n */\napp.post('/tabs/:tabId/click', async (req, res) => {\n```\n\n**Rules:**\n- New routes: add a `@openapi` JSDoc block immediately above the `app.get/post/delete(...)` call\n- Path params use `{tabId}` syntax (not `:tabId`) in the JSDoc YAML\n- Tag must be one of: `System`, `Tabs`, `Navigation`, `Interaction`, `Content`, `Sessions`, `Browser`, `Legacy`\n- Every operation must have `tags`, `summary`, and `responses`\n- Include `requestBody` for POST/PUT/DELETE routes that accept JSON\n- Include `parameters` for path params and required query params\n- Mark backward-compat endpoints with `deprecated: true`\n- Removing a route: delete the `@openapi` block along with the handler\n- **After any route change, run `npm run generate-openapi`** to regenerate the committed `openapi.json`. The test suite will fail if it's stale.\n- Run `npx jest tests/unit/openapi.test.js` to verify coverage -- the test fails if any route is missing from the spec, if a stale route exists, or if `openapi.json` is out of date\n- Reusable schemas go in `components.schemas` in `lib/openapi.js` (the `swaggerDefinition`); reference them via `$ref: '#/components/schemas/Name'`\n\n## Telemetry\n\n**No credentials are embedded in this package.** `lib/reporter.js` is a stateless HTTP client that sends anonymized crash/hang telemetry to a Cloudflare Worker endpoint (`camofox-telemetry.askjo.workers.dev`). The endpoint holds the GitHub App credentials as environment secrets -- see `workers/crash-reporter/index.ts`. The source is in-repo and auditable.\n\n- **Architecture**: `lib/reporter.js` (client, no secrets, no `fs`) -> POST -> Cloudflare Worker endpoint -> GitHub Issues\n- **`lib/reporter.js`** has ZERO credentials, ZERO private keys, ZERO `fs` imports. It only does `fetch()` to the telemetry endpoint.\n- **`lib/resources.js`** handles `fs`-based resource snapshots (reading /proc on Linux) -- separated from reporter.js so no file-read + network-send pattern exists in any single file. No `child_process` import.\n- **Anonymization** is in `lib/reporter.js` L28-290 -- text scrubbing (`anonymize()`), URL anonymization (`createUrlAnonymizer()`), and tab health tracking (`createTabHealthTracker()`)\n- **Public domain list** (~120 entries) determines which domains are shown verbatim vs HMAC-hashed\n- **Tests**: `tests/unit/crashRelay.test.js` (telemetry client), `tests/unit/crashRelayWorker.test.js` (worker contract), `tests/unit/noSecrets.test.js` (asserts no key material in shipped files)\n- Self-hosted endpoint: see README \"Self-hosted telemetry endpoint\" section\n- Disable with `CAMOFOX_CRASH_REPORT_ENABLED=false`\n\n## Code Separation Conventions\n\nThe codebase separates concerns across files for clarity and auditability:\n\n- **Configuration**: `process.env` reads live in `lib/config.js`, which exports a plain config object. No other file reads environment variables directly.\n- **Subprocess management**: `child_process` usage lives in dedicated launcher modules (`lib/launcher.js`, `plugins/youtube/youtube.js`, `plugins/vnc/vnc-launcher.js`), not in route handlers.\n- **Route handlers**: `server.js` defines Express routes but delegates env/config reads and subprocess spawning to the modules above.\n- **Metrics**: `lib/metrics.js` lazy-loads prom-client. `lib/request-utils.js` handles HTTP method classification.\n\nWhen adding features that need env vars or subprocesses, put that code in a `lib/` module and import the result into `server.js`.\n\n## Plugin System\n\nPlugins extend camofox-browser with new endpoints, background processes, and lifecycle hooks. The server auto-loads all plugins from `plugins/<name>/index.js` on startup.\n\n### Creating a Plugin\n\n```\nplugins/\n  my-plugin/\n    index.js        Required -- exports register(app, ctx)\n    apt.txt         Optional -- system packages (one per line)\n    post-install.sh Optional -- executable hook for binary downloads\n    *.test.js       Optional -- Jest tests (auto-discovered)\n```\n\n```js\n// plugins/my-plugin/index.js\n\nexport function register(app, ctx) {\n  const { sessions, config, log, events, auth, ensureBrowser, getSession, destroySession,\n          withUserLimit, safePageClose, normalizeUserId, validateUrl, safeError,\n          buildProxyUrl, proxyPool, failuresTotal } = ctx;\n\n  // Register Express routes (auth() enforces API key or loopback)\n  app.get('/my-endpoint', auth(), async (req, res) => {\n    const session = sessions.get(req.params.userId);\n    res.json({ ok: true });\n  });\n\n  // Listen to lifecycle events\n  events.on('browser:launched', ({ browser, display }) => {\n    log('info', 'browser is up', { display });\n  });\n\n  events.on('session:created', ({ userId, context }) => {\n    log('info', 'new session', { userId });\n  });\n\n  events.on('tab:navigated', ({ userId, tabId, url }) => {\n    log('info', 'navigation', { userId, tabId, url });\n  });\n}\n```\n\n### Plugin Context (`ctx`)\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `sessions` | `Map` | Live sessions: `userId -> { context, tabGroups, lastAccess }` |\n| `config` | `object` | Server CONFIG (port, apiKey, nodeEnv, proxy, etc.) |\n| `log` | `function` | `log(level, msg, fields)` -- structured JSON logging |\n| `events` | `EventEmitter` | Plugin event bus (29 events -- see below) |\n| `auth` | `function` | `auth()` returns Express middleware enforcing API key / loopback |\n| `ensureBrowser` | `async function` | Launch browser if not running, return browser instance |\n| `getSession` | `async function` | `getSession(userId)` -- get or create a session |\n| `destroySession` | `async function` | `destroySession(userId, { reason })` -- tear down and await a session close |\n| `withUserLimit` | `async function` | `withUserLimit(userId, fn)` -- run `fn` within per-user concurrency limit |\n| `safePageClose` | `async function` | `safePageClose(page)` -- close a page with timeout guard |\n| `normalizeUserId` | `function` | `normalizeUserId(id)` -- coerce to string for map keys |\n| `validateUrl` | `function` | `validateUrl(url)` -- returns error string or null |\n| `safeError` | `function` | `safeError(err)` -- sanitize error for client response |\n| `buildProxyUrl` | `function` | `buildProxyUrl(pool, proxyConfig)` -- get proxy URL for external requests |\n| `proxyPool` | `object\\|null` | Proxy pool instance (null if no proxy configured) |\n| `failuresTotal` | `Counter` | Prometheus counter: `failuresTotal.labels(type, action).inc()` |\n| `createMetric` | `async function` | Create a Prometheus metric registered to the shared registry (see below) |\n| `metricsRegistry` | `function` | `metricsRegistry()` -- raw prom-client Registry or null |\n\n### Events (29)\n\n28 emitted by core, 1 (`session:storage:export`) emitted by plugins.\n\n#### Browser Lifecycle\n| Event | Payload | Mutating? |\n|-------|---------|-----------|\n| `browser:launching` | `{ options }` | (ok) Modify launch options in-place |\n| `browser:launched` | `{ browser, display }` | |\n| `browser:restart` | `{ reason }` | |\n| `browser:closed` | `{ reason }` | |\n| `browser:error` | `{ error }` | |\n\n#### Session Lifecycle\n| Event | Payload | Mutating? |\n|-------|---------|-----------|\n| `session:creating` | `{ userId, contextOptions }` | (ok) Modify context options in-place |\n| `session:created` | `{ userId, context }` | |\n| `session:destroyed` | `{ userId, reason }` | |\n| `session:expired` | `{ userId, idleMs }` | |\n\n#### Tab Lifecycle\n| Event | Payload |\n|-------|---------|\n| `tab:created` | `{ userId, tabId, page, url }` |\n| `tab:navigated` | `{ userId, tabId, url, prevUrl }` |\n| `tab:destroyed` | `{ userId, tabId, reason }` |\n| `tab:recycled` | `{ userId, tabId }` |\n| `tab:error` | `{ userId, tabId, error }` |\n\n#### Content\n| Event | Payload |\n|-------|---------|\n| `tab:snapshot` | `{ userId, tabId, snapshot }` |\n| `tab:screenshot` | `{ userId, tabId, buffer }` |\n| `tab:evaluate` | `{ userId, tabId, expression }` |\n| `tab:evaluated` | `{ userId, tabId, result }` |\n\n#### Input\n| Event | Payload |\n|-------|---------|\n| `tab:click` | `{ userId, tabId, ref, selector }` |\n| `tab:type` | `{ userId, tabId, text, ref, mode }` |\n| `tab:scroll` | `{ userId, tabId, direction, amount }` |\n| `tab:press` | `{ userId, tabId, key }` |\n\n#### Downloads\n| Event | Payload |\n|-------|---------|\n| `tab:download:start` | `{ userId, tabId, filename, url }` |\n| `tab:download:complete` | `{ userId, tabId, filename, path, size }` |\n\n#### Cookies / Auth\n| Event | Payload |\n|-------|---------|\n| `session:cookies:import` | `{ userId, count }` |\n| `session:storage:export` | `{ userId, storageState }` |\n\n#### Server\n| Event | Payload |\n|-------|---------|\n| `server:starting` | `{ port }` |\n| `server:started` | `{ port, pid }` |\n| `server:shutdown` | `{ signal }` |\n\n### Mutating Hooks\n\n`browser:launching`, `session:creating`, `session:created`, and `session:destroyed` are emitted via `events.emitAsync()` -- the server awaits all listeners (including async ones) before proceeding. This ensures async work like loading storage state from disk completes before the context is created.\n\nOther events use regular `events.emit()` (fire-and-forget).\n\nModify payload objects in-place:\n\n```js\n// Change Xvfb resolution (e.g., for VNC plugin)\nevents.on('browser:launching', ({ options }) => {\n  options.virtual_display_resolution = '1920x1080x24';\n});\n\n// Inject saved auth state into new sessions\nevents.on('session:creating', ({ userId, contextOptions }) => {\n  const saved = loadStorageState(userId);\n  if (saved) contextOptions.storageState = saved;\n});\n```\n\n### System Packages (`apt.txt`) and Post-Install Hooks\n\nPlugins that need system packages list them one per line in `apt.txt`:\n\n```\n# plugins/vnc/apt.txt\nx11vnc\nnovnc\npython3-websockify\n```\n\nFor binary downloads or setup not available via apt, add an executable `post-install.sh`:\n\n```bash\n# plugins/youtube/post-install.sh\n#!/bin/sh\nset -e\ncurl -fL https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp\nchmod +x /usr/local/bin/yt-dlp\n```\n\nBoth are run by `scripts/install-plugin-deps.sh` during Docker build.\n\n### Configuration (`camofox.config.json`)\n\n`camofox.config.json` controls which plugins are loaded at runtime and during Docker build:\n\n```json\n{\n  \"id\": \"camofox-browser\",\n  \"name\": \"Camofox Browser\",\n  \"version\": \"1.5.2\",\n  \"plugins\": [\"youtube\"]\n}\n```\n\n- **`plugins`** -- array of plugin directory names to load. Only these are loaded at startup and have deps installed during build.\n- If the file is missing or has no `plugins` key, **all** plugins in `plugins/` are loaded (backward-compatible).\n- This is camofox's own config. `openclaw.plugin.json` is separate -- it tells the OpenClaw Gateway how to configure camofox as an external service.\n\n### Installing Plugins\n\nUse the plugin manager to install third-party plugins from git or local paths:\n\n```bash\n# Install from git\nnpm run plugin install https://github.com/user/camofox-screenshot-plugin\nnpm run plugin install git:github.com/user/my-plugin\n\n# Install from local directory\nnpm run plugin install ./path/to/my-plugin\n\n# List installed plugins\nnpm run plugin list\n\n# Remove a plugin\nnpm run plugin remove my-plugin\n```\n\nThe installer copies the plugin into `plugins/`, adds it to `camofox.config.json`, and runs `npm install` for any npm dependencies. System deps (`apt.txt`, `post-install.sh`) are flagged but must be installed manually or via Docker rebuild.\n\nPlugin sources can be:\n- **Git repos** where the root has `index.js` with `register()` (installed as one plugin)\n- **Git repos** with a `plugins/` subdirectory (each subdirectory installed as a separate plugin)\n- **Local directories** with `index.js` and `register()`\n\n### Default Plugins\n\nThree plugins ship by default:\n\n- **youtube** -- YouTube transcript extraction (enabled by default)\n- **persistence** -- Per-user session state persistence to `~/.camofox/profiles/` (enabled by default)\n- **vnc** -- Interactive browser login via noVNC (disabled by default, requires `ENABLE_VNC=1`)\n\nThe `youtube` plugin ships as a default plugin -- it's listed in `camofox.config.json` and included in the base Docker image with its deps pre-installed. The base image runs `scripts/install-plugin-deps.sh` which reads the config and installs `apt.txt` packages + `post-install.sh` hooks for listed plugins.\n\nThe `with-plugins` Dockerfile stage is for rebuilding after adding third-party plugins:\n\n```bash\ndocker build --target with-plugins -t camofox-browser .\n```\n\nThe `with-plugins` stage re-runs `install-plugin-deps.sh` to pick up any new plugins added to `plugins/`.\n\n### Code Separation Rules\n\nPlugins follow the same separation conventions as core (see \"Code Separation Conventions\" above):\n- **No `process.env` in plugin files that also have route handlers** -- read config from `ctx.config`\n- **No `child_process` in plugin files that also have route handlers** -- spawn from a separate `lib/` module\n\n### Custom Metrics\n\nPlugins create Prometheus metrics via `ctx.createMetric()`. Returns a no-op stub when Prometheus is disabled -- no null checks needed.\n\n```js\n// In register(app, ctx):\nconst transcriptsTotal = await ctx.createMetric('counter', {\n  name: 'camofox_youtube_transcripts_total',\n  help: 'YouTube transcripts extracted',\n  labelNames: ['method'],\n});\n\n// Use anywhere -- works whether Prometheus is enabled or not\ntranscriptsTotal.labels('yt-dlp').inc();\n```\n\nSupported types: `'counter'`, `'histogram'`, `'gauge'`. Options are standard [prom-client](https://github.com/siimon/prom-client) options (`name`, `help`, `labelNames`, `buckets`, etc.). Metrics auto-register to the shared registry and appear on `/metrics`.\n\nFor advanced use, `ctx.metricsRegistry()` returns the raw prom-client `Registry` (or `null` when disabled).\n\n### Example: YouTube Transcript Plugin\n\nThe YouTube plugin (`plugins/youtube/`) is the reference implementation. It extracts transcripts via yt-dlp with browser fallback, using `ctx` helpers for auth, logging, browser access, and concurrency control.\n\n```\nplugins/\n  youtube/\n    index.js        # register(app, ctx) -- route handler + browser fallback\n    youtube.js      # yt-dlp process management + transcript parsing\n    youtube.test.js # parser unit tests\n    apt.txt         # python3-minimal (yt-dlp runtime dep)\n    post-install.sh # downloads yt-dlp binary\n```\n\n```js\n// plugins/youtube/index.js (simplified)\nimport { detectYtDlp, hasYtDlp, ensureYtDlp, ytDlpTranscript } from './youtube.js';\nimport { classifyError } from '../../lib/request-utils.js';\n\nexport async function register(app, ctx) {\n  const { log, config, sessions, ensureBrowser, getSession,\n          withUserLimit, safePageClose, normalizeUserId,\n          validateUrl, safeError, buildProxyUrl, proxyPool,\n          failuresTotal } = ctx;\n\n  await detectYtDlp(log);\n\n  app.post('/youtube/transcript', ctx.auth(), async (req, res) => {\n    // ... validate URL, extract videoId, try yt-dlp then browser fallback\n  });\n\n  async function browserTranscript(reqId, url, videoId, lang) {\n    return await withUserLimit('__yt_transcript__', async () => {\n      await ensureBrowser();\n      const session = await getSession('__yt_transcript__');\n      const page = await session.context.newPage();\n      // ... intercept captions, parse transcript\n      await safePageClose(page);\n    });\n  }\n}\n```\n\nKey patterns:\n- **Auth**: `ctx.auth()` middleware on the route\n- **Logging**: `ctx.log('info', ...)` -- never `console.log`\n- **Browser access**: `ctx.ensureBrowser()` + `ctx.getSession()` for browser-backed features\n- **Concurrency**: `ctx.withUserLimit()` to respect per-user limits\n- **Metrics**: `ctx.failuresTotal.labels(...)` for core counters, `ctx.createMetric()` for custom\n- **Code separation**: `child_process` in `youtube.js`, route handler in `index.js` -- separate files\n- **System deps**: `apt.txt` lists packages installed via `scripts/install-plugin-deps.sh`\n","category":"root","tokens":5595}]}