Configuration

Create an agent-browser.json file to set persistent defaults instead of repeating flags on every command.

Config File Locations

agent-browser checks two locations, merged in priority order:

Priority	Location	Scope
1 (lowest)	`~/.agent-browser/config.json`	User-level defaults
2	`./agent-browser.json`	Project-level overrides
3	`AGENT_BROWSER_*` env vars	Override config values
4 (highest)	CLI flags	Override everything

Project-level values override user-level values. Environment variables override both. CLI flags always win.

Use --config <path> or the AGENT_BROWSER_CONFIG environment variable to load a specific config file instead of the default locations:

agent-browser --config ./ci-config.json open example.com
AGENT_BROWSER_CONFIG=./ci-config.json agent-browser open example.com

Example Config

{
  "headed": true,
  "proxy": "http://localhost:8080",
  "profile": "./browser-data",
  "userAgent": "my-agent/1.0",
  "ignoreHttpsErrors": true
}

All Options

Every CLI flag can be set in the config file using its camelCase equivalent:

Config Key	CLI Flag	Type
`headed`	`--headed`	boolean
`json`	`--json`	boolean
`full`	`--full, -f`	boolean
`debug`	`--debug`	boolean
`session`	`--session`	string
`sessionName`	`--session-name`	string
`executablePath`	`--executable-path`	string
`extensions`	`--extension`	string[]
`profile`	`--profile`	string
`state`	`--state`	string
`proxy`	`--proxy`	string
`proxyBypass`	`--proxy-bypass`	string
`args`	`--args`	string
`userAgent`	`--user-agent`	string
`provider`	`-p, --provider`	string
`device`	`--device`	string
`ignoreHttpsErrors`	`--ignore-https-errors`	boolean
`allowFileAccess`	`--allow-file-access`	boolean
`cdp`	`--cdp`	string
`autoConnect`	`--auto-connect`	boolean
`colorScheme`	`--color-scheme`	string (`dark`, `light`, `no-preference`)
`downloadPath`	`--download-path`	string
`contentBoundaries`	`--content-boundaries`	boolean
`maxOutput`	`--max-output`	number
`allowedDomains`	`--allowed-domains`	string[]
`actionPolicy`	`--action-policy`	string
`confirmActions`	`--confirm-actions`	string
`confirmInteractive`	`--confirm-interactive`	boolean
`headers`	`--headers`	string (JSON)

Common Configurations

Local Development

{
  "headed": true,
  "profile": "./browser-data"
}

Behind a Proxy

{
  "proxy": "http://proxy.corp.example.com:8080",
  "proxyBypass": "localhost,*.internal.com",
  "ignoreHttpsErrors": true
}

CI / Devcontainer

{
  "args": "--no-sandbox,--disable-gpu",
  "ignoreHttpsErrors": true
}

iOS Testing

{
  "provider": "ios",
  "device": "iPhone 16 Pro"
}

AI Agent Security

{
  "contentBoundaries": true,
  "maxOutput": 50000,
  "allowedDomains": ["your-app.com", "*.your-app.com"],
  "actionPolicy": "./policy.json"
}

Overriding Boolean Options

Boolean flags accept an optional true/false value to override config settings:

agent-browser --headed false open example.com

A bare flag is equivalent to passing true:

agent-browser --headed open example.com       # same as --headed true
agent-browser --headed true open example.com  # explicit

This applies to all boolean flags: --headed, --debug, --json, --ignore-https-errors, --allow-file-access, --auto-connect, --content-boundaries, --confirm-interactive.

Extensions Merging

Extensions from user-level and project-level configs are concatenated, not replaced. For example, if ~/.agent-browser/config.json specifies ["/ext1"] and ./agent-browser.json specifies ["/ext2"], the result is ["/ext1", "/ext2"].

The AGENT_BROWSER_EXTENSIONS environment variable and CLI --extension flags follow the standard priority rules (env replaces config, CLI appends).

Environment Variables

These environment variables configure additional daemon and runtime behavior:

Variable	Description	Default
`AGENT_BROWSER_AUTO_CONNECT`	Auto-discover and connect to a running Chrome instance.	(disabled)
`AGENT_BROWSER_ALLOW_FILE_ACCESS`	Allow `file://` URLs to access local files.	(disabled)
`AGENT_BROWSER_COLOR_SCHEME`	Color scheme preference (`dark`, `light`, `no-preference`).	(none)
`AGENT_BROWSER_DOWNLOAD_PATH`	Default directory for browser downloads.	(temp directory)
`AGENT_BROWSER_DEFAULT_TIMEOUT`	Default Playwright timeout in ms. Keep below 30000 to avoid IPC timeouts.	`25000`
`AGENT_BROWSER_SESSION_NAME`	Auto-save/load state persistence name.	(none)
`AGENT_BROWSER_STATE_EXPIRE_DAYS`	Auto-delete saved session states older than N days.	`30`
`AGENT_BROWSER_ENCRYPTION_KEY`	64-char hex key for AES-256-GCM session encryption.	(none)
`AGENT_BROWSER_STREAM_PORT`	Enable WebSocket streaming on the specified port (e.g., `9223`).	(disabled)
`AGENT_BROWSER_IOS_DEVICE`	Default iOS device name for the `ios` provider.	(none)
`AGENT_BROWSER_IOS_UDID`	Default iOS device UDID for the `ios` provider.	(none)
`AGENT_BROWSER_DEBUG`	Enable debug output (`1` to enable).	(disabled)
`AGENT_BROWSER_CONTENT_BOUNDARIES`	Wrap page output in boundary markers for LLM safety.	(disabled)
`AGENT_BROWSER_MAX_OUTPUT`	Max characters for page output (truncates beyond limit).	(unlimited)
`AGENT_BROWSER_ALLOWED_DOMAINS`	Comma-separated allowed domain patterns (e.g., `example.com,*.example.com`).	(unrestricted)
`AGENT_BROWSER_ACTION_POLICY`	Path to action policy JSON file.	(none)
`AGENT_BROWSER_CONFIRM_ACTIONS`	Comma-separated action categories requiring confirmation.	(none)
`AGENT_BROWSER_CONFIRM_INTERACTIVE`	Enable interactive confirmation prompts (auto-denies if stdin is not a TTY).	(disabled)

Error Handling

Auto-discovered config files (~/.agent-browser/config.json, ./agent-browser.json) that are missing are silently ignored.
--config <path> with a missing or malformed file exits with an error.
Malformed JSON in auto-discovered files prints a warning to stderr and continues without that file.
Unknown keys are silently ignored for forward compatibility.

Tip: If your project-level agent-browser.json contains environment-specific values (paths, proxies), consider adding it to .gitignore.