@agenticmail/enterprise 0.5.236 → 0.5.238

package/dist/cli-serve-OHDYAC3L.js

@@ -0,0 +1,114 @@
+import "./chunk-KFQGP6VL.js";
+
+// src/cli-serve.ts
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+function loadEnvFile() {
+  const candidates = [
+    join(process.cwd(), ".env"),
+    join(homedir(), ".agenticmail", ".env")
+  ];
+  for (const envPath of candidates) {
+    if (!existsSync(envPath)) continue;
+    try {
+      const content = readFileSync(envPath, "utf8");
+      for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) continue;
+        const eq = trimmed.indexOf("=");
+        if (eq < 0) continue;
+        const key = trimmed.slice(0, eq).trim();
+        let val = trimmed.slice(eq + 1).trim();
+        if (val.startsWith('"') && val.endsWith('"') || val.startsWith("'") && val.endsWith("'")) {
+          val = val.slice(1, -1);
+        }
+        if (!process.env[key]) process.env[key] = val;
+      }
+      console.log(`Loaded config from ${envPath}`);
+      return;
+    } catch {
+    }
+  }
+}
+async function ensureSecrets() {
+  const { randomUUID } = await import("crypto");
+  const envDir = join(homedir(), ".agenticmail");
+  const envPath = join(envDir, ".env");
+  let dirty = false;
+  if (!process.env.JWT_SECRET) {
+    process.env.JWT_SECRET = randomUUID() + randomUUID();
+    dirty = true;
+    console.log("[startup] Generated new JWT_SECRET (existing sessions will need to re-login)");
+  }
+  if (!process.env.AGENTICMAIL_VAULT_KEY) {
+    process.env.AGENTICMAIL_VAULT_KEY = randomUUID() + randomUUID();
+    dirty = true;
+    console.log("[startup] Generated new AGENTICMAIL_VAULT_KEY");
+    console.log("[startup] \u26A0\uFE0F  Previously encrypted credentials will need to be re-entered in the dashboard");
+  }
+  if (dirty) {
+    try {
+      if (!existsSync(envDir)) {
+        const { mkdirSync } = await import("fs");
+        mkdirSync(envDir, { recursive: true });
+      }
+      const { appendFileSync } = await import("fs");
+      const lines = [];
+      let existing = "";
+      if (existsSync(envPath)) {
+        existing = readFileSync(envPath, "utf8");
+      }
+      if (!existing.includes("JWT_SECRET=")) {
+        lines.push(`JWT_SECRET=${process.env.JWT_SECRET}`);
+      }
+      if (!existing.includes("AGENTICMAIL_VAULT_KEY=")) {
+        lines.push(`AGENTICMAIL_VAULT_KEY=${process.env.AGENTICMAIL_VAULT_KEY}`);
+      }
+      if (lines.length) {
+        appendFileSync(envPath, "\n" + lines.join("\n") + "\n", { mode: 384 });
+        console.log(`[startup] Saved secrets to ${envPath}`);
+      }
+    } catch (e) {
+      console.warn(`[startup] Could not save secrets to ${envPath}: ${e.message}`);
+    }
+  }
+}
+async function runServe(_args) {
+  loadEnvFile();
+  const DATABASE_URL = process.env.DATABASE_URL;
+  const PORT = parseInt(process.env.PORT || "8080", 10);
+  await ensureSecrets();
+  const JWT_SECRET = process.env.JWT_SECRET;
+  const VAULT_KEY = process.env.AGENTICMAIL_VAULT_KEY;
+  if (!DATABASE_URL) {
+    console.error("ERROR: DATABASE_URL is required.");
+    console.error("");
+    console.error("Set it via environment variable or .env file:");
+    console.error("  DATABASE_URL=postgresql://user:pass@host:5432/db npx @agenticmail/enterprise start");
+    console.error("");
+    console.error("Or create a .env file (in cwd or ~/.agenticmail/.env):");
+    console.error("  DATABASE_URL=postgresql://user:pass@host:5432/db");
+    console.error("  JWT_SECRET=your-secret-here");
+    console.error("  PORT=3200");
+    process.exit(1);
+  }
+  const { createAdapter } = await import("./factory-672W7A5B.js");
+  const { createServer } = await import("./server-VXVRSEFL.js");
+  const db = await createAdapter({
+    type: DATABASE_URL.startsWith("postgres") ? "postgres" : "sqlite",
+    connectionString: DATABASE_URL
+  });
+  await db.migrate();
+  const server = createServer({
+    port: PORT,
+    db,
+    jwtSecret: JWT_SECRET,
+    corsOrigins: ["*"]
+  });
+  await server.start();
+  console.log(`AgenticMail Enterprise server running on :${PORT}`);
+}
+export {
+  runServe
+};

