Agent-Browser Npm: Run AI Browser Agents on Hosted Chromium

# Agent-Browser Npm: Run AI Browser Agents on Hosted Chromium

The agent-browser npm package is a browser automation CLI designed for AI agents. It gives your agent a way to navigate pages, click elements, fill forms, and extract data. But the npm package itself only provides the control layer. For production workloads, you need a browser runtime that can actually execute those commands reliably. That's where a hosted Chromium service like Remote Browser fits in.

This guide explains what agent-browser npm does, why local browser setups fail in production, and how to connect the CLI to hosted Chromium via CDP for persistent, scalable sessions.

What Is Agent-Browser Npm?

agent-browser is an open-source command-line tool (originally from Vercel Labs) that wraps browser automation into simple commands an AI model can invoke. Instead of writing raw Playwright or Puppeteer code, an agent calls commands like agent-browser navigate "https://example.com" or agent-browser extract.

The npm package handles the orchestration logic. It decides what to click, when to scroll, and how to parse the resulting DOM. What it does not handle is the underlying browser process—where that browser runs, how it stays alive, and how it scales.

That separation matters. The CLI is the brain; the browser is the hands. In local development, both run on your machine. In production, they need to be separated.

Why Local Browser Setup Breaks in Production

Running agent-browser npm against a locally installed Chromium works fine for demos. It fails in production for predictable reasons:

The core issue is that browser automation is stateful and resource-intensive. A single Chromium instance can consume 500MB+ of RAM. Running ten concurrent agents locally means managing ten browser processes, each with its own profile, cache, and network connections. That's not a coding problem—it's an infrastructure problem.

How to Connect Agent-Browser Npm to Hosted Chromium

Remote Browser provides hosted Chromium sessions that are accessible via the Chrome DevTools Protocol (CDP). The agent-browser CLI can connect to any CDP endpoint, which means you can point it at a Remote Browser session instead of a local browser instance.

Here's a TypeScript example showing how to establish a CDP connection that an agent-browser-style workflow would use:

import { chromium } from 'playwright';

// Connect to a hosted Chromium session via CDP
// Replace with your Remote Browser session URL
const browser = await chromium.connectOverCDP(
  'wss://remote-browser.dev/cdp/your-session-id'
);

// The browser is now a remote Chromium instance
// You can use the standard Playwright API
const page = await browser.newPage();
await page.goto('https://example.com');

// Extract data or perform actions
const title = await page.title();
console.log(`Page title: ${title}`);

// The session stays alive even if this script crashes
// because the browser runs remotely, not locally

await browser.close();

The key insight: connectOverCDP does not launch a browser. It attaches to an existing one. That existing browser runs on Remote Browser's infrastructure, not your machine.

Keeping Browser Sessions Alive Across Cloud Workers

One of the most common production questions is: *how do I keep a browser session alive when my cloud worker restarts?*

With a local browser, you can't. When the worker dies, the browser dies with it. Any cookies, localStorage, or logged-in state is lost.

With Remote Browser, the session is decoupled from your worker. The Chromium instance runs on our infrastructure. Your worker connects via CDP, does its work, and disconnects. The browser stays alive, retaining its full state.

This enables patterns that are impossible with local browsers:

• Long-running sessions: A session can persist for hours or days, surviving worker restarts and deploys.
• Stateful agents: An agent can log into a service, disconnect, and reconnect later without re-authenticating.
• Queue-based processing: Multiple workers can share a single browser session, picking up tasks sequentially.

The agent-browser npm CLI doesn't manage session lifecycle. You need a runtime that does. Remote Browser provides that runtime layer.

Scaling Playwright Browser Workloads Reliably

If you're using Playwright (which agent-browser npm builds on), you've probably hit the scaling wall. Playwright's default behavior is to launch a browser per script execution. That works for tests but is wasteful for agent workloads.

For production agent workloads, consider these criteria:

1. Session Reuse

Launching a browser takes 2-5 seconds. For a single task, that's acceptable. For an agent performing many steps, it's wasteful. Reusing a persistent session eliminates cold starts.

2. Profile Persistence

AI agents often need to maintain state—cookies, local storage, service workers. A fresh browser profile every time means re-authenticating on every task. Persistent profiles solve this.

3. Resource Isolation

A misbehaving script can crash a browser. In a shared local setup, that takes down all concurrent tasks. Hosted sessions provide isolation—each session runs independently.

4. Network Configuration

Production web scraping and automation often require specific IP configurations. Remote Browser supports configurable proxy settings so you can route traffic through appropriate egress points.

