Control a standalone camofox-browser server over its REST API, especially when a local or remote service is already running on port 9377. Use for opening tab...
--- name: camofox-browser-control description: Control a standalone camofox-browser server over its REST API, especially when a local or remote service is already running on port 9377. Use for opening tabs, navigating, snapshotting pages, clicking refs, typing into forms, pressing keys, scrolling, exporting storage state, importing cookies, or debugging browser automation against camofox-browser/Camoufox behavior. --- 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: ```bash 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.
don't have the plugin yet? install it then click "run inline in claude" again.
by @clawhub