Camoufox Browser Runtime Skill

Use this skill when browser tasks should run through the Camoufox runtime API exposed by this repository.

Runtime assumptions

• Runtime default URL: http://127.0.0.1:9487
• Health endpoint: GET /health
• Capabilities endpoint: GET /capabilities

If the runtime is not running yet:

cd /path/to/camoufox-browser
npm install
npx camoufox-js fetch
npm start

Or use the bundled helpers from this skill:

./scripts/start.sh
./scripts/stop.sh

(start.sh runs the runtime from the package/repo root and waits for /health.)

Before any browser task, do a quick preflight:

curl -s http://127.0.0.1:9487/health
curl -s http://127.0.0.1:9487/capabilities

Recommended execution flow

1. Create or reuse a session (POST /sessions)
2. Create a tab (POST /sessions/:sessionId/tabs)
3. Inspect (POST /tabs/:tabId/inspect)
4. Query specific targets when needed (POST /tabs/:tabId/query)
5. Execute actions with retries (POST /tabs/:tabId/act)
6. Confirm expected state (POST /tabs/:tabId/wait)
7. Use eval only for edge cases (POST /tabs/:tabId/eval)
8. Read events/downloads/fetch APIs for debugging and extraction

For userscript-style injection:

1. Write the script to a file on disk
2. Register via POST /sessions/:sessionId/init-scripts with {"path": "/path/to/script.js"}
3. Open tabs — the script runs automatically at DOMContentLoaded on every page load
4. Edit the file on disk as needed — changes are picked up on next page load
5. Reload the target tab to verify (no re-registration needed)

Minimal API snippets

Create session:

curl -s -X POST http://127.0.0.1:9487/sessions \
  -H "Content-Type: application/json" \
  -d '{"persistent":true}'

Create tab:

curl -s -X POST http://127.0.0.1:9487/sessions/<sessionId>/tabs \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Inspect:

curl -s -X POST http://127.0.0.1:9487/tabs/<tabId>/inspect \
  -H "Content-Type: application/json" \
  -d '{"limit":200,"offset":0,"includeScreenshot":false,"includeDom":false}'

Act:

curl -s -X POST http://127.0.0.1:9487/tabs/<tabId>/act \
  -H "Content-Type: application/json" \
  -d '{
    "action":"click",
    "target":{"by":"role","role":"button","name":"Continue"},
    "retry":{"maxAttempts":3,"backoffMs":150}
  }'

Wait:

curl -s -X POST http://127.0.0.1:9487/tabs/<tabId>/wait \
  -H "Content-Type: application/json" \
  -d '{
    "mode":"all",
    "conditions":[{"kind":"networkIdle"}],
    "timeoutMs":10000
  }'

Init scripts (userscript-style injection):

# From file on disk (re-read on every page load)
curl -s -X POST http://127.0.0.1:9487/sessions/<sessionId>/init-scripts \
  -H "Content-Type: application/json" \
  -d '{"path":"/path/to/script.user.js"}'

# Or inline
curl -s -X POST http://127.0.0.1:9487/sessions/<sessionId>/init-scripts \
  -H "Content-Type: application/json" \
  -d '{"script":"document.body.style.background = \"red\""}'

Notes

• Prefer semantic targeting (ref, role, label) before brittle selectors.
• For userscript-style injection, use POST /sessions/:sessionId/init-scripts with a file path.

File-based scripts are re-read from disk on every page load — just edit and reload.

• Inline scripts (via script) are also supported but baked in at registration time.
• Use /tabs/:tabId/events for timeline debugging (network, console, page errors, actions).
• Use /tabs/:tabId/fetch for authenticated HTTP calls using browser cookies.
• Use /tabs/:tabId/downloads + /save to persist downloaded artifacts.

For complete endpoint coverage and payload details, read ../../README.md before complex or long-running workflows.