Skip to main content

​
Overview

Create an agent-browser.json file to set persistent defaults instead of repeating flags on every command. Configuration files use a priority-based system where CLI flags always take precedence.

​
Configuration Precedence

Settings are loaded in the following order (lowest to highest priority):
PriorityLocationDescription
1 (lowest)~/.agent-browser/config.jsonUser-level defaults
2./agent-browser.jsonProject-level overrides (in working directory)
3AGENT_BROWSER_* environment variablesEnvironment-specific overrides
4 (highest)CLI flagsCommand-specific overrides
Higher priority settings override lower priority ones. For example, a CLI flag overrides an environment variable, which overrides a project config file, which overrides a user config file.

​
Custom Config Files

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
When using a custom config file:
  • If the file is missing or invalid, agent-browser exits with an error
  • Auto-discovered config files (~/.agent-browser/config.json, ./agent-browser.json) are still loaded if they exist
  • The custom config file has priority between project config and environment variables

​
Config File Format

All CLI options can be set in the config file using camelCase keys. For example, --executable-path becomes "executablePath", and --proxy-bypass becomes "proxyBypass".

​
Example Config

{
  "headed": true,
  "proxy": "http://localhost:8080",
  "profile": "./browser-data",
  "userAgent": "my-agent/1.0",
  "ignoreHttpsErrors": true,
  "colorScheme": "dark",
  "downloadPath": "./downloads",
  "allowedDomains": ["example.com", "*.example.com"]
}
See src/daemon.ts:434-481 for the complete list of environment variables that map to config options.

​
Available Options

Config KeyCLI FlagTypeDescription
headed—headedbooleanShow browser window (not headless)
profile—profilestringPersistent browser profile directory
executablePath—executable-pathstringCustom browser executable path
extensions—extensionstring[]Browser extension paths (repeatable)
args—argsstring[]Browser launch arguments
userAgent—user-agentstringCustom User-Agent string
proxy—proxystringProxy server URL
proxyBypass—proxy-bypassstringHosts to bypass proxy
ignoreHttpsErrors—ignore-https-errorsbooleanIgnore HTTPS certificate errors
allowFileAccess—allow-file-accessbooleanAllow file:// URL access (Chromium only)
colorScheme—color-schemestringColor scheme: dark, light, no-preference
downloadPath—download-pathstringDefault download directory
allowedDomains—allowed-domainsstring[]Allowed domain patterns (security)
actionPolicy—action-policystringPath to action policy JSON file
confirmActions—confirm-actionsstringAction categories requiring confirmation
contentBoundaries—content-boundariesbooleanWrap page output in boundary markers
maxOutput—max-outputnumberMax characters for page output

​
Boolean Flags

Boolean flags accept an optional true/false value to override config settings: 
# Override "headed": true from config
agent-browser --headed false open example.com

# Bare flag is equivalent to true
agent-browser --headed open example.com

​
Extension Merging

Extensions from user and project configs are concatenated, not replaced. For example:
  • ~/.agent-browser/config.json specifies ["extensions": ["/ext1"]
  • ./agent-browser.json specifies "extensions": ["/ext2"]
  • Result: ["/ext1", "/ext2"]
This allows user-level extensions (like ad blockers) to coexist with project-specific extensions.

​
Environment Variables

All config options can also be set via environment variables using the AGENT_BROWSER_ prefix: 
export AGENT_BROWSER_HEADED=1
export AGENT_BROWSER_PROFILE=~/.myapp-profile
export AGENT_BROWSER_USER_AGENT="my-agent/1.0"
agent-browser open example.com
Boolean values use 1 for true and 0 for false. See the README for the complete list of environment variables.

​
Config File Validation

  • Auto-discovered config files (~/.agent-browser/config.json, ./agent-browser.json) that are missing are silently ignored.
  • Explicitly specified config files (via --config or AGENT_BROWSER_CONFIG) must exist and be valid JSON, or agent-browser exits with an error.
  • Unknown keys in config files are ignored for forward compatibility.

​
Use Cases

​
User-Level Defaults

Create ~/.agent-browser/config.json for settings you want across all projects: 
{
  "headed": false,
  "colorScheme": "dark",
  "ignoreHttpsErrors": true
}

​
Project-Level Overrides

Create ./agent-browser.json in your project for project-specific settings: 
{
  "profile": "./browser-profile",
  "allowedDomains": ["myapp.com", "*.myapp.com"],
  "downloadPath": "./downloads"
}
Consider adding agent-browser.json to .gitignore if it contains environment-specific values like paths or proxies.

​
CI/CD Config

Use a separate config file for CI environments: 
{
  "headless": true,
  "ignoreHttpsErrors": true,
  "args": ["--no-sandbox", "--disable-setuid-sandbox"]
}
Then load it with: 
AGENT_BROWSER_CONFIG=./ci-config.json agent-browser open example.com

​
Security Considerations

Configuration files may contain sensitive settings like:
  • Proxy credentials in proxy field
  • Custom headers in headers field
  • Download paths that expose directory structure
Protect config files with appropriate file permissions: 
chmod 600 ~/.agent-browser/config.json
chmod 600 ./agent-browser.json
Consider using environment variables for sensitive values instead of committing them to config files.

Build docs developers (and LLMs) love

Get started for freeTalk to us