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.

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.