Camofox Browser Control

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...

Security Scan

The skill mostly does what it claims (control a local camofox-browser HTTP API) but the docs reference a CAMOFOX_API_KEY and cookie/storage operations that are not declared or implemented, creating an unexplained credential/data-risk gap.

Purpose & Capability

Name, description, SKILL.md, cheatsheet, and the helper script all align: they operate against a camofox-browser REST API (default http://127.0.0.1:9377). The provided Python helper implements the documented endpoints. However, the docs reference an Authorization-protected cookie/storage API (CAMOFOX_API_KEY) that is not declared in requires.env and is not used by the helper script—an inconsistency that should be clarified.

Instruction Scope

Instructions explicitly tell the agent/operator to import/export cookies and storage_state and to use VNC/noVNC for interactive login. Those operations can move credentials/session material in/out of the system. The SKILL.md also tells to always send userId and suggests a default live server on localhost; while interacting with localhost is expected, the cookie/storage endpoints require an Authorization header per the cheatsheet (not wired into the script). This gap means the instructions expect access to sensitive session data but the skill does not declare how that secret is supplied or protected.

Install Mechanism

This is an instruction-only skill with no install spec; the only code is a small helper script. Nothing is downloaded or written during installation, which is low risk.

Credentials

requires.env is empty, yet the cheatsheet and SKILL.md mention a CAMOFOX_API_KEY for cookie import and storage_state export. That environment/credential need is not declared and the helper script does not accept or attach an Authorization header. This mismatch could lead to unclear secrets handling (missing, required ad-hoc, or passed in insecure ways).

Persistence & Privilege

The skill is not always-on and does not request elevated or persistent system privileges. It does not modify other skills or system-wide agent settings.

What to consider before installing

This skill appears to be a simple REST client for a local camofox-browser service, which is coherent — but note the mismatch: the docs mention a CAMOFOX_API_KEY and cookie/storage operations that are not declared or implemented in the helper script. Before installing or using it, verify: (1) whether your deployment actually requires CAMOFOX_API_KEY for /sessions endpoints and where that key would come from; (2) how cookie/storage export/import will be handled and whether sensitive session data might be exposed; (3) that the default target (127.0.0.1:9377) is a trusted local service (the SKILL.md even notes VNC/noVNC exposure). If you need cookie/storage features, ask the author to (a) declare required env vars (CAMOFOX_API_KEY) in metadata, (b) add explicit support in the helper for safe Authorization header handling, and (c) document data-retention/exfiltration risks. If you cannot confirm those, treat cookie/import operations as potentially risky and avoid providing credentials or storage dumps.

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.