Remote Agent Browser

Each call runs inside a remote Sandbox while browser state persists between steps.

INSTALL

pnpm add remote-agent-browser

BASIC USAGE

import { AgentBrowser } from 'remote-agent-browser'

const browser = await AgentBrowser.create({
  args: ['--color-scheme', 'dark'],
})

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

  const page = await browser.exec<{ url: string }>('get', {
    args: ['url'],
    output: 'json',
  })
  console.log(page.data.url)
} finally {
  await browser.close()
}

Authentication is provided by VERCEL_OIDC_TOKEN. On Vercel it is available automatically; locally, pull it from a linked project.

API

AgentBrowser.create(options?)

Start a disposable browser Sandbox. Use args for launch settings shared by every command.

browser.run(commands)

Run several agent-browser commands in one session.

browser.exec(command)

Run one command with arguments and flags.

browser.exec<T>(command, { output: "json" })

Add --json, validate its response, and return the typed data.

browser.upload(selector, files)

Stage local buffers in the Sandbox and upload them through a file input.

browser.download(selector, options?)

Trigger a browser download and return its bytes.

browser.snapshot(url?)

Optionally open a URL, then capture an interactive snapshot.

browser.screenshot(url?)

Optionally open a URL, then return a PNG buffer.

result.file

Read collected screenshots, PDFs, traces, HAR, state, and video output.

browser.close()

Close the session and stop the Sandbox.

Read the full API details in the README.

FILES

import { readFile, writeFile } from 'node:fs/promises'

await browser.upload('#avatar', [{
  name: 'avatar.png',
  bytes: await readFile('avatar.png'),
}])

const { file } = await browser.download('@e4', {
  filename: 'report.csv',
})
await writeFile('report.csv', file.bytes)

const trace = await browser.exec('trace', {
  args: ['stop'],
})
console.log(trace.file?.contentType)

File-producing commands use temporary Sandbox paths and return the collected bytes without exposing the remote filesystem.