browse.json

Overview

Create a browse.json file in your project root to set default options. Every command respects these settings unless overridden by CLI flags.

{
  "session": "my-agent",
  "json": true,
  "context": true,
  "contentBoundaries": true,
  "allowedDomains": ["example.com", "*.api.io"],
  "idleTimeout": 3600000,
  "viewport": "1280x720",
  "device": "iPhone 14",
  "runtime": "playwright"
}

Fields

Field	Type	Default	Description
`session`	`string`	`"default"`	Named session for isolation
`json`	`boolean`	`false`	Wrap output as `{success, data, command}`
`context`	`boolean`	`false`	Enable action context on write commands
`contentBoundaries`	`boolean`	`false`	Nonce-delimited output for LLM safety
`allowedDomains`	`string[]`	`[]`	Block navigation outside these domains
`idleTimeout`	`number`	`1800000`	Session auto-close timeout (ms)
`viewport`	`string`	`"1920x1080"`	Default viewport size
`device`	`string`	—	Device emulation preset
`runtime`	`string`	`"playwright"`	Browser runtime (playwright, rebrowser, lightpanda, camoufox, chrome)
`camoufox`	`object`	`{}`	Camoufox browser configuration (see below)

Camoufox Configuration

The camoufox section configures the camoufox-js anti-detection Firefox runtime. These options only take effect when using --runtime camoufox.

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

All 26 supported options (camelCase in config, auto-mapped to camoufox-js snake_case):

Field	Type	Description
`os`	`string \| string[]`	Target OS fingerprint. Array = random per launch.
`blockImages`	`boolean`	Block image loading
`blockWebrtc`	`boolean`	Block WebRTC (prevents IP leak)
`blockWebgl`	`boolean`	Block WebGL
`disableCoop`	`boolean`	Disable COOP headers
`geoip`	`string \| boolean`	GeoIP spoofing. `true` = auto from exit IP. String = country code.
`humanize`	`boolean \| number`	Human-like interaction delays. `true` = default. Number = speed multiplier.
`locale`	`string \| string[]`	Browser locale
`addons`	`string[]`	Firefox addon paths (.xpi)
`fonts`	`string[]`	Custom font list
`customFontsOnly`	`boolean`	Only use custom fonts
`screen`	`object`	Screen size range: `{ minWidth, maxWidth, minHeight, maxHeight }`
`window`	`[number, number]`	Window size `[width, height]`
`fingerprint`	`object`	Fingerprint overrides
`ffVersion`	`number`	Firefox version to emulate
`headless`	`boolean \| "virtual"`	Headless mode. `"virtual"` requires Xvfb on Linux.
`mainWorldEval`	`boolean`	Enable main world evaluation
`firefoxUserPrefs`	`object`	Firefox about:config preferences
`proxy`	`string \| object`	Proxy config. String = URL. Object = `{ server, username, password }`
`enableCache`	`boolean`	Enable disk cache
`debug`	`boolean`	Debug mode
`excludeAddons`	`string[]`	Addons to exclude from default set
`executablePath`	`string`	Custom Firefox binary path
`args`	`string[]`	Extra browser launch arguments
`env`	`object`	Environment variables for the browser process
`virtualDisplay`	`string`	Virtual display (Linux, e.g. `":99"`)

Named Profiles

Save per-scenario presets as .browse/camoufox-profiles/<name>.json:

// .browse/camoufox-profiles/stealth-google.json
{
  "geoip": true,
  "humanize": true,
  "os": ["windows", "macos", "linux"],
  "blockWebrtc": true
}

Use with --camoufox-profile:

browse --runtime camoufox --camoufox-profile stealth-google goto https://google.com

Profile values merge over browse.json defaults — profile wins on conflict.

List available profiles:

browse profiles

Precedence

CLI flags override browse.json values. Environment variables override both.

CLI flags > Environment variables > browse.json > Built-in defaults

Overview

Fields

Camoufox Configuration

Named Profiles

Precedence

On this page