Skip to main content

​
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.
VariableDescriptionExample
AGENT_BROWSER_SESSIONDefault session name (equivalent to —session)AGENT_BROWSER_SESSION=mysession
AGENT_BROWSER_SESSION_NAMEAuto-save/load state persistence nameAGENT_BROWSER_SESSION_NAME=twitter
AGENT_BROWSER_PROFILEPersistent browser profile directoryAGENT_BROWSER_PROFILE=~/.myapp-profile
AGENT_BROWSER_STATEPath to storage state JSON fileAGENT_BROWSER_STATE=./auth-state.json
AGENT_BROWSER_STATE_EXPIRE_DAYSAuto-delete states older than N days (default: 30)AGENT_BROWSER_STATE_EXPIRE_DAYS=7

​
Browser Configuration

Variables for configuring the browser instance.
VariableDescriptionExample
AGENT_BROWSER_HEADEDShow browser window (set to 1 to enable)AGENT_BROWSER_HEADED=1
AGENT_BROWSER_EXECUTABLE_PATHCustom browser executable pathAGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium
AGENT_BROWSER_EXTENSIONSComma-separated extension pathsAGENT_BROWSER_EXTENSIONS=/ext1,/ext2
AGENT_BROWSER_ARGSBrowser launch arguments (comma or newline separated)AGENT_BROWSER_ARGS=—no-sandbox,—disable-gpu
AGENT_BROWSER_USER_AGENTCustom User-Agent stringAGENT_BROWSER_USER_AGENT=“MyBot/1.0”
AGENT_BROWSER_COLOR_SCHEMEColor scheme: dark, light, no-preferenceAGENT_BROWSER_COLOR_SCHEME=dark
AGENT_BROWSER_IGNORE_HTTPS_ERRORSIgnore HTTPS certificate errors (set to 1 to enable)AGENT_BROWSER_IGNORE_HTTPS_ERRORS=1
AGENT_BROWSER_ALLOW_FILE_ACCESSAllow file:// URLs to access local files (set to 1 to enable)AGENT_BROWSER_ALLOW_FILE_ACCESS=1

​
Network Configuration

Variables for network settings.
VariableDescriptionExample
AGENT_BROWSER_PROXYProxy server URL with optional authAGENT_BROWSER_PROXY=http://user:pass@proxy:8080
AGENT_BROWSER_PROXY_BYPASSComma-separated hosts to bypass proxyAGENT_BROWSER_PROXY_BYPASS=localhost,127.0.0.1

​
Cloud Providers

Variables for cloud browser providers.
VariableDescriptionExample
AGENT_BROWSER_PROVIDERCloud browser provider: browserbase, browseruse, kernel, iosAGENT_BROWSER_PROVIDER=browserbase
BROWSERBASE_API_KEYBrowserbase API keyBROWSERBASE_API_KEY=your-api-key
BROWSERBASE_PROJECT_IDBrowserbase project IDBROWSERBASE_PROJECT_ID=your-project-id
BROWSER_USE_API_KEYBrowser Use API keyBROWSER_USE_API_KEY=your-api-key
KERNEL_API_KEYKernel API keyKERNEL_API_KEY=your-api-key
KERNEL_HEADLESSRun Kernel browser in headless mode (true/false)KERNEL_HEADLESS=false
KERNEL_STEALTHEnable Kernel stealth mode (true/false)KERNEL_STEALTH=true
KERNEL_TIMEOUT_SECONDSKernel session timeout in secondsKERNEL_TIMEOUT_SECONDS=300
KERNEL_PROFILE_NAMEKernel browser profile name for persistent stateKERNEL_PROFILE_NAME=my-profile

​
iOS Provider

Variables for iOS simulator/device control.
VariableDescriptionExample
AGENT_BROWSER_IOS_DEVICEiOS device name (e.g., “iPhone 15 Pro”, “iPad Pro”)AGENT_BROWSER_IOS_DEVICE=“iPhone 16 Pro”
AGENT_BROWSER_IOS_UDIDiOS device UDID (alternative to device name)AGENT_BROWSER_IOS_UDID=12345678-ABCD…

​
CDP Connection

Variables for Chrome DevTools Protocol.
VariableDescriptionExample
AGENT_BROWSER_AUTO_CONNECTAuto-discover and connect to running Chrome (set to 1 to enable)AGENT_BROWSER_AUTO_CONNECT=1

​
Security

Variables for security features.
VariableDescriptionExample
AGENT_BROWSER_CONTENT_BOUNDARIESWrap page output in boundary markers (set to 1 to enable)AGENT_BROWSER_CONTENT_BOUNDARIES=1
AGENT_BROWSER_MAX_OUTPUTTruncate page output to N charactersAGENT_BROWSER_MAX_OUTPUT=50000
AGENT_BROWSER_ALLOWED_DOMAINSComma-separated allowed domain patternsAGENT_BROWSER_ALLOWED_DOMAINS=“example.com,*.example.com”
AGENT_BROWSER_ACTION_POLICYPath to action policy JSON fileAGENT_BROWSER_ACTION_POLICY=./policy.json
AGENT_BROWSER_CONFIRM_ACTIONSAction categories requiring confirmation (comma-separated)AGENT_BROWSER_CONFIRM_ACTIONS=eval,download
AGENT_BROWSER_CONFIRM_INTERACTIVEEnable interactive confirmation prompts (set to 1 to enable)AGENT_BROWSER_CONFIRM_INTERACTIVE=1
AGENT_BROWSER_ENCRYPTION_KEY64-character hex key for AES-256-GCM encryption of saved statesAGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)

​
Output Configuration

Variables for output formatting.
VariableDescriptionExample
AGENT_BROWSER_JSONOutput as JSON (set to 1 to enable)AGENT_BROWSER_JSON=1
AGENT_BROWSER_DEBUGEnable debug output (set to 1 to enable)AGENT_BROWSER_DEBUG=1
AGENT_BROWSER_ANNOTATEAnnotated screenshots with numbered element labels (set to 1 to enable)AGENT_BROWSER_ANNOTATE=1
AGENT_BROWSER_FULLFull page screenshots (set to 1 to enable)AGENT_BROWSER_FULL=1

​
Download Configuration

Variables for download behavior.
VariableDescriptionExample
AGENT_BROWSER_DOWNLOAD_PATHDefault download directoryAGENT_BROWSER_DOWNLOAD_PATH=/tmp/downloads

​
Timeouts

Variables for timeout configuration.
VariableDescriptionExample
AGENT_BROWSER_DEFAULT_TIMEOUTDefault Playwright timeout in milliseconds (default: 25000)AGENT_BROWSER_DEFAULT_TIMEOUT=45000

​
Streaming

Variables for browser streaming.
VariableDescriptionExample
AGENT_BROWSER_STREAM_PORTWebSocket streaming port for live browser previewAGENT_BROWSER_STREAM_PORT=9223

​
Configuration File

Variables for loading configuration.
VariableDescriptionExample
AGENT_BROWSER_CONFIGPath to custom config fileAGENT_BROWSER_CONFIG=./custom-config.json

​
Internal Variables

These variables are used internally and typically should not be set manually.
VariableDescriptionNotes
AGENT_BROWSER_SOCKET_DIRCustom socket directory for daemon IPCAdvanced use only. Defaults to XDG_RUNTIME_DIR or ~/.agent-browser
AGENT_BROWSER_DAEMONInternal flag to indicate daemon modeSet automatically by the daemon process

​
Boolean Values

For boolean environment variables, the following values are considered truthy:
  • Any non-empty value except 0, false, or no (case-insensitive)
Examples: 
# 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us