5. Observability

When an agent fails, you need to see what happened. A live viewer and session recording let you watch the browser in real time or replay the session later. This is critical for debugging AI agent behavior.

The Chromium Sandbox Issue

A common production pitfall relates to Chromium's sandbox. When running as root in a container (common in CI/CD and Docker deployments), Chromium refuses to start without --no-sandbox. This is a security trade-off that many teams make without understanding the implications.

Playwright's documentation explicitly notes that chromiumSandbox: false disables the sandbox. This is sometimes necessary in containerized environments, but it increases the risk of a compromised browser process accessing the host system.

Remote Browser handles this for you. Our hosted Chromium instances are configured correctly for their environment. You don't need to disable the sandbox or worry about container privileges. The browser runs in an isolated environment designed for that purpose.

CDP: The Universal Connection Protocol

The Chrome DevTools Protocol is the foundation for all modern browser automation. Both Playwright and Puppeteer use it internally. The agent-browser npm CLI ultimately issues CDP commands.

When you use connectOverCDP, you're speaking CDP directly to a running browser. This is different from launching a browser via Playwright's chromium.launch(), which starts a new process.

The distinction matters for production:

• `chromium.launch()`: Starts a browser on the local machine. Requires the Playwright browser binaries to be installed. Dies with the parent process.
• `connectOverCDP()`: Attaches to an existing browser. No local browser binaries needed. The browser can run anywhere—including on Remote Browser's infrastructure.

For AI agent workloads, connectOverCDP is almost always the right choice. It decouples the agent logic from the browser lifecycle.

Agent-Browser Npm and Selenium

While agent-browser npm is built on Playwright, many teams use Selenium for legacy automation. Remote Browser supports both via CDP. Selenium 4 includes CDP support, allowing it to connect to remote browser instances.

The pattern is the same: point your Selenium WebDriver at the CDP endpoint instead of a local chromedriver. This gives you the same benefits—persistent sessions, remote execution, and scalability—without rewriting your Selenium code.

Production Checklist for Agent-Browser Npm

Before deploying agent-browser npm to production, verify the following:

• [ ] Browser location: Is the browser running locally or on hosted infrastructure? Local browsers don't scale.
• [ ] Session persistence: What happens when your worker restarts? Does the session survive?
• [ ] Concurrency model: How many concurrent sessions do you need? Can your infrastructure handle it?
• [ ] Network configuration: Are you using appropriate proxies for the sites you're accessing?
• [ ] Observability: Can you see what the browser is doing in real time? Can you replay failed sessions?
• [ ] Security: Is the browser sandboxed? What happens if a page exploits a browser vulnerability?

If you can't answer these questions confidently, you're not ready for production browser automation.

When to Use Remote Browser with Agent-Browser Npm

Remote Browser is not the right choice for every workload. Here's a practical breakdown:

Use Remote Browser when:

• You need sessions to persist across worker restarts
• You're running more than a few concurrent browser instances
• You need to access sites that require consistent IP addresses
• You want live visibility into what your agent is doing
• You don't want to manage Chromium infrastructure yourself

Use local browsers when:

• You're doing quick local testing
• You have a single, short-lived task
• You don't need persistent state
• You're okay with the browser dying when your script ends

The line is about state and scale. If your agent needs to remember anything between steps, or if you're running more than a handful of sessions, hosted Chromium is the pragmatic choice.

Getting Started

To use agent-browser npm with Remote Browser:

1. Install the CLI: npm install -g agent-browser
2. Create a Remote Browser session via the API or dashboard
3. Connect the CLI to your session's CDP endpoint
4. Run your automation commands

For detailed API documentation, see the Remote Browser documentation. For current pricing and session limits, check the pricing page.

Related Reading

If you're building AI agents that browse the web, you may find these guides useful:

• Remote Browsers for AI Agents: The Missing Runtime Layer
• Remote Browser Online: Run Real Chromium Without Managing Chrome
• Remote Web Browser: The Practical Runtime for Browser Automation

For the underlying protocol, refer to the official Chrome DevTools Protocol documentation.

Conclusion

The agent-browser npm package solves the orchestration problem—giving AI agents a clean interface to browser automation. But production reliability comes from the runtime underneath. Hosted Chromium via CDP provides the persistence, scalability, and observability that local browsers cannot match.

Connect your agent-browser CLI to Remote Browser, and you get the best of both: a clean agent interface backed by infrastructure designed for production workloads. Your agents get reliable browser access, and you don't have to become a Chromium infrastructure expert.