package/dist/cli.js

@@ -53,14 +53,14 @@ Skill Development:
     break;
   case "serve":
   case "start":
-    import("./cli-serve-WHWBI3NH.js").then((m) => m.runServe(args.slice(1))).catch(fatal);
+    import("./cli-serve-OHDYAC3L.js").then((m) => m.runServe(args.slice(1))).catch(fatal);
     break;
   case "agent":
-    import("./cli-agent-M3YGU3IG.js").then((m) => m.runAgent(args.slice(1))).catch(fatal);
+    import("./cli-agent-HDEPHBZX.js").then((m) => m.runAgent(args.slice(1))).catch(fatal);
     break;
   case "setup":
   default:
-    import("./setup-RHYG7BZO.js").then((m) => m.runSetupWizard()).catch(fatal);
+    import("./setup-OBCJB3R6.js").then((m) => m.runSetupWizard()).catch(fatal);
     break;
 }
 function fatal(err) {

package/dist/dashboard/docs/browser-providers.html

@@ -0,0 +1,411 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Browser Provider Setup Guide — AgenticMail Enterprise</title>
+<style>
+  :root { --bg: #0f172a; --card: #1e293b; --border: #334155; --text: #e2e8f0; --muted: #94a3b8; --accent: #3b82f6; --success: #15803d; --warning: #f59e0b; --danger: #ef4444; --radius: 10px; }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: var(--bg); color: var(--text); line-height: 1.7; padding: 32px; max-width: 900px; margin: 0 auto; }
+  h1 { font-size: 28px; margin-bottom: 8px; }
+  h2 { font-size: 20px; margin: 32px 0 12px; padding-bottom: 8px; border-bottom: 1px solid var(--border); }
+  h3 { font-size: 16px; margin: 20px 0 8px; color: var(--accent); }
+  p { margin-bottom: 12px; }
+  code { background: #0f172a; border: 1px solid var(--border); padding: 2px 6px; border-radius: 4px; font-size: 13px; color: var(--accent); }
+  pre { background: #0f172a; border: 1px solid var(--border); padding: 16px; border-radius: var(--radius); overflow-x: auto; margin: 12px 0; font-size: 13px; line-height: 1.5; }
+  pre code { background: none; border: none; padding: 0; }
+  .card { background: var(--card); border: 1px solid var(--border); border-radius: var(--radius); padding: 20px; margin: 16px 0; }
+  .tip { background: rgba(59,130,246,0.1); border: 1px solid rgba(59,130,246,0.3); padding: 12px 16px; border-radius: var(--radius); margin: 12px 0; font-size: 13px; }
+  .warning { background: rgba(245,158,11,0.1); border: 1px solid rgba(245,158,11,0.3); padding: 12px 16px; border-radius: var(--radius); margin: 12px 0; font-size: 13px; }
+  .danger { background: rgba(239,68,68,0.1); border: 1px solid rgba(239,68,68,0.3); padding: 12px 16px; border-radius: var(--radius); margin: 12px 0; font-size: 13px; }
+  table { width: 100%; border-collapse: collapse; margin: 12px 0; font-size: 13px; }
+  th, td { text-align: left; padding: 8px 12px; border: 1px solid var(--border); }
+  th { background: var(--card); font-weight: 600; }
+  ul, ol { padding-left: 24px; margin-bottom: 12px; }
+  li { margin-bottom: 6px; }
+  .badge { display: inline-block; padding: 2px 8px; border-radius: 4px; font-size: 11px; font-weight: 600; }
+  .badge-easy { background: rgba(21,128,61,0.2); color: #22c55e; }
+  .badge-medium { background: rgba(245,158,11,0.2); color: #f59e0b; }
+  .badge-advanced { background: rgba(239,68,68,0.2); color: #ef4444; }
+  a { color: var(--accent); }
+  .back { display: inline-block; margin-bottom: 20px; font-size: 13px; color: var(--muted); text-decoration: none; }
+  .back:hover { color: var(--text); }
+</style>
+</head>
+<body>
+
+<a class="back" href="/dashboard/agents">← Back to Dashboard</a>
+
+<h1>Browser Provider Setup Guide</h1>
+<p style="color: var(--muted); margin-bottom: 24px;">Complete reference for connecting your AI agents to browsers — local, remote, or cloud-hosted.</p>
+
+<div class="card">
+  <h3 style="margin-top: 0;">Quick Comparison</h3>
+  <table>
+    <tr>
+      <th>Provider</th>
+      <th>Best For</th>
+      <th>Video Calls</th>
+      <th>Difficulty</th>
+      <th>Cost</th>
+    </tr>
+    <tr>
+      <td><strong>Local Chromium</strong></td>
+      <td>Web scraping, form filling, screenshots</td>
+      <td>No (headless) / Yes (headed, if display available)</td>
+      <td><span class="badge badge-easy">Easy</span></td>
+      <td>Free</td>
+    </tr>
+    <tr>
+      <td><strong>Remote CDP</strong></td>
+      <td>Video calls, persistent sessions, full browser control</td>
+      <td>Yes</td>
+      <td><span class="badge badge-medium">Medium</span></td>
+      <td>VM cost only</td>
+    </tr>
+    <tr>
+      <td><strong>Browserless.io</strong></td>
+      <td>Scalable scraping, stealth browsing, managed infra</td>
+      <td>No</td>
+      <td><span class="badge badge-easy">Easy</span></td>
+      <td>From $0/mo (free tier)</td>
+    </tr>
+    <tr>
+      <td><strong>Browserbase</strong></td>
+      <td>AI agent automation, session replay, anti-detection</td>
+      <td>No</td>
+      <td><span class="badge badge-easy">Easy</span></td>
+      <td>From $0/mo (free tier)</td>
+    </tr>
+    <tr>
+      <td><strong>Steel.dev</strong></td>
+      <td>Self-hostable, AI-native, session management</td>
+      <td>No</td>
+      <td><span class="badge badge-medium">Medium</span></td>
+      <td>Free (self-hosted) / Paid (cloud)</td>
+    </tr>
+    <tr>
+      <td><strong>ScrapingBee</strong></td>
+      <td>Web scraping with proxy rotation, CAPTCHA solving</td>
+      <td>No</td>
+      <td><span class="badge badge-easy">Easy</span></td>
+      <td>From $0/mo (free tier)</td>
+    </tr>
+  </table>
+</div>
+
+<!-- ═══════════════════════════════════════════ -->
+<h2 id="local">1. Local Chromium (Default)</h2>
+
+<p>The simplest option. A headless Chromium browser runs on the same machine as AgenticMail. No external services needed.</p>
+
+<h3>When to use</h3>
+<ul>
+  <li>Web scraping and data extraction</li>
+  <li>Taking screenshots of web pages</li>
+  <li>Filling out forms and automating websites</li>
+  <li>Any task that doesn't need a camera, microphone, or visible display</li>
+</ul>
+
+<h3>Setup</h3>
+<p>No setup needed — it's the default. Chromium is bundled with Playwright and installed automatically when the agent first starts.</p>
+
+<div class="tip"><strong>Headed mode:</strong> If your server has a display (desktop, not headless server), you can switch to "Headed" mode in the dashboard to see the browser window. This is useful for debugging.</div>
+
+<h3>Troubleshooting</h3>
+<table>
+  <tr><th>Issue</th><th>Solution</th></tr>
+  <tr><td>Chromium not found</td><td>The agent installs it automatically on first run. If it fails, check disk space (needs ~300MB).</td></tr>
+  <tr><td>Missing dependencies on Linux</td><td>Install: <code>apt-get install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libdrm2 libxcomposite1 libxdamage1 libxrandr2 libgbm1 libpango-1.0-0 libasound2</code></td></tr>
+  <tr><td>"Display not available" in headed mode</td><td>Headed mode requires X11 or Wayland. Use headless mode on servers without a display, or install Xvfb: <code>apt-get install xvfb && Xvfb :99 &</code></td></tr>
+  <tr><td>Timeout on navigation</td><td>Increase timeout in browser settings. Some sites take longer to load with JavaScript rendering.</td></tr>
+</table>
+
+<!-- ═══════════════════════════════════════════ -->
+<h2 id="remote-cdp">2. Remote Browser (CDP)</h2>
+
+<p>Connect to a Chrome browser running on another machine. The agent controls it remotely via the Chrome DevTools Protocol. This is the <strong>only option that supports video calls</strong> (Google Meet, Teams, Zoom) because it can access a real camera, microphone, and display on the remote machine.</p>
+
+<h3>When to use</h3>
+<ul>
+  <li>Video calls and meetings (Google Meet, Microsoft Teams, Zoom)</li>
+  <li>Tasks requiring a persistent browser session (stay logged in across agent restarts)</li>
+  <li>When you need a real display, camera, or microphone</li>
+  <li>Running the agent on a headless server but needing browser GUI features</li>
+</ul>
+
+<h3>What you need</h3>
+<ol>
+  <li>A machine with Google Chrome installed (any OS — Mac, Windows, Linux)</li>
+  <li>Chrome configured to accept remote connections</li>
+  <li>Network access between your AgenticMail server and the Chrome machine</li>
+</ol>
+
+<h3>Setup: macOS</h3>
+<div class="card">
+  <p><strong>Step 1:</strong> Open Terminal on the Mac where you want Chrome to run.</p>
+  <p><strong>Step 2:</strong> Launch Chrome with remote debugging enabled:</p>
+  <pre><code>/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</code></pre>
+  <p><strong>Step 3:</strong> In the AgenticMail dashboard, enter the address: <code>192.168.x.x:9222</code> (replace with the Mac's IP address)</p>
+  <p><strong>Step 4:</strong> Click "Test Connection" — you should see the Chrome version.</p>
+</div>
+
+<div class="tip"><strong>To run Chrome at startup on macOS:</strong> Create a Launch Agent plist at <code>~/Library/LaunchAgents/com.chrome.remote.plist</code> — or simply add the command to Login Items in System Settings.</div>
+
+<h3>Setup: Linux (Ubuntu/Debian)</h3>
+<div class="card">
+  <p><strong>Step 1:</strong> Install Chrome if not already installed:</p>
+  <pre><code>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</code></pre>
+
+  <p><strong>Step 2:</strong> For headless servers (no display), install a virtual display:</p>
+  <pre><code>sudo apt-get install -y xvfb pulseaudio
+# Start virtual display and audio
+Xvfb :99 -screen 0 1920x1080x24 &
+export DISPLAY=:99
+pulseaudio --start</code></pre>
+
+  <p><strong>Step 3:</strong> Launch Chrome:</p>
+  <pre><code>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 &</code></pre>
+
+  <p><strong>Step 4:</strong> Enter the server IP and port in the dashboard: <code>your-server-ip:9222</code></p>
+</div>
+
+<div class="tip"><strong>For video calls on Linux:</strong> Install virtual camera/audio: <code>sudo apt install v4l2loopback-dkms</code> for virtual camera, and PulseAudio virtual sinks for audio routing.</div>
+
+<h3>Setup: Windows</h3>
+<div class="card">
+  <p><strong>Step 1:</strong> Open PowerShell and run:</p>
+  <pre><code>& "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</code></pre>
+
+  <p><strong>Step 2:</strong> Allow Chrome through Windows Firewall when prompted (or add a rule for port 9222).</p>
+  <p><strong>Step 3:</strong> Enter the Windows machine's IP and port in the dashboard.</p>
+</div>
+
+<h3>Setup: Cloud VMs</h3>
+<div class="card">
+  <table>
+    <tr><th>Provider</th><th>Best Option</th><th>Notes</th></tr>
+    <tr><td>AWS</td><td>EC2 with Ubuntu Desktop AMI, or WorkSpaces</td><td>Use t3.medium+. Open port 9222 in security group (restrict to your AgenticMail IP).</td></tr>
+    <tr><td>Azure</td><td>Azure Virtual Desktop or VM with Desktop</td><td>Use B2s or larger. Open port 9222 in NSG.</td></tr>
+    <tr><td>Google Cloud</td><td>Compute Engine with Desktop</td><td>Use e2-medium+. Open port 9222 in firewall rules.</td></tr>
+    <tr><td>Hetzner</td><td>Cloud Server with Ubuntu Desktop</td><td>Very cost-effective (~€4/mo). Open port 9222 in firewall.</td></tr>
+    <tr><td>DigitalOcean</td><td>Droplet with Desktop</td><td>Use 2GB+ RAM. Open port 9222 in firewall.</td></tr>
+  </table>
+  <p style="margin-top: 8px;">For all cloud VMs: follow the Linux setup above, then configure the firewall to only allow connections from your AgenticMail server's IP address.</p>
+</div>
+
+<h3>Securing the Connection</h3>
+<div class="warning"><strong>Security note:</strong> Chrome's remote debugging port has NO authentication by default. Anyone who can reach port 9222 has full browser control. Always restrict access.</div>
+
+<p><strong>Option A: Firewall rules (simplest)</strong></p>
+<p>Only allow your AgenticMail server's IP to connect to port 9222:</p>
+<pre><code># 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</code></pre>
+
+<p><strong>Option B: SSH Tunnel (most secure)</strong></p>
+<p>Don't expose port 9222 at all. Instead, use the SSH Tunnel field in the dashboard:</p>
+<ol>
+  <li>Ensure SSH access to the remote machine is configured (SSH key recommended)</li>
+  <li>In the dashboard, set the Remote Browser Address to <code>localhost:9222</code></li>
+  <li>In the SSH Tunnel field, enter: <code>user@remote-host</code></li>
+  <li>We automatically create the tunnel (<code>ssh -L 9222:localhost:9222 user@remote-host</code>) before connecting</li>
+</ol>
+
+<div class="tip"><strong>SSH key setup:</strong> On your AgenticMail server, run <code>ssh-keygen</code> if you haven't already, then copy your public key to the remote machine: <code>ssh-copy-id user@remote-host</code></div>
+
+<h3>Troubleshooting</h3>
+<table>
+  <tr><th>Issue</th><th>Solution</th></tr>
+  <tr><td>"Cannot connect to CDP"</td><td>Check: (1) Chrome is running with --remote-debugging-port, (2) firewall allows the connection, (3) IP/port are correct</td></tr>
+  <tr><td>"Connection refused"</td><td>Chrome may not be listening on all interfaces. Ensure <code>--remote-debugging-address=0.0.0.0</code> is set (or use SSH tunnel with localhost)</td></tr>
+  <tr><td>"WebSocket handshake failed"</td><td>The WebSocket URL changes each time Chrome starts. Use the host:port format (e.g., <code>192.168.1.100:9222</code>) and we auto-discover the current URL</td></tr>
+  <tr><td>"No cameras found" in video call</td><td>The remote machine needs a camera (physical or virtual). On Linux: <code>sudo modprobe v4l2loopback</code></td></tr>
+  <tr><td>"No audio" in video call</td><td>Install PulseAudio on Linux. On macOS/Windows, audio should work automatically.</td></tr>
+  <tr><td>SSH tunnel fails</td><td>Check: (1) SSH key is configured (no password prompt), (2) remote host is reachable, (3) user has login access</td></tr>
+</table>
+
+<!-- ═══════════════════════════════════════════ -->
+<h2 id="browserless">3. Browserless.io</h2>
+
+<p>A managed cloud browser service. Browserless runs Chrome instances in the cloud and you connect via API token. Great for scalable scraping and automation without managing infrastructure.</p>
+
+<h3>When to use</h3>
+<ul>
+  <li>High-volume web scraping that needs to scale</li>
+  <li>Anti-detection / stealth browsing (bypassing bot detection)</li>
+  <li>When you don't want to manage browser infrastructure</li>
+  <li>Concurrent browsing sessions across multiple agents</li>
+</ul>
+
+<h3>Setup</h3>
+<ol>
+  <li>Sign up at <a href="https://www.browserless.io" target="_blank">browserless.io</a></li>
+  <li>Go to your <a href="https://www.browserless.io/dashboard" target="_blank">dashboard</a> and copy your API token</li>
+  <li>Paste the token in the AgenticMail dashboard under Browser → Browserless → API Token</li>
+  <li>Click "Test Connection" to verify</li>
+</ol>
+
+<div class="tip"><strong>Free tier:</strong> Browserless offers a free tier with limited sessions per month — plenty for testing.</div>
+
+<h3>Self-hosted Browserless</h3>
+<p>You can run Browserless on your own server using Docker:</p>
+<pre><code>docker run -d --name browserless \
+  -p 3000:3000 \
+  -e TOKEN=your-secret-token \
+  ghcr.io/browserless/chromium</code></pre>
+<p>Then set the endpoint to <code>ws://your-server:3000</code> in the dashboard.</p>
+
+<div class="warning"><strong>Note:</strong> Browserless does not support video calls (no camera/mic access). Use Remote CDP for meetings.</div>
+
+<!-- ═══════════════════════════════════════════ -->
+<h2 id="browserbase">4. Browserbase</h2>
+
+<p>AI-native cloud browser built specifically for agent automation. Offers session replay, anti-detection, and managed infrastructure with a developer-friendly API.</p>
+
+<h3>When to use</h3>
+<ul>
+  <li>AI agent workflows that need persistent browser sessions</li>
+  <li>Session recording and replay for debugging agent actions</li>
+  <li>Sites with aggressive anti-bot detection</li>
+  <li>When you want the most agent-friendly browser service</li>
+</ul>
+
+<h3>Setup</h3>
+<ol>
+  <li>Sign up at <a href="https://www.browserbase.com" target="_blank">browserbase.com</a></li>
+  <li>Go to <a href="https://www.browserbase.com/settings" target="_blank">Settings</a> and copy your API key</li>
+  <li>Copy your Project ID from the dashboard</li>
+  <li>Enter both in the AgenticMail dashboard under Browser → Browserbase</li>
+  <li>Click "Test Connection" to verify</li>
+</ol>
+
+<div class="tip"><strong>Session replay:</strong> Browserbase records every session by default. You can watch exactly what your agent did at <a href="https://www.browserbase.com" target="_blank">browserbase.com</a>.</div>
+
+<!-- ═══════════════════════════════════════════ -->
+<h2 id="steel">5. Steel.dev</h2>
+
+<p>Open-source browser API designed for AI agents. Can be self-hosted for free or used as a managed cloud service. Built-in session management and stealth capabilities.</p>
+
+<h3>When to use</h3>
+<ul>
+  <li>Self-hosted browser infrastructure (full control, no vendor lock-in)</li>
+  <li>AI agent workflows that need session persistence</li>
+  <li>When you want open-source and the ability to customize</li>
+</ul>
+
+<h3>Setup: Cloud (managed)</h3>
+<ol>
+  <li>Sign up at <a href="https://app.steel.dev" target="_blank">app.steel.dev</a></li>
+  <li>Copy your API key from the dashboard</li>
+  <li>Enter it in AgenticMail under Browser → Steel</li>
+  <li>Click "Test Connection" to verify</li>
+</ol>
+
+<h3>Setup: Self-hosted (Docker)</h3>
+<pre><code>docker run -d --name steel \
+  -p 3000:3000 \
+  ghcr.io/nichochar/steel-browser:latest</code></pre>
+<p>Set the endpoint to <code>http://your-server:3000</code> and leave the API key empty for local use.</p>
+
+<!-- ═══════════════════════════════════════════ -->
+<h2 id="scrapingbee">6. ScrapingBee</h2>
+
+<p>Web scraping API with built-in browser rendering, proxy rotation, and CAPTCHA solving. Works differently from other providers — it routes your browser traffic through ScrapingBee's proxy network for anti-detection.</p>
+
+<h3>When to use</h3>
+<ul>
+  <li>Scraping websites that block bots aggressively</li>
+  <li>When you need residential proxy IPs</li>
+  <li>CAPTCHA-heavy websites</li>
+  <li>Geo-targeted browsing (browse as if from a specific country)</li>
+</ul>
+
+<h3>Setup</h3>
+<ol>
+  <li>Sign up at <a href="https://www.scrapingbee.com" target="_blank">scrapingbee.com</a></li>
+  <li>Copy your API key from the <a href="https://www.scrapingbee.com/dashboard" target="_blank">dashboard</a></li>
+  <li>Enter it in AgenticMail under Browser → ScrapingBee</li>
+  <li>Click "Test Connection" — you'll see your remaining API credits</li>
+</ol>
+
+<div class="tip"><strong>Free tier:</strong> ScrapingBee offers 1,000 free API credits — enough for testing.</div>
+
+<div class="warning"><strong>Note:</strong> ScrapingBee works as a proxy, not a direct browser connection. Some advanced Playwright features (like file uploads or complex interactions) may not work through the proxy. For those cases, use Browserless or Browserbase.</div>
+
+<!-- ═══════════════════════════════════════════ -->
+<h2 id="security">Security Best Practices</h2>
+
+<div class="card">
+  <h3 style="margin-top: 0;">For all providers</h3>
+  <ul>
+    <li><strong>Use domain allowlists:</strong> Restrict which websites agents can visit in Security & Limits</li>
+    <li><strong>Set page limits:</strong> Limit concurrent pages to prevent runaway browsing</li>
+    <li><strong>Enable SSRF protection:</strong> Blocks navigation to internal/private IPs (enabled by default)</li>
+    <li><strong>Rotate API keys:</strong> Change cloud provider API keys periodically</li>
+  </ul>
+
+  <h3>For Remote CDP specifically</h3>
+  <ul>
+    <li><strong>Never expose port 9222 to the public internet</strong> without a firewall or SSH tunnel</li>
+    <li><strong>Use SSH tunnels</strong> for the most secure connection (all traffic encrypted)</li>
+    <li><strong>Use a dedicated Chrome profile</strong> (--user-data-dir) — don't use your personal browser</li>
+    <li><strong>Run Chrome as a non-root user</strong> on Linux</li>
+    <li><strong>Keep Chrome updated</strong> — remote debugging inherits all Chrome vulnerabilities</li>
+  </ul>
+
+  <h3>For cloud providers</h3>
+  <ul>
+    <li><strong>API keys are encrypted:</strong> All credentials are stored encrypted in the AgenticMail vault</li>
+    <li><strong>Use provider IP allowlists:</strong> Most cloud browser providers let you restrict API access by IP</li>
+    <li><strong>Monitor usage:</strong> Set up alerts on your cloud provider dashboard for unusual usage</li>
+  </ul>
+</div>
+
+<!-- ═══════════════════════════════════════════ -->
+<h2 id="faq">Frequently Asked Questions</h2>
+
+<div class="card">
+  <h3 style="margin-top: 0;">Can I use video calls with cloud browser providers?</h3>
+  <p>No. Cloud providers (Browserless, Browserbase, Steel, ScrapingBee) don't have camera or microphone access. For video calls, use <strong>Remote CDP</strong> connected to a machine with a camera and microphone (physical or virtual).</p>
+
+  <h3>Which provider is fastest?</h3>
+  <p>Local Chromium is fastest (no network latency). For cloud providers, Browserless and Steel are typically fastest for page loads. Browserbase adds session management overhead but is the most reliable for complex automations.</p>
+
+  <h3>Can I switch providers without losing anything?</h3>
+  <p>Yes. Browser sessions are independent of each other. Switching providers in the dashboard takes effect on the next browser action. Note: cookies and login sessions from one provider don't transfer to another.</p>
+
+  <h3>What if my cloud provider goes down?</h3>
+  <p>The agent will fall back to local Chromium automatically if the cloud provider connection fails (configurable in Security & Limits).</p>
+
+  <h3>How do I use multiple browsers for different tasks?</h3>
+  <p>Each agent has its own browser configuration. Create different agents for different purposes — one with Remote CDP for meetings, another with Browserless for scraping.</p>
+</div>
+
+<p style="margin-top: 32px; color: var(--muted); font-size: 12px; text-align: center;">
+  AgenticMail Enterprise — Browser Provider Setup Guide<br>
+  Need help? Contact support or check the <a href="https://docs.agenticmail.io" style="color: var(--muted);">full documentation</a>.
+</p>
+
+</body>
+</html>

package/dist/dashboard/pages/agent-detail/meeting-browser.js

@@ -442,47 +442,60 @@ export function BrowserConfigCard(props) {
           sectionTitle(I.globe(), 'Remote Browser Connection'),
           h('div', { style: { padding: '10px 14px', background: 'var(--info-soft)', borderRadius: 'var(--radius)', marginBottom: 12, fontSize: 12, lineHeight: 1.5 } },
             h('strong', null, 'How it works: '),
-            'The agent connects to a Chrome/Chromium browser running on another machine via the Chrome DevTools Protocol (CDP). ',
-            'This is required for video calls (Google Meet, Teams, Zoom) where the browser needs a camera, microphone, and display. ',
+            'The agent connects to a Chrome browser running on another machine (a VM, cloud desktop, or remote server). ',
+            'This is ideal for video calls (Google Meet, Teams, Zoom) where the browser needs a camera, microphone, and display.',
             h('br', null), h('br', null),
-            h('strong', null, 'Setup options:'), h('br', null),
-            '\u2022 Run Chrome with --remote-debugging-port=9222 on a VM/desktop', h('br', null),
-            '\u2022 Use a cloud desktop (AWS WorkSpaces, Azure Virtual Desktop, Hetzner)', h('br', null),
-            '\u2022 Set up a dedicated browser VM with virtual camera/audio for meetings', h('br', null),
-            '\u2022 Use SSH tunneling to expose Chrome DevTools securely'
+            h('strong', null, 'What you need: '), 'A machine with Chrome installed and remote debugging enabled. ',
+            'Just enter the connection URL below — we handle everything else automatically, including SSH tunneling if needed.',
+            h('br', null), h('br', null),
+            h('strong', null, 'Connection format: '), 'Enter either:',
+            h('br', null),
+            '\u2022 A hostname and port (e.g., ', h('code', { style: { fontSize: 11, color: 'var(--accent)' } }, '192.168.1.100:9222'), ') — we auto-discover the WebSocket URL',
+            h('br', null),
+            '\u2022 A full WebSocket URL (e.g., ', h('code', { style: { fontSize: 11, color: 'var(--accent)' } }, 'ws://192.168.1.100:9222/devtools/browser/...'), ')',
+            h('br', null), h('br', null),
+            h('strong', null, 'Don\'t have a remote browser yet? '), h('a', { href: '/docs/browser-providers', target: '_blank', style: { color: 'var(--accent)' } }, 'Read our setup guide'),
+            ' for step-by-step instructions on setting up Chrome for remote access on any machine (Mac, Linux, Windows, cloud VMs).'
           ),
           h('div', { style: { display: 'grid', gap: 12 } },
             h('div', { className: 'form-group' },
-              h('label', { style: labelStyle }, 'CDP WebSocket URL *'),
-              h('input', { className: 'input', placeholder: 'ws://192.168.1.100:9222/devtools/browser/...',
+              h('label', { style: labelStyle }, 'Remote Browser Address *'),
+              h('input', { className: 'input', placeholder: '192.168.1.100:9222  or  ws://host:9222/devtools/browser/...',
                 value: cfg.cdpUrl || '',
                 onChange: function(e) { update('cdpUrl', e.target.value); }
               }),
-              h('div', { style: helpStyle }, 'WebSocket URL from chrome://inspect or --remote-debugging-port output. Format: ws://host:port/devtools/browser/<id>')
+              h('div', { style: helpStyle }, 'IP address and port of the remote Chrome browser. We auto-detect the connection details.')
             ),
             h('div', { style: { display: 'grid', gap: 12, gridTemplateColumns: '1fr 1fr' } },
               h('div', { className: 'form-group' },
                 h('label', { style: labelStyle }, 'Auth Token'),
-                h('input', { className: 'input', type: 'password', placeholder: 'Optional — for authenticated CDP endpoints',
+                h('input', { className: 'input', type: 'password', placeholder: 'Optional — for authenticated endpoints',
                   value: cfg.cdpAuthToken || '',
                   onChange: function(e) { update('cdpAuthToken', e.target.value || undefined); }
-                })
+                }),
+                h('div', { style: helpStyle }, 'Only needed if the remote browser requires authentication.')
               ),
               h('div', { className: 'form-group' },
-                h('label', { style: labelStyle }, 'Connection Timeout (ms)'),
-                h('input', { className: 'input', type: 'number', min: 5000, max: 60000,
-                  value: cfg.cdpTimeout || 30000,
-                  onChange: function(e) { update('cdpTimeout', parseInt(e.target.value) || 30000); }
-                })
+                h('label', { style: labelStyle }, 'Connection Timeout'),
+                h('select', { className: 'input', value: String(cfg.cdpTimeout || 30000),
+                  onChange: function(e) { update('cdpTimeout', parseInt(e.target.value)); }
+                },
+                  h('option', { value: '10000' }, '10 seconds'),
+                  h('option', { value: '30000' }, '30 seconds (recommended)'),
+                  h('option', { value: '60000' }, '60 seconds (slow networks)')
+                )
               )
             ),
             h('div', { className: 'form-group' },
-              h('label', { style: labelStyle }, 'SSH Tunnel (auto-connect)'),
-              h('input', { className: 'input', placeholder: 'ssh -L 9222:localhost:9222 user@remote-host (optional)',
-                value: cfg.sshTunnel || '',
-                onChange: function(e) { update('sshTunnel', e.target.value || undefined); }
-              }),
-              h('div', { style: helpStyle }, 'SSH command to establish tunnel before connecting. Agent will run this automatically.')
+              h('label', { style: labelStyle }, 'SSH Tunnel'),
+              h('div', { style: { display: 'grid', gap: 8, gridTemplateColumns: '1fr auto' } },
+                h('input', { className: 'input', placeholder: 'user@remote-host (we handle the rest automatically)',
+                  value: cfg.sshTunnel || '',
+                  onChange: function(e) { update('sshTunnel', e.target.value || undefined); }
+                }),
+                cfg.sshTunnel && h('span', { style: { display: 'flex', alignItems: 'center', fontSize: 11, color: 'var(--success)', whiteSpace: 'nowrap' } }, I.check(), ' Auto-connect enabled')
+              ),
+              h('div', { style: helpStyle }, 'Optional. If the remote browser is behind a firewall, enter the SSH user@host and we\'ll automatically create a secure tunnel before connecting. The SSH key must be configured on this server.')
             )
           )
         ),