firefox-control

Firefox Control

Control Firefox via WebDriver BiDi on port 9223. Direct BiDi WebSocket, no geckodriver. Use port 9223 because more popular Chrome CDP occupies 9222.

Launch Firefox: firefox --remote-debugging-port 9223

TEST TOOL: navigator.webdriver=true — detected by every anti-bot system. No toggle exists. Use Chrome CDP for production automation.

Usage

Just run a command — the daemon auto-starts on first call and connects to Firefox on port 9223. If Firefox isn't running or doesn't have remote debugging enabled, the error message will say so.

Full command list: uv run firefoxctl.py --help Per-command help: uv run firefoxctl.py COMMAND --help

Always use uv run (PEP 723 inline dependencies):

uv run firefoxctl.py list
uv run firefoxctl.py --json list
uv run firefoxctl.py open https://example.com
uv run firefoxctl.py status
uv run firefoxctl.py targets
uv run firefoxctl.py stop

--json goes BEFORE the subcommand (global flag). The daemon idles out after 5 min. Unix socket: /tmp/firefoxctl-{uid}.sock. Tool responses are sanitized against prompt injection.

Target commands

All target commands: uv run firefoxctl.py CONTEXT COMMAND [ARGS]

Context ID from list output (full UUID required — no prefix match).

uv run firefoxctl.py CONTEXT eval "document.title"
uv run firefoxctl.py CONTEXT screenshot -o page.png
uv run firefoxctl.py CONTEXT console-tail --for 30
uv run firefoxctl.py CONTEXT navigate https://example.com

navigate and open may hand you a different context back. Firefox sometimes answers a navigation by replacing the browsing context rather than reusing it — the id you asked for is destroyed and a new one appears at the target URL. navigate follows the swap when it can identify the replacement:

uv run firefoxctl.py --json navigate "$ctx" https://example.com/feed.json
# {"navigation": "...", "url": "...", "context": "<same id>"}
# {"navigation": null,  "url": "...", "context": "<NEW id>", "context_swapped": true}