camofox-browser-control（camofox 浏览器控件）

Use the standalone camofox-browser server directly over HTTP.

Default assumptions for this workspace:

• Base URL: http://127.0.0.1:9377
• The service is already running.
• userId is mandatory on nearly every useful request.
• sessionKey (or legacy listItemId) groups tabs; default to default.

Golden workflow

1. Check /health.
2. Create a tab with /tabs.
3. Call /tabs/:tabId/wait.
4. Call /tabs/:tabId/snapshot and read refs.
5. Act with /click, /type, /press, /scroll, or /navigate.
6. Snapshot again after any state-changing action.

Prefer this loop over HTML scraping.

Hard rules

• Always send userId.
• Prefer POST /tabs with sessionKey for raw server use.
• Re-snapshot after click, type, press, or navigation.
• If a field ignores fill, retry with type using mode: "keyboard".
• If /tabs returns an empty list, check whether userId was omitted.
• Use direct navigation when the target URL is known; do not over-click through search results if a stable URL exists.
• Use VNC/manual login for MFA, CAPTCHAs, or brittle auth flows, then reuse storage state or persistence.

Minimal endpoint map

Read references/api-cheatsheet.md when you need request/response shapes.

Most-used endpoints:

• GET /health
• POST /tabs
• GET /tabs?userId=...
• POST /tabs/:tabId/wait
• GET /tabs/:tabId/snapshot?userId=...
• POST /tabs/:tabId/click
• POST /tabs/:tabId/type
• POST /tabs/:tabId/press
• POST /tabs/:tabId/scroll
• POST /tabs/:tabId/navigate
• POST /tabs/:tabId/evaluate
• POST /sessions/:userId/cookies
• GET /sessions/:userId/storage_state

Recommended helper script

Use scripts/camofox.py instead of rewriting raw HTTP every time.

Examples:

python3 skills/camofox-browser-control/scripts/camofox.py health
python3 skills/camofox-browser-control/scripts/camofox.py open --user lotfi --session default --url https://github.com
python3 skills/camofox-browser-control/scripts/camofox.py snapshot --user lotfi --tab <tabId>
python3 skills/camofox-browser-control/scripts/camofox.py click --user lotfi --tab <tabId> --ref e17
python3 skills/camofox-browser-control/scripts/camofox.py type --user lotfi --tab <tabId> --ref e2 --text 'hello' --mode fill
python3 skills/camofox-browser-control/scripts/camofox.py type --user lotfi --tab <tabId> --text '97304' --mode keyboard --submit
python3 skills/camofox-browser-control/scripts/camofox.py navigate --user lotfi --tab <tabId> --url https://example.com

Known quirks

• GET /tabs without userId can misleadingly show no tabs even when tabs exist.
• Refs go stale after page changes. Snapshot again instead of reusing old refs blindly.
• click already retries normal click, force click, and mouse sequence; success does not guarantee the frontend changed the state you expect, so verify with a fresh snapshot.
• Some sites accept direct URL navigation more reliably than UI clicking.
• Some frontend inputs require true keyboard events. Use mode: "keyboard" plus --submit when fill does not trigger app logic.
• Large multi-step chained calls are more fragile than short calls with verification between them.

Login strategy

For normal forms:

• open → wait → snapshot → type → click/submit → snapshot

For stubborn auth:

• use VNC/noVNC login
• export storage_state
• rely on persistence or restore state on later runs

For cookie bootstrap:

• import Netscape cookies through /sessions/:userId/cookies
• requires CAMOFOX_API_KEY

Escape hatch

Use /tabs/:tabId/evaluate only when refs/typing/clicking are insufficient. Keep expressions small and targeted.

Local note for this machine

The current host already has a live server on 127.0.0.1:9377, with VNC/noVNC exposed by the container. Treat that as the default target unless the task says otherwise.