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

# Environment Variables

> Complete reference of all environment variables for Agent Browser

# Environment Variables

Agent Browser can be configured using environment variables as an alternative to CLI flags. Environment variables take precedence over config files but are overridden by CLI flags.

## Session Management

Variables for managing browser sessions and state.

<table>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Description</th>
      <th>Example</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>AGENT\_BROWSER\_SESSION</code></td>
      <td>Default session name (equivalent to <code>--session</code>)</td>
      <td><code>AGENT\_BROWSER\_SESSION=mysession</code></td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_SESSION\_NAME</code></td>
      <td>Auto-save/load state persistence name</td>
      <td><code>AGENT\_BROWSER\_SESSION\_NAME=twitter</code></td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_PROFILE</code></td>
      <td>Persistent browser profile directory</td>
      <td><code>AGENT\_BROWSER\_PROFILE=\~/.myapp-profile</code></td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_STATE</code></td>
      <td>Path to storage state JSON file</td>
      <td><code>AGENT\_BROWSER\_STATE=./auth-state.json</code></td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_STATE\_EXPIRE\_DAYS</code></td>
      <td>Auto-delete states older than N days (default: 30)</td>
      <td><code>AGENT\_BROWSER\_STATE\_EXPIRE\_DAYS=7</code></td>
    </tr>
  </tbody>
</table>

## Browser Configuration

Variables for configuring the browser instance.

<table>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Description</th>
      <th>Example</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>AGENT\_BROWSER\_HEADED</code></td>
      <td>Show browser window (set to <code>1</code> to enable)</td>
      <td><code>AGENT\_BROWSER\_HEADED=1</code></td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_EXECUTABLE\_PATH</code></td>
      <td>Custom browser executable path</td>
      <td><code>AGENT\_BROWSER\_EXECUTABLE\_PATH=/usr/bin/chromium</code></td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_EXTENSIONS</code></td>
      <td>Comma-separated extension paths</td>
      <td><code>AGENT\_BROWSER\_EXTENSIONS=/ext1,/ext2</code></td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_ARGS</code></td>
      <td>Browser launch arguments (comma or newline separated)</td>
      <td><code>AGENT\_BROWSER\_ARGS=--no-sandbox,--disable-gpu</code></td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_USER\_AGENT</code></td>
      <td>Custom User-Agent string</td>
      <td><code>AGENT\_BROWSER\_USER\_AGENT="MyBot/1.0"</code></td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_COLOR\_SCHEME</code></td>
      <td>Color scheme: <code>dark</code>, <code>light</code>, <code>no-preference</code></td>
      <td><code>AGENT\_BROWSER\_COLOR\_SCHEME=dark</code></td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_IGNORE\_HTTPS\_ERRORS</code></td>
      <td>Ignore HTTPS certificate errors (set to <code>1</code> to enable)</td>
      <td><code>AGENT\_BROWSER\_IGNORE\_HTTPS\_ERRORS=1</code></td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_ALLOW\_FILE\_ACCESS</code></td>
      <td>Allow file:// URLs to access local files (set to <code>1</code> to enable)</td>
      <td><code>AGENT\_BROWSER\_ALLOW\_FILE\_ACCESS=1</code></td>
    </tr>
  </tbody>
</table>

## Network Configuration

Variables for network settings.

