remote-agent-browser 0.1.0

package/Dockerfile.sandbox

@@ -0,0 +1,19 @@
+FROM node:24-slim
+
+# Keep the browser and its native CLI in the image so Sandbox creation never
+# installs packages at runtime. Debian Chromium supports amd64 and arm64.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        chromium \
+        fonts-liberation \
+        fonts-noto-color-emoji \
+    && rm -rf /var/lib/apt/lists/* \
+    && npm install -g --allow-scripts=agent-browser agent-browser
+
+ENV AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium
+ENV AGENT_BROWSER_ARGS="--no-sandbox,--disable-dev-shm-usage,--disable-gpu"
+ENV AGENT_BROWSER_DEFAULT_TIMEOUT=25000
+
+# Vercel Sandbox uses bash to execute commands in custom images.
+WORKDIR /vercel/sandbox
+CMD ["/bin/bash"]

package/README.md

@@ -0,0 +1,88 @@
+# remote-agent-browser
+
+Run [agent-browser](https://github.com/vercel-labs/agent-browser) in an isolated
+[Vercel Sandbox](https://vercel.com/docs/vercel-sandbox). Chromium and the CLI
+come preinstalled, so there is no browser or Docker setup at runtime.
+
+## Install
+
+```bash
+pnpm add remote-agent-browser
+```
+
+## Use
+
+```ts
+import { createAgentBrowser } from 'remote-agent-browser'
+
+const browser = await createAgentBrowser()
+
+try {
+  const { results } = await browser.run([
+    ['open', 'https://example.com'],
+    ['snapshot', '-i', '--json'],
+  ])
+
+  console.log(results[1].stdout)
+} finally {
+  await browser.close()
+}
+```
+
+`createAgentBrowser()` starts a fresh Vercel Sandbox from the prebuilt browser
+image. Commands in one client share the same page, cookies, tabs, and element
+references. `close()` closes Chromium and stops the Sandbox.
+
+## Authentication
+
+Authentication is automatic when running 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
+node --env-file=.env.local example.mjs
+```
+
+## API
+
+### `createAgentBrowser()`
+
+Starts a fresh browser in a disposable Vercel Sandbox. Always call
+`browser.close()` when finished.
+
+### `browser.run(commands)`
+
+Run several agent-browser commands in the same session:
+
+```ts
+const result = await browser.run([
+  ['open', 'https://my-preview.vercel.app'],
+  ['wait', '--load', 'networkidle'],
+  ['snapshot', '-i', '--json'],
+  ['click', '@e3'],
+])
+```
+
+### `browser.exec(command, options?)`
+
+Run one command with arguments and flags:
+
+```ts
+await browser.exec('find', {
+  args: ['role', 'button', 'click'],
+  flags: { name: 'Submit' },
+})
+```
+
+### Convenience methods
+
+- `browser.snapshot(url)` opens a page and returns its interactive snapshot.
+- `browser.screenshot(url, { fullPage: true })` returns a PNG buffer.
+- `browser.close()` closes the session and stops the Sandbox.
+
+All methods use the same disposable browser session until `close()` is called.
+
+Container image and development details are in [docs.md](./docs.md).

package/dist/index.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Shared types for remote-agent-browser.
+ *
+ * The library has two layers:
+ *  - `AgentBrowser` (browser.ts): a thin, session-oriented client over the
+ *    `agent-browser` CLI running somewhere that can execute commands.
+ *  - `createAgentBrowser` (create.ts): provisions a Vercel Sandbox from a
+ *    browser-ready image and returns an `AgentBrowser` backed by it.
+ */
+/** One agent-browser CLI invocation result. */
+type BrowserCommandResult = {
+    /** The CLI args that ran, e.g. ["snapshot", "-i", "--json"] */
+    args: string[];
+    ok: boolean;
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    /** File bytes collected from the sandbox for file-producing commands. */
+    file?: {
+        path: string;
+        bytes: Buffer;
+        contentType: string;
+    };
+};
+/** A batch of commands run sequentially in one session. */
+type BrowserRunResult = {
+    session: string;
+    results: BrowserCommandResult[];
+    ok: boolean;
+};
+type RunOptions = {
+    /** Named session to reuse browser state across calls. Default: ephemeral. */
+    session?: string;
+    /** Stop the batch at the first failing command. Default: true. */
+    stopOnError?: boolean;
+    /** Per-command timeout in ms. */
+    timeoutMs?: number;
+};
+type ExecOptions = {
+    session?: string;
+    /** Positional CLI args, e.g. ["@e3"] for click. */
+    args?: string[];
+    /** Flags serialized to --kebab-case (true → bare flag, arrays → repeated). */
+    flags?: Record<string, unknown>;
+    timeoutMs?: number;
+};
+/**
+ * Minimal command executor the browser client needs. Implemented by the
+ * Vercel Sandbox adapter; anything with the same shape can back a
+ * AgentBrowser (tests, a local shell, another sandbox provider).
+ */
+interface CommandRunner {
+    /** Run a command, waiting for completion. */
+    run(cmd: string, args: string[], opts?: {
+        timeoutMs?: number;
+        env?: Record<string, string>;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number | null;
+    }>;
+    /** Read a file's bytes from the remote environment. */
+    readFile(path: string): Promise<Buffer>;
+    /** Tear the remote environment down. */
+    close(): Promise<void>;
+}
+/** Session-oriented remote browser client. */
+interface AgentBrowser {
+    /** The runner's session name this client uses by default. */
+    readonly session: string;
+    /** Run a batch of agent-browser arg-arrays sequentially. */
+    run(commands: string[][], opts?: RunOptions): Promise<BrowserRunResult>;
+    /** Run one agent-browser command by name. */
+    exec(command: string, opts?: ExecOptions): Promise<BrowserCommandResult>;
+    /** Open a URL and return the interactive accessibility snapshot (JSON). */
+    snapshot(url: string, opts?: RunOptions): Promise<BrowserRunResult>;
+    /** Open a URL and return a PNG screenshot. */
+    screenshot(url: string, opts?: RunOptions & {
+        fullPage?: boolean;
+    }): Promise<{
+        png: Buffer;
+        result: BrowserRunResult;
+    }>;
+    /** Close the browser session (and the sandbox when it owns it). */
+    close(): Promise<void>;
+}
+
+type CreateAgentBrowserOptions = {
+    /** Named CLI session; state (page, cookies, refs) persists across calls. */
+    session?: string;
+    /**
+     * Vercel Container Registry image containing agent-browser + Chromium.
+     * Default: REMOTE_AGENT_BROWSER_IMAGE or remote-agent-browser:latest.
+     */
+    image?: string;
+    /** Sandbox wall-clock timeout in ms. Default: 10 minutes. */
+    timeoutMs?: number;
+    /** Sandbox vCPUs. Default: 2. */
+    vcpus?: number;
+    /** Extra env vars for every command inside the sandbox. */
+    env?: Record<string, string>;
+};
+/**
+ * Create an agent-browser client running inside a fresh Vercel Sandbox.
+ *
+ * The sandbox boots from a browser-ready VCR image and the returned client
+ * runs every command as
+ * `agent-browser --session <name> …` so page state persists across calls.
+ * `close()` closes the browser and stops the sandbox.
+ *
+ * Auth comes from the environment (VERCEL_OIDC_TOKEN on Vercel, or a local
+ * `vercel login`), via @vercel/sandbox.
+ *
+ * ```ts
+ * import { createAgentBrowser } from 'remote-agent-browser'
+ *
+ * const browser = await createAgentBrowser()
+ * const { results } = await browser.run([
+ *   ['open', 'https://example.com'],
+ *   ['snapshot', '-i', '--json'],
+ * ])
+ * await browser.close()
+ * ```
+ */
+declare function createAgentBrowser(opts?: CreateAgentBrowserOptions): Promise<AgentBrowser>;
+
+/**
+ * Create a session-oriented browser client over any CommandRunner.
+ *
+ * Every command runs as `agent-browser --session <name> <args...>` so the
+ * remote daemon keeps page state (refs, cookies, tabs) across calls. Pass an
+ * explicit session name to share state across clients, or let it default to
+ * an ephemeral per-client session that is closed on `close()`.
+ */
+declare function createBrowserClient(runner: CommandRunner, opts?: {
+    session?: string;
+    ownsRunner?: boolean;
+}): AgentBrowser;
+
+export { createAgentBrowser, createBrowserClient };
+export type { AgentBrowser, BrowserCommandResult, BrowserRunResult, CommandRunner, CreateAgentBrowserOptions, ExecOptions, RunOptions };

package/dist/index.js

@@ -0,0 +1,332 @@
+import { randomUUID } from 'node:crypto';
+import { Sandbox } from '@vercel/sandbox';
+
+/** Commands whose output is a file we pull back as bytes. */ const FILE_OUTPUT = {
+    screenshot: {
+        subcommand: null,
+        ext: 'png',
+        contentType: 'image/png'
+    },
+    pdf: {
+        subcommand: null,
+        ext: 'pdf',
+        contentType: 'application/pdf'
+    },
+    trace: {
+        subcommand: 'stop',
+        ext: 'json',
+        contentType: 'application/json'
+    },
+    profiler: {
+        subcommand: 'stop',
+        ext: 'json',
+        contentType: 'application/json'
+    },
+    record: {
+        subcommand: 'stop',
+        ext: 'webm',
+        contentType: 'video/webm'
+    }
+};
+const SESSION_NAME = /^[\w.-]{1,64}$/;
+/** { json: true, fullPage: true, depth: 2 } → ["--json", "--full-page", "--depth", "2"] */ function flagsToArgs(flags) {
+    const args = [];
+    for (const [key, value] of Object.entries(flags)){
+        if (value === false || value === null || value === undefined) continue;
+        const flag = `--${key.replace(/[A-Z]/g, (c)=>`-${c.toLowerCase()}`)}`;
+        const values = Array.isArray(value) ? value : [
+            value
+        ];
+        for (const item of values){
+            if (item === false || item === null || item === undefined) continue;
+            args.push(flag);
+            if (item !== true) args.push(String(item));
+        }
+    }
+    return args;
+}
+function withSession(session, args) {
+    return [
+        '--session',
+        session,
+        ...args
+    ];
+}
+/**
+ * Create a session-oriented browser client over any CommandRunner.
+ *
+ * Every command runs as `agent-browser --session <name> <args...>` so the
+ * remote daemon keeps page state (refs, cookies, tabs) across calls. Pass an
+ * explicit session name to share state across clients, or let it default to
+ * an ephemeral per-client session that is closed on `close()`.
+ */ function createBrowserClient(runner, opts = {}) {
+    const session = opts.session ?? `session-${randomUUID()}`;
+    if (!SESSION_NAME.test(session)) {
+        throw new Error(`session must match [A-Za-z0-9_.-]{1,64}, got "${session}"`);
+    }
+    const ownsRunner = opts.ownsRunner ?? true;
+    let closed = false;
+    function assertOpen() {
+        if (closed) throw new Error('AgentBrowser is closed');
+    }
+    async function execCommand(args, timeoutMs, useSession = session) {
+        const [name, ...rest] = args;
+        // File-producing commands: inject a remote path and pull the bytes back,
+        // unless the caller already supplied an output path themselves.
+        const fileSpec = name ? FILE_OUTPUT[name] : undefined;
+        const positionals = rest.filter((a)=>!a.startsWith('-'));
+        const wantsFile = fileSpec && (fileSpec.subcommand === null ? positionals.length === 0 : positionals.length === 1 && positionals[0] === fileSpec.subcommand);
+        let finalArgs = withSession(useSession, args);
+        let remotePath;
+        if (wantsFile) {
+            remotePath = `/tmp/agent-browser-${randomUUID()}.${fileSpec.ext}`;
+            // screenshot <path> is the first positional for these commands
+            finalArgs = withSession(useSession, [
+                name,
+                ...rest,
+                remotePath
+            ]);
+        }
+        const run = await runner.run('agent-browser', finalArgs, {
+            timeoutMs
+        });
+        const result = {
+            args,
+            ok: run.exitCode === 0,
+            exitCode: run.exitCode,
+            stdout: run.stdout,
+            stderr: run.stderr
+        };
+        if (result.ok && remotePath && fileSpec) {
+            try {
+                result.file = {
+                    path: remotePath,
+                    bytes: await runner.readFile(remotePath),
+                    contentType: fileSpec.contentType
+                };
+            } catch (error) {
+                result.ok = false;
+                result.stderr += `\ncommand succeeded but ${remotePath} could not be read: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        }
+        return result;
+    }
+    return {
+        session,
+        async run (commands, runOpts = {}) {
+            assertOpen();
+            const useSession = runOpts.session ?? session;
+            if (!SESSION_NAME.test(useSession)) {
+                throw new Error(`session must match [A-Za-z0-9_.-]{1,64}, got "${useSession}"`);
+            }
+            const stopOnError = runOpts.stopOnError ?? true;
+            const results = [];
+            // Run each command inside the same CLI session so state carries over.
+            for (const command of commands){
+                if (command.length === 0) {
+                    results.push({
+                        args: [],
+                        ok: false,
+                        exitCode: null,
+                        stdout: '',
+                        stderr: 'empty command'
+                    });
+                    if (stopOnError) break;
+                    continue;
+                }
+                const result = await execCommand(command, runOpts.timeoutMs, useSession);
+                results.push(result);
+                if (!result.ok && stopOnError) break;
+            }
+            return {
+                session: useSession,
+                results,
+                ok: results.every((r)=>r.ok)
+            };
+        },
+        async exec (command, execOpts = {}) {
+            assertOpen();
+            const args = [
+                command,
+                ...execOpts.args ?? [],
+                ...execOpts.flags ? flagsToArgs(execOpts.flags) : []
+            ];
+            const useSession = execOpts.session ?? session;
+            if (!SESSION_NAME.test(useSession)) {
+                throw new Error(`session must match [A-Za-z0-9_.-]{1,64}, got "${useSession}"`);
+            }
+            return execCommand(args, execOpts.timeoutMs, useSession);
+        },
+        async snapshot (url, runOpts = {}) {
+            return this.run([
+                [
+                    'open',
+                    url
+                ],
+                [
+                    'snapshot',
+                    '-i',
+                    '--json'
+                ]
+            ], runOpts);
+        },
+        async screenshot (url, runOpts = {}) {
+            const shotArgs = [
+                'screenshot'
+            ];
+            if (runOpts.fullPage) shotArgs.push('--full');
+            const run = await this.run([
+                [
+                    'open',
+                    url
+                ],
+                shotArgs
+            ], runOpts);
+            const file = run.results.find((r)=>r.file)?.file;
+            if (!file) {
+                throw new Error(`screenshot failed: ${run.results.map((r)=>r.stderr || r.stdout).join('\n') || 'no output'}`);
+            }
+            return {
+                png: file.bytes,
+                result: run
+            };
+        },
+        async close () {
+            if (closed) return;
+            closed = true;
+            // Close the CLI session's browser first so the sandbox can stop cleanly.
+            await runner.run('agent-browser', withSession(session, [
+                'close'
+            ]), {
+                timeoutMs: 15_000
+            }).catch(()=>{});
+            if (ownsRunner) await runner.close();
+        }
+    };
+}
+
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+const DEFAULT_BROWSER_IMAGE = 'remote-agent-browser:latest';
+const BASE_ENV = {
+    AGENT_BROWSER_ARGS: '--no-sandbox,--disable-dev-shm-usage,--disable-gpu',
+    AGENT_BROWSER_DEFAULT_TIMEOUT: '25000'
+};
+/** CommandRunner backed by one Vercel Sandbox. */ class SandboxRunner {
+    constructor(sandbox, env){
+        this.sandbox = sandbox;
+        this.env = env;
+    }
+    async run(cmd, args, opts = {}) {
+        const timeoutMs = opts.timeoutMs ?? 60_000;
+        const command = await this.sandbox.runCommand({
+            cmd,
+            args,
+            env: {
+                ...this.env,
+                ...opts.env
+            },
+            detached: true
+        });
+        let timer;
+        const timeout = new Promise((_, reject)=>{
+            timer = setTimeout(()=>reject(new Error(`command timed out after ${timeoutMs}ms`)), timeoutMs);
+            if (typeof timer.unref === 'function') timer.unref();
+        });
+        try {
+            const finished = await Promise.race([
+                command.wait(),
+                timeout
+            ]);
+            const exitCode = typeof finished === 'number' ? finished : finished.exitCode;
+            const [stdout, stderr] = await Promise.all([
+                command.output('stdout'),
+                command.output('stderr')
+            ]);
+            return {
+                stdout,
+                stderr,
+                exitCode
+            };
+        } catch (error) {
+            await command.kill().catch(()=>{});
+            throw error;
+        } finally{
+            if (timer) clearTimeout(timer);
+        }
+    }
+    async readFile(path) {
+        const { stdout, exitCode, stderr } = await this.run('base64', [
+            '-w0',
+            path
+        ], {
+            timeoutMs: 30_000
+        });
+        if (exitCode !== 0) {
+            throw new Error(`failed to read ${path}: ${stderr.trim()}`);
+        }
+        return Buffer.from(stdout.trim(), 'base64');
+    }
+    async close() {
+        await this.sandbox.stop().catch(()=>{});
+    }
+}
+/**
+ * Start an ephemeral Vercel Sandbox from the pre-built browser image.
+ *
+ * The image must already exist in the Sandbox project's Vercel Container
+ * Registry and contain both `agent-browser` and Chromium. A repository name,
+ * tag, digest, or fully-qualified VCR reference is accepted by the SDK.
+ */ async function provisionBrowserSandbox(opts) {
+    const image = opts.image ?? process.env.REMOTE_AGENT_BROWSER_IMAGE ?? DEFAULT_BROWSER_IMAGE;
+    const env = {
+        ...BASE_ENV,
+        ...opts.env
+    };
+    const sandbox = await Sandbox.create({
+        image,
+        resources: {
+            vcpus: opts.vcpus ?? 2
+        },
+        timeout: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        ports: [],
+        env,
+        persistent: false
+    });
+    return new SandboxRunner(sandbox, env);
+}
+
+/**
+ * Create an agent-browser client running inside a fresh Vercel Sandbox.
+ *
+ * The sandbox boots from a browser-ready VCR image and the returned client
+ * runs every command as
+ * `agent-browser --session <name> …` so page state persists across calls.
+ * `close()` closes the browser and stops the sandbox.
+ *
+ * Auth comes from the environment (VERCEL_OIDC_TOKEN on Vercel, or a local
+ * `vercel login`), via @vercel/sandbox.
+ *
+ * ```ts
+ * import { createAgentBrowser } from 'remote-agent-browser'
+ *
+ * const browser = await createAgentBrowser()
+ * const { results } = await browser.run([
+ *   ['open', 'https://example.com'],
+ *   ['snapshot', '-i', '--json'],
+ * ])
+ * await browser.close()
+ * ```
+ */ async function createAgentBrowser(opts = {}) {
+    const runner = await provisionBrowserSandbox({
+        image: opts.image,
+        timeoutMs: opts.timeoutMs,
+        vcpus: opts.vcpus,
+        env: opts.env
+    });
+    return createBrowserClient(runner, {
+        session: opts.session,
+        ownsRunner: true
+    });
+}
+
+export { createAgentBrowser, createBrowserClient };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "remote-agent-browser",
+  "version": "0.1.0",
+  "description": "Run agent-browser in a Vercel Sandbox created from a browser-ready container image",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vercel-labs/remote-agent-browser.git"
+  },
+  "type": "module",
+  "packageManager": "pnpm@11.18.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bunchee --runtime node",
+    "prepublishOnly": "node --run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --run build && node --test tests/*.test.mjs",
+    "test:integration": "node --run build && node --test tests/integration.test.mjs",
+    "test:unit": "node --run build && node --test tests/unit.test.mjs"
+  },
+  "files": [
+    "dist",
+    "Dockerfile.sandbox"
+  ],
+  "dependencies": {
+    "@vercel/sandbox": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "bunchee": "^7.0.0",
+    "typescript": "^5.9.0"
+  }
+}