browse-config

browse-config: Camoufox Configuration Generator

Step 0: Ask what the user needs

Use AskUserQuestion to determine the goal. Offer these presets:

Preset	Description
Stealth browsing	For scraping protected sites. Enables geoip, humanize, default OS fingerprint.
Fast scraping	Minimal footprint. Blocks images, WebRTC, WebGL. Enables disk cache.
Google-safe	For Google search without "unusual traffic" blocks. Enables geoip, humanize, random OS.
Custom	Walk through each option group interactively.

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.

Key	Type	Description
os	string or string[]	Target OS fingerprint
blockImages	boolean	Block image loading
blockWebrtc	boolean	Block WebRTC
blockWebgl	boolean	Block WebGL
disableCoop	boolean	Disable COOP headers
geoip	string or boolean	GeoIP spoofing (true or country code)
humanize	boolean or number	Human-like delays (true or speed factor)
locale	string or string[]	Browser locale
addons	string[]	Firefox addon paths
fonts	string[]	Custom fonts
customFontsOnly	boolean	Only use custom fonts
screen	object	Screen size range ({minWidth, maxWidth, minHeight, maxHeight})
window	[number, number]	Fixed window size
fingerprint	object	Fingerprint overrides
ffVersion	number	Firefox version
headless	boolean or "virtual"	Headless mode
mainWorldEval	boolean	Main world eval
firefoxUserPrefs	Record	Firefox about:config prefs
proxy	string or object	Proxy config
enableCache	boolean	Enable disk cache
debug	boolean	Debug logging
excludeAddons	string[]	Addons to exclude
executablePath	string	Custom browser path
args	string[]	Extra browser args
env	Record	Environment variables
virtualDisplay	string	Virtual display (Linux)

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.