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",
  "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.