browse-config: Camoufox Configuration Generator

Step 0: Ask what the user needs

Use AskUserQuestion to determine the goal. Offer these presets:

Preset defaults

Stealth browsing:

{
  "geoip": true,
  "humanize": true
}

Fast scraping:

{
  "blockImages": true,
  "blockWebrtc": true,
  "blockWebgl": true,
  "enableCache": true
}

Google-safe:

{
  "geoip": true,
  "humanize": true,
  "os": ["windows", "macos", "linux"]
}

Step 1: Custom configuration (skip if preset chosen)

If the user chose "Custom", ask about each option group using AskUserQuestion. Present one group at a time.

Identity

• os (string or array) -- target OS fingerprint: "windows", "macos", "linux", or an array for random selection
• locale (string or array) -- browser locale, e.g. "en-US" or ["en-US", "en-GB"]
• fingerprint (object) -- advanced fingerprint overrides (most users skip this)

Privacy

• blockWebrtc (boolean) -- block WebRTC to prevent IP leaks
• blockWebgl (boolean) -- block WebGL fingerprinting
• blockImages (boolean) -- block image loading (also improves speed)

Performance

• enableCache (boolean) -- enable browser disk cache
• blockImages (boolean) -- already covered in Privacy, mention speed benefit here

Network

• proxy (string or object) -- proxy URL like "http://user:pass@host:port" or {"server":"...","username":"...","password":"..."}
• geoip (string or boolean) -- true to auto-derive from proxy IP, or a country code like "US"

Behavior

• humanize (boolean or number) -- true for default human-like delays, or a number (0.5-2.0) to control speed

Advanced (offer only if user asks)

• addons (string[]) -- Firefox addon paths to load
• excludeAddons (string[]) -- built-in addons to skip
• firefoxUserPrefs (Record) -- raw Firefox about:config preferences
• args (string[]) -- extra browser launch arguments
• fonts (string[]) -- custom font list
• customFontsOnly (boolean) -- use only custom fonts
• screen (object) -- {minWidth, maxWidth, minHeight, maxHeight}
• window ([width, height]) -- fixed window size
• ffVersion (number) -- target Firefox version
• headless (boolean or "virtual") -- headless mode (not recommended for anti-detection)
• mainWorldEval (boolean) -- enable main world JavaScript eval
• executablePath (string) -- custom camoufox binary path
• env (Record) -- environment variables for the browser process
• virtualDisplay (string) -- virtual display config (Linux only)
• disableCoop (boolean) -- disable Cross-Origin-Opener-Policy headers
• debug (boolean) -- enable debug logging

Step 2: Ask where to save

Use AskUserQuestion with two options:

1. browse.json -- adds a "camoufox" section to the project's browse.json. Applied automatically whenever --runtime camoufox is used.
2. Named profile -- saves to .browse/camoufox-profiles/<name>.json. Used with --camoufox-profile <name>. Good for per-scenario configs (e.g. "google", "scrape", "stealth").

If the user picks a named profile, ask for the profile name.

Step 3: Generate and write the file

If browse.json

Read the existing browse.json first (if it exists). Merge the new camoufox key into it. Write the result:

{
  "camoufox": {
    "geoip": true,
    "humanize": true
  }
}

If named profile

Create the directory .browse/camoufox-profiles/ if needed. Write just the config object:

{
  "geoip": true,
  "humanize": true,
  "os": "windows"
}

Step 4: Show usage

After writing the file, tell the user exactly how to use it.

If browse.json:

Run: browse --runtime camoufox goto <url>
The camoufox section is applied automatically.

If named profile:

Run: browse --runtime camoufox --camoufox-profile <name> goto <url>

Always note: "The --camoufox-profile flag only applies when starting a new server. If a server is already running, stop it first with browse stop."

All CamoufoxConfig options

All keys use camelCase in JSON. They are auto-mapped to snake_case for camoufox-js internally.

Guardrails

• Always use AskUserQuestion before generating config. Do not assume preferences.
• Use camelCase keys in all generated JSON (the CLI handles snake_case mapping).
• Never overwrite existing browse.json fields outside the camoufox key.
• Never include proxy credentials in output shown to the user. Write them to the file only.
• Do not include options the user did not ask for or confirm, beyond the preset defaults.