Browser Automation

The harness can drive a real browser through Camoufox, an anti-detection Firefox fork. Agents navigate pages, read accessibility snapshots, interact with elements, run JavaScript, and take screenshots.

Source: pkgs/camoufox/, modules/camoufox.nix, modules/options/camoufox.nix.

Components

• camoufox — the Camoufox browser binary (anti-detection Firefox, daijro/camoufox).
• camofox-server — a Node.js REST server wrapping Camoufox (jo-inc/camofox-browser).
• cowboy-browser — a shell CLI (pkgs/camoufox/cowboy-browser.sh) that the agent calls; it talks to the server’s REST API.

All three are exposed as flake packages: nix build .#camoufox, .#camofox-server, .#cowboy-browser.

Deployment

The server runs inside a shared NixOS container (cowboy-camoufox) with one camoufox-<user> systemd service per agent. Each agent’s server listens on basePort + (uid - 1338), where basePort defaults to 9377. Browsing happens under a headless Xvfb display.

Enable it with:

services.cowboy.camoufox.enable = true;

This requires services.cowboy.secretsProxy.enable = true — the camoufox container uses the proxy’s veth networking, and the module asserts this.

Options under services.cowboy.camoufox:

CLI

cowboy-browser keeps a session id in a file under $XDG_RUNTIME_DIR and targets the server at $CAMOFOX_URL (default http://10.200.0.1:9377, the veth host address — localhost does not reach the container). Subcommands:

cowboy-browser navigate <url>      Open URL (creates a session if needed), return a snapshot
cowboy-browser snapshot [--full]   Accessibility-tree snapshot of the current page
cowboy-browser click <ref>         Click an element by ref
cowboy-browser type <ref> <text>   Type text into an element
cowboy-browser scroll <direction>  Scroll (up/down/left/right)
cowboy-browser press <key>         Press a key (Enter, Escape, Tab, ...)
cowboy-browser back                Navigate back
cowboy-browser eval <js> | eval -  Run JS in the page ('-' reads from stdin)
cowboy-browser screenshot [file]   Save a screenshot (default /tmp/cowboy-browser-screenshot.png)
cowboy-browser close               Close the browser session

Elements are referenced as @e1, @e2, … from the snapshot output (the @ is optional).

Example

cowboy-browser navigate https://example.com
# snapshot lists interactive elements with @eN refs
cowboy-browser type @e3 "search query"
cowboy-browser click @e7
cowboy-browser screenshot ./result.png

The agent invokes these through its bash tool. cowboy-browser unsets the HTTP proxy variables for its own requests, since the camofox server is local to the veth and does not need credential injection.