Remote Agent Browser

Remote Agent Browser runs agent-browser inside an isolated Vercel Sandbox. Use it when a TypeScript application needs to provision a browser on demand without managing a local Chrome process.

Remote Agent Browser is a library rather than an agent-browser -p provider. Import it in your application and use the returned client to run agent-browser commands.

Setup

bash

pnpm add remote-agent-browser

Authentication is automatic on Vercel through VERCEL_OIDC_TOKEN. For local development, link a Vercel project and pull its environment:

bash

vercel link
vercel env pull .env.local

Create a browser

import { AgentBrowser } from "remote-agent-browser";

const browser = await AgentBrowser.create();

try {
  await browser.exec("open", {
    args: ["https://example.com"],
  });

  const snapshot = await browser.exec("snapshot");
  console.log(snapshot.stdout);
} finally {
  await browser.close();
}

Commands issued through the same client share the same page, cookies, tabs, and element references. Always close disposable clients when the work is complete.

Stable browser sessions

Use a stable ID when browser identity needs to survive process boundaries:

const browser = AgentBrowser.session({
  id: `chat:${chatId}`,
});

const stopKeepalive = browser.keepalive();

try {
  await browser.exec("open", {
    args: ["https://example.com"],
  });
} finally {
  stopKeepalive();
}

The first command finds or creates the named Sandbox. A later process using the same ID can attach to it. If an expired Sandbox resumes, Chromium starts fresh and in-memory page state is reset.

Custom browser image

The default image is remote-agent-browser:latest. Pass a Vercel Container Registry repository, tag, digest, or fully qualified reference to use a custom image:

const browser = await AgentBrowser.create({
  image: "vcr.vercel.com/my-team/my-project/my-browser:v1",
});

You can also set REMOTE_AGENT_BROWSER_IMAGE to configure the image for every client.

Options

<table> <thead> <tr><th>Option</th><th>Description</th><th>Default</th></tr> </thead> <tbody> <tr><td><code>image</code></td><td>Vercel Container Registry image containing agent-browser and Chromium</td><td><code>remote-agent-browser:latest</code></td></tr> <tr><td><code>timeoutMs</code></td><td>Sandbox wall-clock timeout in milliseconds</td><td><code>600000</code></td></tr> <tr><td><code>vcpus</code></td><td>Number of Sandbox vCPUs</td><td><code>2</code></td></tr> <tr><td><code>env</code></td><td>Additional environment variables for commands in the Sandbox</td><td><code>{}</code></td></tr> <tr><td><code>args</code></td><td>Global agent-browser CLI arguments applied to each command</td><td><code>[]</code></td></tr> <tr><td><code>proxy</code></td><td>Proxy URL or proxy configuration for the browser client</td><td>(none)</td></tr> </tbody> </table>

See the Remote Agent Browser repository for file transfer, proxy configuration, typed JSON output, keepalive, and stable-session examples.