> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vercel-labs/agent-browser/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure agent-browser with persistent config files

## 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):

<table>
  <thead>
    <tr>
      <th>Priority</th>
      <th>Location</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr><td>1 (lowest)</td><td><code>\~/.agent-browser/config.json</code></td><td>User-level defaults</td></tr>
    <tr><td>2</td><td><code>./agent-browser.json</code></td><td>Project-level overrides (in working directory)</td></tr>
    <tr><td>3</td><td><code>AGENT\_BROWSER\_\*</code> environment variables</td><td>Environment-specific overrides</td></tr>
    <tr><td>4 (highest)</td><td>CLI flags</td><td>Command-specific overrides</td></tr>
  </tbody>
</table>

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:

```bash theme={null}
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

```json theme={null}
{
  "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

<table>
  <thead>
    <tr>
      <th>Config Key</th>
      <th>CLI Flag</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr><td><code>headed</code></td><td><code>--headed</code></td><td>boolean</td><td>Show browser window (not headless)</td></tr>
    <tr><td><code>profile</code></td><td><code>--profile</code></td><td>string</td><td>Persistent browser profile directory</td></tr>
    <tr><td><code>executablePath</code></td><td><code>--executable-path</code></td><td>string</td><td>Custom browser executable path</td></tr>
    <tr><td><code>extensions</code></td><td><code>--extension</code></td><td>string\[]</td><td>Browser extension paths (repeatable)</td></tr>
    <tr><td><code>args</code></td><td><code>--args</code></td><td>string\[]</td><td>Browser launch arguments</td></tr>
    <tr><td><code>userAgent</code></td><td><code>--user-agent</code></td><td>string</td><td>Custom User-Agent string</td></tr>
    <tr><td><code>proxy</code></td><td><code>--proxy</code></td><td>string</td><td>Proxy server URL</td></tr>
    <tr><td><code>proxyBypass</code></td><td><code>--proxy-bypass</code></td><td>string</td><td>Hosts to bypass proxy</td></tr>
    <tr><td><code>ignoreHttpsErrors</code></td><td><code>--ignore-https-errors</code></td><td>boolean</td><td>Ignore HTTPS certificate errors</td></tr>
    <tr><td><code>allowFileAccess</code></td><td><code>--allow-file-access</code></td><td>boolean</td><td>Allow file:// URL access (Chromium only)</td></tr>
    <tr><td><code>colorScheme</code></td><td><code>--color-scheme</code></td><td>string</td><td>Color scheme: dark, light, no-preference</td></tr>
    <tr><td><code>downloadPath</code></td><td><code>--download-path</code></td><td>string</td><td>Default download directory</td></tr>
    <tr><td><code>allowedDomains</code></td><td><code>--allowed-domains</code></td><td>string\[]</td><td>Allowed domain patterns (security)</td></tr>
    <tr><td><code>actionPolicy</code></td><td><code>--action-policy</code></td><td>string</td><td>Path to action policy JSON file</td></tr>
    <tr><td><code>confirmActions</code></td><td><code>--confirm-actions</code></td><td>string</td><td>Action categories requiring confirmation</td></tr>
    <tr><td><code>contentBoundaries</code></td><td><code>--content-boundaries</code></td><td>boolean</td><td>Wrap page output in boundary markers</td></tr>
    <tr><td><code>maxOutput</code></td><td><code>--max-output</code></td><td>number</td><td>Max characters for page output</td></tr>
  </tbody>
</table>

## Boolean Flags

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

```bash theme={null}
# 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:

```bash theme={null}
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:

```json theme={null}
{
  "headed": false,
  "colorScheme": "dark",
  "ignoreHttpsErrors": true
}
```

### Project-Level Overrides

Create `./agent-browser.json` in your project for project-specific settings:

```json theme={null}
{
  "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:

```json theme={null}
{
  "headless": true,
  "ignoreHttpsErrors": true,
  "args": ["--no-sandbox", "--disable-setuid-sandbox"]
}
```

Then load it with:

```bash theme={null}
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:

```bash theme={null}
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.