<table>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Description</th>
      <th>Example</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>AGENT\_BROWSER\_PROXY</code></td>
      <td>Proxy server URL with optional auth</td>
      <td><code>AGENT\_BROWSER\_PROXY=[http://user:pass@proxy:8080](http://user:pass@proxy:8080)</code></td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_PROXY\_BYPASS</code></td>
      <td>Comma-separated hosts to bypass proxy</td>
      <td><code>AGENT\_BROWSER\_PROXY\_BYPASS=localhost,127.0.0.1</code></td>
    </tr>
  </tbody>
</table>

## Cloud Providers

Variables for cloud browser providers.

<table>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Description</th>
      <th>Example</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>AGENT\_BROWSER\_PROVIDER</code></td>
      <td>Cloud browser provider: <code>browserbase</code>, <code>browseruse</code>, <code>kernel</code>, <code>ios</code></td>
      <td><code>AGENT\_BROWSER\_PROVIDER=browserbase</code></td>
    </tr>

    <tr>
      <td><code>BROWSERBASE\_API\_KEY</code></td>
      <td>Browserbase API key</td>
      <td><code>BROWSERBASE\_API\_KEY=your-api-key</code></td>
    </tr>

    <tr>
      <td><code>BROWSERBASE\_PROJECT\_ID</code></td>
      <td>Browserbase project ID</td>
      <td><code>BROWSERBASE\_PROJECT\_ID=your-project-id</code></td>
    </tr>

    <tr>
      <td><code>BROWSER\_USE\_API\_KEY</code></td>
      <td>Browser Use API key</td>
      <td><code>BROWSER\_USE\_API\_KEY=your-api-key</code></td>
    </tr>

    <tr>
      <td><code>KERNEL\_API\_KEY</code></td>
      <td>Kernel API key</td>
      <td><code>KERNEL\_API\_KEY=your-api-key</code></td>
    </tr>

    <tr>
      <td><code>KERNEL\_HEADLESS</code></td>
      <td>Run Kernel browser in headless mode (<code>true</code>/<code>false</code>)</td>
      <td><code>KERNEL\_HEADLESS=false</code></td>
    </tr>

    <tr>
      <td><code>KERNEL\_STEALTH</code></td>
      <td>Enable Kernel stealth mode (<code>true</code>/<code>false</code>)</td>
      <td><code>KERNEL\_STEALTH=true</code></td>
    </tr>

    <tr>
      <td><code>KERNEL\_TIMEOUT\_SECONDS</code></td>
      <td>Kernel session timeout in seconds</td>
      <td><code>KERNEL\_TIMEOUT\_SECONDS=300</code></td>
    </tr>

    <tr>
      <td><code>KERNEL\_PROFILE\_NAME</code></td>
      <td>Kernel browser profile name for persistent state</td>
      <td><code>KERNEL\_PROFILE\_NAME=my-profile</code></td>
    </tr>
  </tbody>
</table>

## iOS Provider

Variables for iOS simulator/device control.

<table>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Description</th>
      <th>Example</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>AGENT\_BROWSER\_IOS\_DEVICE</code></td>
      <td>iOS device name (e.g., "iPhone 15 Pro", "iPad Pro")</td>
      <td><code>AGENT\_BROWSER\_IOS\_DEVICE="iPhone 16 Pro"</code></td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_IOS\_UDID</code></td>
      <td>iOS device UDID (alternative to device name)</td>
      <td><code>AGENT\_BROWSER\_IOS\_UDID=12345678-ABCD...</code></td>
    </tr>
  </tbody>
</table>

## CDP Connection

Variables for Chrome DevTools Protocol.

<table>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Description</th>
      <th>Example</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>AGENT\_BROWSER\_AUTO\_CONNECT</code></td>
      <td>Auto-discover and connect to running Chrome (set to <code>1</code> to enable)</td>
      <td><code>AGENT\_BROWSER\_AUTO\_CONNECT=1</code></td>
    </tr>
  </tbody>
</table>

## Security

Variables for security features.

<table>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Description</th>
      <th>Example</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>AGENT\_BROWSER\_CONTENT\_BOUNDARIES</code></td>
      <td>Wrap page output in boundary markers (set to <code>1</code> to enable)</td>
      <td><code>AGENT\_BROWSER\_CONTENT\_BOUNDARIES=1</code></td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_MAX\_OUTPUT</code></td>
      <td>Truncate page output to N characters</td>
      <td><code>AGENT\_BROWSER\_MAX\_OUTPUT=50000</code></td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_ALLOWED\_DOMAINS</code></td>
      <td>Comma-separated allowed domain patterns</td>
      <td><code>AGENT\_BROWSER\_ALLOWED\_DOMAINS="example.com,\*.example.com"</code></td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_ACTION\_POLICY</code></td>
      <td>Path to action policy JSON file</td>
      <td><code>AGENT\_BROWSER\_ACTION\_POLICY=./policy.json</code></td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_CONFIRM\_ACTIONS</code></td>
      <td>Action categories requiring confirmation (comma-separated)</td>
      <td><code>AGENT\_BROWSER\_CONFIRM\_ACTIONS=eval,download</code></td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_CONFIRM\_INTERACTIVE</code></td>
      <td>Enable interactive confirmation prompts (set to <code>1</code> to enable)</td>
      <td><code>AGENT\_BROWSER\_CONFIRM\_INTERACTIVE=1</code></td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_ENCRYPTION\_KEY</code></td>
      <td>64-character hex key for AES-256-GCM encryption of saved states</td>
      <td><code>AGENT\_BROWSER\_ENCRYPTION\_KEY=\$(openssl rand -hex 32)</code></td>
    </tr>
  </tbody>
</table>

## Output Configuration

Variables for output formatting.

<table>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Description</th>
      <th>Example</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>AGENT\_BROWSER\_JSON</code></td>
      <td>Output as JSON (set to <code>1</code> to enable)</td>
      <td><code>AGENT\_BROWSER\_JSON=1</code></td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_DEBUG</code></td>
      <td>Enable debug output (set to <code>1</code> to enable)</td>
      <td><code>AGENT\_BROWSER\_DEBUG=1</code></td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_ANNOTATE</code></td>
      <td>Annotated screenshots with numbered element labels (set to <code>1</code> to enable)</td>
      <td><code>AGENT\_BROWSER\_ANNOTATE=1</code></td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_FULL</code></td>
      <td>Full page screenshots (set to <code>1</code> to enable)</td>
      <td><code>AGENT\_BROWSER\_FULL=1</code></td>
    </tr>
  </tbody>
</table>

## Download Configuration

Variables for download behavior.

<table>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Description</th>
      <th>Example</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>AGENT\_BROWSER\_DOWNLOAD\_PATH</code></td>
      <td>Default download directory</td>
      <td><code>AGENT\_BROWSER\_DOWNLOAD\_PATH=/tmp/downloads</code></td>
    </tr>
  </tbody>
</table>

## Timeouts

Variables for timeout configuration.

<table>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Description</th>
      <th>Example</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>AGENT\_BROWSER\_DEFAULT\_TIMEOUT</code></td>
      <td>Default Playwright timeout in milliseconds (default: 25000)</td>
      <td><code>AGENT\_BROWSER\_DEFAULT\_TIMEOUT=45000</code></td>
    </tr>
  </tbody>
</table>

## Streaming

Variables for browser streaming.

<table>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Description</th>
      <th>Example</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>AGENT\_BROWSER\_STREAM\_PORT</code></td>
      <td>WebSocket streaming port for live browser preview</td>
      <td><code>AGENT\_BROWSER\_STREAM\_PORT=9223</code></td>
    </tr>
  </tbody>
</table>

## Configuration File

Variables for loading configuration.

<table>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Description</th>
      <th>Example</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>AGENT\_BROWSER\_CONFIG</code></td>
      <td>Path to custom config file</td>
      <td><code>AGENT\_BROWSER\_CONFIG=./custom-config.json</code></td>
    </tr>
  </tbody>
</table>

## Internal Variables

These variables are used internally and typically should not be set manually.

<table>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Description</th>
      <th>Notes</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>AGENT\_BROWSER\_SOCKET\_DIR</code></td>
      <td>Custom socket directory for daemon IPC</td>
      <td>Advanced use only. Defaults to XDG\_RUNTIME\_DIR or \~/.agent-browser</td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_DAEMON</code></td>
      <td>Internal flag to indicate daemon mode</td>
      <td>Set automatically by the daemon process</td>
    </tr>
  </tbody>
</table>

## Boolean Values

For boolean environment variables, the following values are considered truthy:

* Any non-empty value except `0`, `false`, or `no` (case-insensitive)

Examples:

```bash theme={null}
# Truthy (enable)
AGENT_BROWSER_HEADED=1
AGENT_BROWSER_HEADED=true
AGENT_BROWSER_HEADED=TRUE
AGENT_BROWSER_HEADED=yes

# Falsy (disable)
AGENT_BROWSER_HEADED=0
AGENT_BROWSER_HEADED=false
AGENT_BROWSER_HEADED=no
AGENT_BROWSER_HEADED=  # Empty string
```

## Priority Order

Configuration sources are applied in this order (lowest to highest priority):

1. `~/.agent-browser/config.json` (user-level defaults)
2. `./agent-browser.json` (project-level overrides)
3. Environment variables
4. CLI flags

CLI flags always take precedence over environment variables, which take precedence over config files.