Browser Provider Setup Guide

Complete reference for connecting your AI agents to browsers — local, remote, or cloud-hosted.

Quick Comparison

Provider	Best For	Video Calls	Difficulty	Cost
Local Chromium	Web scraping, form filling, screenshots	No (headless) / Yes (headed + display)	Easy	Free
Remote CDP	Video calls, persistent sessions, full control	Yes	Medium	VM cost only
Browserless.io	Scalable scraping, stealth, managed infra	No	Easy	Free tier available
Browserbase	AI automation, session replay, anti-detection	No	Easy	Free tier available
Steel.dev	Self-hostable, AI-native, open-source	No	Medium	Free (self-hosted)
ScrapingBee	Proxy rotation, CAPTCHA solving	No	Easy	Free tier available

1. Local Chromium (Default)

The simplest option. A headless Chromium browser runs on the same machine as AgenticMail. No external services needed.

When to use

Web scraping and data extraction
Taking screenshots of web pages
Filling out forms and automating websites
Any task that doesn't need camera, microphone, or visible display

Setup

No setup needed — it's the default. Chromium is auto-detected (Google Chrome, system Chromium, or Playwright's bundled Chromium). If none found, we install Playwright Chromium automatically on first launch.

Headed mode: If your server has a display (desktop machine, not headless server), switch to "Headed" in the dashboard to see the browser window. Useful for debugging.

Troubleshooting

Issue	Solution
Chromium not found	We auto-install on first use. If it fails, check disk space (~300MB needed).
Missing dependencies on Linux	`apt-get install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libdrm2 libxcomposite1 libxdamage1 libxrandr2 libgbm1 libpango-1.0-0 libasound2`
"Display not available" in headed mode	Headed mode requires X11/Wayland. Use headless on servers, or install Xvfb: `apt-get install xvfb && Xvfb :99 &`
Timeout on navigation	Increase timeout in browser settings. Some sites need longer with JS rendering.

2. Remote Browser (CDP)

Connect to a Chrome browser running on another machine. The agent controls it remotely via Chrome DevTools Protocol. This is the only option that supports video calls (Google Meet, Teams, Zoom) because it can access a real camera, microphone, and display.

When to use

Video calls and meetings (Google Meet, Microsoft Teams, Zoom)
Persistent browser sessions (stay logged in across restarts)
When you need a real display, camera, or microphone
Agent on headless server but needs browser GUI

What you need

A machine with Google Chrome installed (any OS)
Chrome launched with remote debugging enabled
Network access between your AgenticMail server and that machine

Setup: macOS

Step 1: Open Terminal on the Mac where Chrome should run.

Step 2: Launch Chrome with remote debugging:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --remote-debugging-address=0.0.0.0 \
  --user-data-dir=/tmp/chrome-remote \
  --no-first-run

Step 3: In AgenticMail dashboard, enter: 192.168.x.x:9222 (the Mac's IP)

Step 4: Click "Test Connection" — you should see the Chrome version.

Run at startup: Add the command to Login Items in System Settings, or create a Launch Agent plist at ~/Library/LaunchAgents/com.chrome.remote.plist.

Setup: Linux (Ubuntu/Debian)

Step 1: Install Chrome:

wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo gpg --dearmor -o /usr/share/keyrings/google-chrome.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/google-chrome.gpg] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt-get update && sudo apt-get install -y google-chrome-stable

Step 2: For headless servers (no display), install virtual display:

sudo apt-get install -y xvfb pulseaudio
Xvfb :99 -screen 0 1920x1080x24 &
export DISPLAY=:99
pulseaudio --start

Step 3: Launch Chrome:

google-chrome-stable \
  --remote-debugging-port=9222 \
  --remote-debugging-address=0.0.0.0 \
  --no-sandbox --disable-gpu \
  --user-data-dir=/tmp/chrome-remote \
  --no-first-run &

Step 4: Enter your-server-ip:9222 in the dashboard.

For video calls on Linux: Virtual camera: sudo apt install v4l2loopback-dkms. Virtual audio: PulseAudio virtual sinks.

Setup: Windows

Step 1: Open PowerShell:

& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
  --remote-debugging-port=9222 `
  --remote-debugging-address=0.0.0.0 `
  --user-data-dir="$env:TEMP\chrome-remote" `
  --no-first-run

Step 2: Allow Chrome through Windows Firewall when prompted.

Step 3: Enter the Windows machine's IP:9222 in the dashboard.

Setup: Cloud VMs

Provider	Recommended	Notes
AWS	EC2 Ubuntu Desktop / WorkSpaces	t3.medium+. Open port 9222 in security group (restrict to your AgenticMail IP).
Azure	Virtual Desktop or VM	B2s+. Open port 9222 in NSG.
Google Cloud	Compute Engine with Desktop	e2-medium+. Open port 9222 in firewall.
Hetzner	Cloud Server with Ubuntu Desktop	Cost-effective (~€4/mo). Open port 9222.
DigitalOcean	Droplet with Desktop	2GB+ RAM. Open port 9222.

Follow the Linux setup above, then configure firewall to only allow your AgenticMail server's IP.

Securing the Connection

Security: Chrome's debug port has NO authentication by default. Anyone who reaches port 9222 has full browser control. Always restrict access.

Option A: Firewall (simplest)

# Linux (ufw)
sudo ufw allow from YOUR_AGENTICMAIL_IP to any port 9222

# Linux (iptables)
sudo iptables -A INPUT -p tcp --dport 9222 -s YOUR_AGENTICMAIL_IP -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 9222 -j DROP

Option B: SSH Tunnel (most secure)

Don't expose port 9222 publicly
In the dashboard, set Remote Browser Address to localhost:9222
In SSH Tunnel field, enter: user@remote-host
We auto-create the tunnel before connecting — all traffic encrypted

Troubleshooting

Issue	Solution
"Cannot connect to CDP"	Check: Chrome running with --remote-debugging-port, firewall allows it, IP/port correct
"Connection refused"	Ensure `--remote-debugging-address=0.0.0.0` is set, or use SSH tunnel
"WebSocket handshake failed"	Use host:port format (e.g. `192.168.1.100:9222`) — we auto-discover the WebSocket URL
No camera in video call	Remote machine needs a camera (physical or virtual). Linux: `sudo modprobe v4l2loopback`
No audio	Install PulseAudio on Linux. macOS/Windows: works automatically.
SSH tunnel fails	Check: SSH key configured (no password), host reachable, user has access

3. Browserless.io

Managed cloud browser service. Chrome in the cloud, connect via API token. Scalable and maintenance-free.

Setup

Sign up at browserless.io
Copy your API token from the dashboard
Paste in AgenticMail → Browser → Browserless → API Token
Click "Test Connection"

Self-hosted

docker run -d --name browserless -p 3000:3000 -e TOKEN=your-secret ghcr.io/browserless/chromium

Set endpoint to ws://your-server:3000.

No video calls. Cloud browsers don't have camera/mic. Use Remote CDP for meetings.

4. Browserbase

AI-native cloud browser. Session replay, anti-detection, built for agent automation.

Setup

Sign up at browserbase.com
Copy API key from Settings
Copy Project ID from dashboard
Enter both in AgenticMail → Browser → Browserbase
"Test Connection"

Session replay: Watch exactly what your agent did at browserbase.com.

5. Steel.dev

Open-source browser API for AI agents. Self-host for free or use managed cloud.

Cloud setup

Sign up at app.steel.dev
Copy API key
Enter in AgenticMail → Browser → Steel

Self-hosted

docker run -d --name steel -p 3000:3000 ghcr.io/nichochar/steel-browser:latest

Set endpoint to http://your-server:3000.

6. ScrapingBee

Scraping API with proxy rotation and CAPTCHA solving. Routes your browser through their network for anti-detection.

Setup

Sign up at scrapingbee.com
Copy API key from dashboard
Enter in AgenticMail → Browser → ScrapingBee
"Test Connection" — shows remaining credits

Proxy-based: Works differently from other providers. Some advanced Playwright features (file uploads, complex interactions) may not work through the proxy. Use Browserless or Browserbase for those.

Security Best Practices

All providers

Domain allowlists: Restrict which websites agents can visit
Page limits: Limit concurrent pages to prevent runaway browsing
SSRF protection: Blocks navigation to internal IPs (enabled by default)
Rotate API keys: Change cloud provider keys periodically

Remote CDP

Never expose port 9222 publicly without firewall or SSH tunnel
Use SSH tunnels for encrypted connections
Dedicated Chrome profile (--user-data-dir) — don't use your personal browser
Non-root user on Linux
Keep Chrome updated

Cloud providers

Credentials encrypted in AgenticMail vault
IP allowlists on provider dashboards
Usage alerts for unusual activity

FAQ

Can I use video calls with cloud providers?

No. Cloud providers don't have camera/mic. Use Remote CDP for meetings.

Which provider is fastest?

Local Chromium (no network latency). For cloud: Browserless and Steel are fastest.

Can I switch providers without losing anything?

Yes. Sessions are independent. Switching takes effect on next browser action. Cookies don't transfer between providers.

What if cloud provider goes down?

Agent falls back to local Chromium automatically.

Multiple browsers for different tasks?

Each agent has its own browser config. Create different agents for different purposes.

AgenticMail Enterprise — Browser Provider Setup Guide

AgenticMail Enterprise Documentation Report an issue