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:

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",
  "hideScrollbars": false,
  "ignoreHttpsErrors": true
}

A JSON Schema is available for IDE autocomplete and validation. Add a $schema key to your config file to enable it:

{
  "$schema": "https://agent-browser.dev/schema.json",
  "headed": true
}

All Options#

Global launch, output, provider, and chat options can be set in the config file using their camelCase equivalent. Command-scoped flags such as screenshot --full remain command arguments.

Common Configurations#

Local Development#

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

Behind a Proxy#

{
  "proxy": "http://proxy.corp.example.com:8080",
  "proxyBypass": "localhost,*.internal.com",
  "caCert": "/etc/ssl/certs/proxy-ca.crt"
}

caCert imports the supplied CA certificate or PEM bundle into an isolated NSS database for locally launched Chromium on Linux. Hostname, validity period, and unrelated CA verification remain enabled. The CA remains active when later commands omit it. Setting different certificate content or clearCaCert: true relaunches Chromium without restarting the daemon. agent-browser install --with-deps installs the required certutil; otherwise install libnss3-tools on Debian/Ubuntu or nss-tools on RPM Linux. This initial implementation does not support Chrome profiles, CDP attach, providers, Lightpanda, macOS, or Windows.

Without the CA certificate on hand, fall back to ignoring every certificate error, which is less secure:

{
  "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 boolean flags such as --headed, --debug, --json, --ignore-https-errors, --allow-file-access, --hide-scrollbars, --auto-connect, --annotate, --content-boundaries, --confirm-interactive, and --no-auto-dialog.

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).

Plugins#

Configure external plugins with the plugins array:

See Plugins for the plugin author protocol and implementation examples. Use agent-browser plugin add <ref> to create this config automatically.

{
  "plugins": [
    {
      "name": "vault",
      "command": "agent-browser-plugin-vault",
      "args": [],
      "capabilities": ["credential.read"]
    },
    {
      "name": "cloud-browser",
      "command": "agent-browser-plugin-cloud-browser",
      "capabilities": ["browser.provider"]
    },
    {
      "name": "stealth",
      "command": "agent-browser-plugin-stealth",
      "capabilities": ["launch.mutate"]
    },
    {
      "name": "captcha",
      "command": "agent-browser-plugin-captcha",
      "capabilities": ["command.run", "captcha.solve"]
    }
  ]
}

Project-level plugin entries are appended after user-level entries. If two entries use the same name, agent-browser resolves the later entry, so a project can override a user default. AGENT_BROWSER_PLUGINS can replace config discovery with a JSON array using the same shape.

Do not put vault tokens or passwords in plugin command args. Use the vault vendor's own login/session mechanism or environment outside agent-browser config.

agent-browser plugin list
agent-browser auth login my-app --credential-provider vault --item "My App"
agent-browser --provider cloud-browser open https://example.com
agent-browser plugin run captcha captcha.solve --payload '{"siteKey":"...","url":"https://example.com"}'

plugin run is for command.run and custom capabilities. Core capabilities and protocol request types use their dedicated command paths.

Environment Variables#

These environment variables configure additional daemon and runtime behavior:

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.