@cmmd-center/agent-browser

Browser-control primitives for agentic apps — the reusable browser runtime behind CMMD, Forge, and other agent surfaces. Public on npm; consumed as a pinned, versioned dependency.

Full usage docs: docs.cmmd.ai/agent-browser.

Install

npm install @cmmd-center/agent-browser
# or
pnpm add @cmmd-center/agent-browser
bun add @cmmd-center/agent-browser

No registry configuration or auth token is required — it resolves from the public npm registry. For production consumers (Forge, CMMD), pin an exact version rather than a range so upgrades land through a reviewed dependency PR:

{
  "dependencies": {
    "@cmmd-center/agent-browser": "0.5.2"
  }
}

Imports

Import the core package without pulling in browser automation dependencies:

import { AgentBrowser } from "@cmmd-center/agent-browser";
import { AgentBrowserHttpClient } from "@cmmd-center/agent-browser/client";

Import optional runtime adapters explicitly:

import { CdpBackend } from "@cmmd-center/agent-browser/cdp";
import { ExtensionBrowserBackend } from "@cmmd-center/agent-browser/extension";
import { PlaywrightBackend } from "@cmmd-center/agent-browser/playwright";
import { createBrowserHttpServer } from "@cmmd-center/agent-browser/server";
import { createHostBrowserBridge } from "@cmmd-center/agent-browser/host";

express, playwright, and zod are optional peer dependencies — install them only for the subpaths that need them (e.g. playwright for the /playwright and /cdp backends).

Production Boundary

/preview is a demo/debug page, not the production app surface. Production apps should own their browser surface and connect it through EmbeddedBrowserBackend, createEmbeddedBrowserHost, and optionally createHostBrowserBridge.

For Forge-style consumers, keep this package as the reusable browser runtime boundary. Map the app's browser/session contract onto createHostBrowserBridge and use CDP, embedded, extension, or Playwright backends according to the host surface the app owns.

The server adapter exposes shared-session endpoints for local tools and demos:

GET /session
GET /events
GET /screenshot
GET /preview

Security & secure defaults

This package drives a real browser. The defaults are tuned for local development, not for exposure to untrusted input or networks. When you embed it in a production app, treat the following as required hardening — none of it is on by default:

• Configure auth on the HTTP server. If you start createBrowserHttpServer without an apiKey, the server is open — anyone who can reach the port can drive the browser. Always set an apiKey, and prefer the x-api-key header. The query-string ?apiKey= form is dev-only: it leaks into browser history, Referer headers, and proxy/access logs.
• Supply a real permission policy. The default is AllowAllBrowserPermissionPolicy, which authorizes every action (navigate, click, type, clipboard read/write, clear cookies/cache). Production consumers must pass a BrowserPermissionPolicy that reflects what the app should allow.
• Never feed untrusted input to evaluate / tab.evaluate. These execute an arbitrary JavaScript string in the target page's context, giving full access to that origin's DOM, cookies, and tokens. Only pass code you control.
• Network-isolate the driven browser. /goto (and the navigation commands) will fetch any URL, including localhost, RFC1918 addresses, and cloud metadata endpoints (169.254.169.254). The browser is a confused deputy — run it where it can't reach internal services you don't intend to expose.
• Harden IPC adapters. The Electron and Tauri adapters (./adapters/electron, ./adapters/tauri) carry no auth of their own and rely entirely on the bridge's permission policy. Enable contextIsolation and never expose the agent-browser IPC channel to a renderer that loads untrusted content.

To report a vulnerability, see SECURITY.md.