{"id":51526853,"url":"https://github.com/ehmo/gomoufox","last_synced_at":"2026-07-08T22:30:31.056Z","repository":{"id":363256835,"uuid":"1258644344","full_name":"ehmo/gomoufox","owner":"ehmo","description":"Go library, CLI, and MCP server for Camoufox browser automation.","archived":false,"fork":false,"pushed_at":"2026-06-21T20:12:16.000Z","size":1857,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-21T21:22:43.544Z","etag":null,"topics":["agent-tools","browser-automation","camoufox","cli","go","golang","mcp","model-context-protocol","playwright","web-automation"],"latest_commit_sha":null,"homepage":"https://github.com/ehmo/gomoufox#readme","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ehmo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-03T19:25:21.000Z","updated_at":"2026-06-21T20:12:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ehmo/gomoufox","commit_stats":null,"previous_names":["ehmo/gomoufox"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/ehmo/gomoufox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmo%2Fgomoufox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmo%2Fgomoufox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmo%2Fgomoufox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmo%2Fgomoufox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ehmo","download_url":"https://codeload.github.com/ehmo/gomoufox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmo%2Fgomoufox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35280681,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-08T02:00:06.796Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-tools","browser-automation","camoufox","cli","go","golang","mcp","model-context-protocol","playwright","web-automation"],"created_at":"2026-07-08T22:30:30.208Z","updated_at":"2026-07-08T22:30:31.046Z","avatar_url":"https://github.com/ehmo.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/gomoufox-banner.png\" alt=\"gomoufox\" width=\"900\"\u003e\n\u003c/p\u003e\n\n# gomoufox\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Go 1.26.4\" src=\"https://img.shields.io/badge/Go-1.26.4-00ADD8?logo=go\u0026logoColor=white\"\u003e\n  \u003cimg alt=\"MIT license\" src=\"https://img.shields.io/badge/license-MIT-2ea44f\"\u003e\n  \u003cimg alt=\"coverage 97%+\" src=\"https://img.shields.io/badge/coverage-97%25%2B-2ea44f\"\u003e\n  \u003cimg alt=\"MCP ready\" src=\"https://img.shields.io/badge/MCP-ready-7c3aed\"\u003e\n  \u003cimg alt=\"agent skills\" src=\"https://img.shields.io/badge/agent%20skills-included-f97316\"\u003e\n\u003c/p\u003e\n\ngomoufox is a Go driver for Camoufox.\n\nIt gives Go programs, shell scripts, and MCP agents a typed way to launch and\ncontrol the pinned Camoufox browser stack without writing Python glue.\n\nUse it only on sites you own, test, or have permission to automate.\n\n## Add gomoufox to an agent\n\nInstall the bundled skills and MCP server config in one step:\n\n```bash\ngomoufox setup --dry-run\ngomoufox setup --target all --features skills,mcp --yes\ngomoufox agents install --target all --features skills,mcp --dry-run --json\ngomoufox agents install --target all --features skills,mcp\n```\n\nUse `--target codex`, `claude`, `cursor`, or `gemini` to install for one\nagent. Use `--scope project` when you want repo-local MCP config. The default\nwrites skill files plus a stdio MCP entry that runs\n`gomoufox mcp --toolset core`.\n\nRun the dry run first. It prints the exact files gomoufox would write.\nReruns are safe: MCP config files are merged, and existing skill files are left\nalone unless you pass `--force`.\n\n## At a glance\n\n| Need | Use |\n|---|---|\n| Go browser automation | `github.com/ehmo/gomoufox` |\n| Shell automation | `gomoufox get`, `gomoufox screenshot`, `gomoufox fetch` |\n| Agent browser tools | `gomoufox mcp` |\n| Guided setup | `gomoufox setup`, `gomoufox agents install` |\n| Release evidence | [docs/BENCHMARKS.md](docs/BENCHMARKS.md) |\n\n```mermaid\nflowchart LR\n  GoApp[\"Go app\"] --\u003e GoAPI[\"Go API\"]\n  Shell[\"Shell script\"] --\u003e CLI[\"gomoufox CLI\"]\n  Agent[\"Agent\"] --\u003e Skills[\"SKILL.md\"]\n  Skills --\u003e MCP[\"gomoufox mcp\"]\n  GoAPI --\u003e Sidecar[\"gomoufox sidecar\"]\n  CLI --\u003e Sidecar\n  MCP --\u003e Sidecar\n  Sidecar --\u003e Camoufox[\"Pinned Camoufox\"]\n  Camoufox --\u003e Web[\"Permitted sites\"]\n\n  classDef api fill:#00ADD8,color:#ffffff,stroke:#00758f;\n  classDef agent fill:#7c3aed,color:#ffffff,stroke:#5b21b6;\n  classDef browser fill:#f97316,color:#ffffff,stroke:#c2410c;\n  classDef web fill:#16a34a,color:#ffffff,stroke:#15803d;\n  class GoAPI,CLI api;\n  class Agent,Skills,MCP agent;\n  class Sidecar,Camoufox browser;\n  class Web web;\n```\n\n## Install\n\nLibrary:\n\n```bash\ngo get github.com/ehmo/gomoufox\n```\n\nCLI:\n\n```bash\ngo install github.com/ehmo/gomoufox/cmd/gomoufox@latest\ngomoufox -h\ngomoufox install\ngomoufox doctor\n```\n\nHomebrew:\n\n```bash\nbrew tap ehmo/gomoufox https://github.com/ehmo/gomoufox\nif brew commands | grep -qx trust; then\n  brew trust --formula ehmo/gomoufox/gomoufox\nfi\nbrew install gomoufox\ngomoufox install\ngomoufox doctor\n```\n\nInstall through the tap. The release `gomoufox.rb` file is there for audit and\ntap metadata; Homebrew wants formulae inside taps. Run `brew trust` only if your\nHomebrew build still has that command.\n\n| Path | Status | Use it when |\n|---|---|---|\n| `gomoufox install` | ![default](https://img.shields.io/badge/default-no%20Python-2ea44f) | You want the Go-managed node-direct runtime. |\n| `gomoufox install --runtime python` | ![legacy](https://img.shields.io/badge/legacy-explicit-f97316) | You need BrowserForge, geoip, humanize launch options, or the legacy Python sidecar. |\n| `GOMOUFOX_CAMOUFOX_PATH=/path/to/browser` | ![custom](https://img.shields.io/badge/custom-local%20browser-64748b) | You already have a compatible Camoufox browser directory. |\n\nDefault Go, CLI, and MCP flows use the Go-managed node-direct runtime. The\ndefault install fetches Playwright's Node driver, gomoufox's launch server, and\nthe pinned Camoufox browser archive. Persistent profiles and browser-context\nlocale settings use the node-direct runtime; geoip and humanize launch options\nstill require the Python sidecar.\n\nUse `gomoufox install --runtime python` only for the explicit legacy\nPython-sidecar path. That path uses hash-locked wheels and fails closed on a\nmissing wheel or hash mismatch.\n\nHomebrew installs on macOS Apple Silicon and Linux amd64, because those are the\nhosts where the pinned browser has an upstream binary. Other Go archives still\nship for library and CLI users.\n\nUse `GOMOUFOX_TRUST_UNVERIFIED_CAMOUFOX_PATH=1` only for a trusted local browser\nbuild that does not match the release manifest. `gomoufox doctor` reports that\nas a warning.\n\n## Go library\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\tgomoufox \"github.com/ehmo/gomoufox\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\tbrowser, err := gomoufox.New(ctx)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer browser.Close()\n\n\tpage, err := browser.NewPage(ctx)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tif _, err := page.Goto(ctx, \"https://example.com\"); err != nil {\n\t\tpanic(err)\n\t}\n\n\ttext, err := page.Content(ctx)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tfmt.Println(text)\n}\n```\n\nUse the library when your program owns the browser lifecycle. Use the CLI when a\nshell script needs a page snapshot, screenshot, or browser-context fetch. Use MCP\nwhen an agent needs browser tools over stdio or HTTP.\n\n## CLI\n\n```bash\ngomoufox get https://example.com --markdown\ngomoufox screenshot https://example.com --out page.png --full-page\ngomoufox fetch https://api.example.com/me --navigate-first https://example.com\ngomoufox open https://app.example.com --save-session state.json --wait\ngomoufox fetch https://app.example.com/api/me --cookies-file state.json\n```\n\nFetch responses are read through a bounded browser stream. `gomoufox fetch`\ndefaults to 512 KiB, reports truncation in JSON output, and cancels the reader\nwhen the cap is reached.\n\nAgent-friendly discovery:\n\n```bash\ngomoufox -h\ngomoufox -v\ngomoufox version\ngomoufox help\ngomoufox help --json --fields commands\ngomoufox help skills --json\ngomoufox help mcp --json\ngomoufox skills list --json\ngomoufox skills show core\ngomoufox mcp --help\n```\n\nAutomation tips:\n\n- Use `--json` for machine-readable output and keep status logs on stderr.\n- Use `--timeout \u003cdur\u003e` for bounded shell jobs.\n- Use `open --save-session` for human login, then reuse the state with\n  `--cookies-file`.\n- Use `--profile \u003cdir\u003e` when a workflow needs full persistent browser state.\n- Keep the default URL policy for normal work. For CLI browser commands only,\n  use `--allow-private-ips` when you need local or private network targets.\n\n## Skills\n\ngomoufox ships versioned agent skills in the binary and as checked `SKILL.md`\nfiles. Skills give agents a compact operating guide for the Go API, CLI, and MCP\ntools. They do not install npm packages, run `npx`, or call the network.\n\n| Skill | Path | Use it when |\n|---|---|---|\n| `core` | `skills/gomoufox/SKILL.md` | An agent needs the Go library or CLI workflow. |\n| `mcp` | `skills/gomoufox-mcp/SKILL.md` | An agent needs MCP setup, tool choice, and browser safety rules. |\n\nInspect the embedded skills:\n\n```bash\ngomoufox skills list --json\ngomoufox skills show core\ngomoufox skills show mcp\n```\n\nExport installable copies:\n\n```bash\ngomoufox skills export --out ./skills\ngomoufox skills export --out ./skills --force\n```\n\nInstall skill files only for Codex:\n\n```bash\ngomoufox skills install --target codex --dry-run --json\ngomoufox skills install --target codex\n```\n\nBy default, the Codex target writes to `$CODEX_HOME/skills` or\n`~/.codex/skills`. Use `--dir \u003cpath\u003e` to choose another skill directory. The\ninstaller writes:\n\n- `gomoufox/SKILL.md`\n- `gomoufox/agents/openai.yaml`\n- `gomoufox-mcp/SKILL.md`\n- `gomoufox-mcp/agents/openai.yaml`\n\n`list` and `show` read from the embedded skill bodies, so agents can discover\nthe right instructions even when no skill directory exists yet. `export` and\n`install` write the same checked bodies that ship in the repo. Existing files are\nleft alone unless you pass `--force`.\n\nInstall skills plus MCP configuration for a specific agent or project:\n\n```bash\ngomoufox agents install --target all --dry-run --json\ngomoufox agents install --target cursor --scope project --features skills,mcp\n```\n\n`agents install` supports `codex`, `claude`, `cursor`, `gemini`, or `all`, with\n`--scope user|project` and `--features skills,mcp`. MCP entries use stdio and\ndefault to `gomoufox mcp --toolset core`. Use `--toolset full` for the full MCP\nsurface. Reserve repeated `--mcp-arg \u003carg\u003e` for extra MCP server flags. Use\n`--force` only when you want to replace existing skill files or rewrite merged\nMCP config.\n\n| Target | User-scope MCP file | Project-scope MCP file | Skill root |\n|---|---|---|---|\n| `codex` | `~/.codex/config.toml` | `.codex/config.toml` | `~/.agents/skills` or `.agents/skills` |\n| `claude` | `~/.claude/mcp.json` | `.mcp.json` | `~/.claude/skills` or `.claude/skills` |\n| `cursor` | `~/.cursor/mcp.json` | `.cursor/mcp.json` | `~/.agents/skills` or `.agents/skills` |\n| `gemini` | `~/.gemini/settings.json` | `.gemini/settings.json` | `~/.agents/skills` or `.agents/skills` |\n\nDry-run output shows the exact absolute paths that would be written.\n\n## MCP\n\nRun browser tools over stdio:\n\n```bash\ngomoufox mcp\n```\n\nClaude Code example:\n\n```bash\nclaude mcp add gomoufox -- gomoufox mcp\n```\n\nHTTP transport requires a bearer token:\n\n```bash\ngomoufox mcp --transport http --auth-token \"$TOKEN\"\n```\n\nMCP defaults:\n\n- Use `gomoufox mcp --toolset core` for a smaller agent tool surface. It keeps\n  navigation, snapshots/content, common form actions, sessions, and skill tools.\n  The default `full` toolset keeps diagnostics, eval, fetch, cookies, storage,\n  upload, and other gated tools available.\n- `file://`, private IP ranges, link-local addresses, and metadata hosts are\n  blocked.\n- `gomoufox mcp --allow-localhost` permits explicit loopback HTTP(S) targets\n  (`localhost`, `127.0.0.0/8`, `::1`) for local app testing while keeping\n  broader private networks, metadata hosts, DNS rebinding, and unsafe redirects\n  blocked.\n- JavaScript evaluation is disabled unless you start MCP with `--enable-eval`.\n- Response sizes are capped.\n- MCP-owned helper scripts use a startup-probed internal helper evaluation path\n  and do not install a page-visible helper object.\n- Browser-derived MCP responses include `provenance.trust: \"untrusted\"` so\n  agents can separate website content from trusted instructions. This label helps\n  agent policy. It is not a sandbox.\n- Console, page-error, network, and performance diagnosis tools are bounded,\n  redacted, and clearable where they keep event buffers. Network summaries do\n  not include request or response bodies.\n- Ref-based interaction tools cover click, type, key press, hover, scroll,\n  select option, checkbox/radio state, dialog policy, and bounded form batches.\n- `browser_snapshot` form values stay redacted unless you start MCP with\n  `--allow-snapshot-values` and the tool call sets `include_values: true`.\n- Browser-context fetches, cookie values, cookie mutation, session export,\n  session import, session proxy use, file upload, and file download stay\n  disabled unless you enable their matching operator flags.\n- To reuse a CLI login in MCP, save state with `gomoufox open --save-session`,\n  place the file under `--session-dir`, start MCP with `--allow-session-import`,\n  then call `session_create` with `storage_state_path` or `session_load` with\n  `path`.\n- `browser_upload_file` requires `--allow-file-upload`; paths must resolve under\n  `--session-dir`, and responses do not echo file paths.\n- `browser_download` requires `--allow-file-download`; destination paths must\n  resolve under `--session-dir`. Suggested filenames from the browser are\n  returned as metadata only and are never used as write paths.\n- `browser_fetch` requires `--allow-browser-fetch` plus at least one\n  `--allowed-origins` or `--allowed-hosts` entry. It still uses gomoufox network\n  policy, so private and metadata destinations stay blocked.\n\n## Benchmarks\n\nThe benchmark answers one question: did the Go path stay close to Python\nCamoufox without producing Go-only failures?\n\n![node-direct](https://img.shields.io/badge/node--direct-candidate-2ea44f)\n![python-sidecar](https://img.shields.io/badge/python--sidecar-baseline-64748b)\n![upstream](https://img.shields.io/badge/Python%20Camoufox-upstream-2563eb)\n\nLatest checked evidence:\n[docs/BENCHMARKS.md](docs/BENCHMARKS.md),\n[Python-sidecar artifact](docs/benchmarks/2026-06-08-release-gate.json), and\n[node-direct artifact](docs/benchmarks/2026-06-24-node-direct-readiness.json).\n\n| Runtime | Passed | Blocked | Failed | Wall ms | Peak RSS MiB | Peak CPU % | Report tokens |\n|---|---:|---:|---:|---:|---:|---:|---:|\n| Python Camoufox | 95 | 5 | **0** | 373,637 | 3,863.5 | 567.9 | 79,051 |\n| gomoufox, Python sidecar | 95 | 5 | **0** | 366,338 | **2,765.3** | 569.9 | 13,059 |\n| gomoufox, node-direct Go | **96** | **4** | **0** | **360,361** | 3,734.2 | **548.4** | **12,857** |\n\nBold means best in that column. The sidecar row comes from the previous extended\nrelease-gate artifact; node-direct comes from the readiness artifact.\nUse the table for direction, not single-run timing claims.\n\nLatest extended validation: 100 targets, 60s timeout, `commit` wait, 3s settle,\nno screenshots, reused browser, compact Go report, 0s extra load-state wait, and\n250,000-byte classification cap.\ngomoufox passed 96, blocked 4, failed 0. Python Camoufox passed 95, blocked 5,\nfailed 0. The run had 0 Go-only regressions and 1 Python-only outcome\ndifference. See\n[docs/benchmarks/2026-06-24-node-direct-readiness.json](docs/benchmarks/2026-06-24-node-direct-readiness.json).\n\n| Ratio | node-direct Go / Python Camoufox |\n|---|---:|\n| Wall time | 0.964 |\n| Peak RSS | 0.967 |\n| Peak CPU | 0.966 |\n| Report tokens | 0.163 |\n\nWall time stayed at parity. Node-direct used less RSS, less CPU, and produced a\nmuch smaller agent report. Treat a report-token ratio above 0.50 as a regression.\nRelease gates use `--unsafe-direct-network`, block reproducible outcome mismatch,\nand give a new shared block, failure, or performance outlier one focused retry.\n\n```bash\nscripts/benchmark-realpass.py --mode smoke\nscripts/benchmark-realpass.py --mode smoke --loops 2 --run-order alternate\nscripts/benchmark-realpass.py --mode extended --list-targets\nscripts/fingerprint-audit.py\n```\n\nUse `--run-order alternate` for timing work. Run `scripts/fingerprint-audit.py`\nafter browser pin, launch option, WebGL, locale, timezone, font, canvas, or\nruntime changes. It compares Python Camoufox, gomoufox with the Python sidecar,\nand gomoufox node-direct on a local fingerprint page.\n\nThe no-Python canary checks the consumer path:\n\n```bash\nscripts/no-python-consumer-canary.sh --gomoufox ./gomoufox --json-out dist/node-direct-consumer-readiness.json\npython3 scripts/check-python-removal-readiness.py --artifact dist/node-direct-consumer-readiness.json\n```\n\nMore detail:\n\n- [Benchmark rules and target matrix](docs/BENCHMARKS.md)\n- [Release verification](#release-verification)\n- [Python tooling policy](scripts/python-tooling-policy.json)\n- [Public consumer canary](scripts/public-consumer-canary.sh)\n\n## Release verification\n\nEach public release ships deterministic archives, `checksums.txt`,\n`checksums.json`, a Homebrew formula, `release-provenance.json`, and\n`sbom.spdx.json`. The public workflow also creates GitHub artifact attestations.\n\n```bash\ngh release download vX.Y.Z --repo ehmo/gomoufox --dir /tmp/gomoufox-vX.Y.Z\ncd /tmp/gomoufox-vX.Y.Z\nshasum -a 256 -c checksums.txt\ngh attestation verify gomoufox_X.Y.Z_darwin_arm64.tar.gz -R ehmo/gomoufox\n```\n\nRun the public consumer canary when you want one command that checks the release\nasset layout, checksums, host archive extraction, CLI help, MCP core handshake,\nskills listing, and skills install dry-run:\n\n```bash\nbash scripts/public-consumer-canary.sh --version vX.Y.Z --repo ehmo/gomoufox --brew-mode inspect\n```\n\nAdd `--verify-attestations`, `--go-install`, or `--brew-mode install` when you\nneed those slower paths. The default canary avoids browser launch work. Add\n`--browser-smoke-url https://example.com/` when you also want to prove the\nmanaged runtime is installed and usable on that machine.\n\nMaintainers also run the bundled public audit after publication:\n\n```bash\npython3 scripts/audit-public-release.py \\\n  --version vX.Y.Z \\\n  --repo ehmo/gomoufox \\\n  --verify-attestations \\\n  --brew-mode inspect\n```\n\n## Common questions\n\n### Where is Python still used?\n\nDefault install and ordinary node-direct flows do not need Python at runtime.\nPython remains for explicit legacy Python-sidecar mode, geoip/humanize\nlaunch-option flows, upstream Python Camoufox comparison benchmarks, and\nmaintainer release/dev scripts listed in `scripts/python-tooling-policy.json`.\n\nThe audit path still exists for upstream parity work:\n\n```bash\ngo run ./cmd/gomoufox-launchplan --scenario all --out dist/launch-plan/latest\n```\n\nThat command dumps gomoufox's Go launch input beside the Python Camoufox launch\npayload. It can also compare an optional candidate payload with\n`--candidate \u003cjson\u003e` and fails on drift.\n\n### Why use gomoufox instead of Python Camoufox directly?\n\nUse gomoufox when you need a typed Go API, a scriptable CLI, MCP tools for\nagents, release-gated Go/Python parity checks, and local URL guardrails. Use\nPython Camoufox directly when your project is already Python-first and does not\nneed those surfaces.\n\n### Will every protected site work?\n\nNo. gomoufox tests against Python Camoufox on the same target set. A Go-only\nblock or failure is a gomoufox regression. A shared block means both stacks saw\nthe same site behavior during that run. Site policy, traffic reputation, browser\nchanges, and upstream Camoufox changes can still affect results.\n\n### Where does browser state live?\n\nTemporary sessions use temporary profile data. Persistent sessions use the\ndirectory you pass with `--profile`. MCP session import, export, proxy use, and\nfile upload stay disabled until you start MCP with the matching operator flags.\nPortable `storage_state` files from `open --save-session` contain cookies and\nlocalStorage only; reuse them with CLI `--cookies-file` or MCP session import.\n\n### Does MCP trust page content?\n\nNo. Browser-derived MCP responses carry `provenance.trust: \"untrusted\"`. Agents\nshould treat page text as data from the site, not instructions from the operator.\n\n### Can I run headful on Linux?\n\nYes, if a display exists. Set `GOMOUFOX_AUTO_DISPLAY=1` when you want gomoufox to\nuse an automatic display helper.\n\n### How do I debug install issues?\n\nRun:\n\n```bash\ngomoufox doctor\ngomoufox doctor --json\ngomoufox --verbose doctor\n```\n\nCheck `GOMOUFOX_CAMOUFOX_PATH` only when you intentionally bypass the managed\nruntime. Offline browser paths are manifest-verified unless\n`GOMOUFOX_TRUST_UNVERIFIED_CAMOUFOX_PATH=1` is set for a trusted local build.\n\n## Compatibility\n\ngomoufox pins the browser stack. Upgrade these pieces together.\n\n| gomoufox | playwright-go | Playwright package | Camoufox package | Camoufox browser |\n|---|---|---|---|---|\n| v0.1.x | v0.5700.1 | 1.57.0 | 0.4.11 | v135.0.1-beta.24 |\n\nAuto-fetch support is verified for macOS arm64. Other platforms may work with a\npre-provisioned browser directory through `GOMOUFOX_CAMOUFOX_PATH`.\n\nHeadful Linux runs need an existing display or `GOMOUFOX_AUTO_DISPLAY=1`.\n\n## Development\n\nThese Python commands are development tooling, not runtime prerequisites:\n\n```bash\ngo test -count=1 ./...\ngo test -race -count=1 ./...\ngo vet ./...\npython3 scripts/check-agent-contracts.py\npython3 scripts/format-doc-numbers.py\ngo run golang.org/x/vuln/cmd/govulncheck@v1.3.0 ./...\n```\n\nNormal CI keeps to cheap deterministic checks: public export consistency,\ndocs-number formatting, unit tests, agent contracts, `go vet`, and the public\nconsumer canary in dry-run mode. Public tag releases run the heavier coverage,\nvulnerability, package, attestation, and post-release audit checks.\n\nAgent-facing CLI and MCP discovery snapshots live in `docs/agent-contracts/`.\nWhen CLI help or MCP tool schemas change, run\n`python3 scripts/check-agent-contracts.py --update` and review the diff.\n\nRun `python3 scripts/format-doc-numbers.py --write` after editing docs with\nlarge displayed numbers.\n\nThe public repo is generated. Do not edit generated public files by hand.\n\n## License\n\ngomoufox is MIT licensed.\n\nCamoufox is MPL-2.0. gomoufox starts Camoufox as a subprocess and downloads its\nbrowser binary at runtime. gomoufox does not vendor or modify Camoufox.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehmo%2Fgomoufox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fehmo%2Fgomoufox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehmo%2Fgomoufox/lists"}