Record a browser session

record is Unsurf’s video-capable proof layer. It wraps a supported browser run and produces a video, trace, status bundle, and viewer link.

Start from a real browser for video capture

agent-browser --headed --profile ~/.cmux-browser open https://example.com

Sign in once. Reuse that browser for video-capable agent work. For normal authenticated investigation, sign in directly through cmux instead.

Record a fresh local browser run

import { recordLocal } from "unsurf/skills/record";

const result = await recordLocal({
  task: "verify the happy path",
  run: async (browser) => {
    await browser.goto("https://example.com");
    await browser.wait(1000);
  },
});

Record the browser already open on your machine

import { recordAttachedLocal } from "unsurf/skills/record";

const result = await recordAttachedLocal({
  connect: 9222,
  task: "record the authenticated dashboard",
  run: async (browser) => {
    await browser.goto("https://example.com/dashboard");
    await browser.wait(4000);
  },
});

CLI equivalent:

export TRACE_INGEST_TOKEN=...
unsurf record ./demo.ts --task "dashboard proof" --cdp-port 9222

Hosted Browser Run provider

import { openBrowserRunBrowser } from "unsurf/skills/record";

const browser = await openBrowserRunBrowser({ binding: env.BROWSER });
try {
  await browser.goto("https://httpbin.org/forms/post");
  await browser.fill('input[name="custname"]', "unsurf");
  const snapshot = await browser.snapshot();
} finally {
  await browser.close();
}

Browser Run is the hosted/provider lane: Cloudflare Worker-side browser flows with the same browser-handle verbs.

import { recordBrowserRunSession } from "unsurf/skills/record";

const recording = await recordBrowserRunSession({
  binding: env.BROWSER,
  run: async (browser) => {
    await browser.goto("https://httpbin.org/forms/post");
    await browser.fill('input[name="custname"]', "unsurf");
  },
});

recordBrowserRunSession(...) turns on Browser Run’s native session recording and returns its session ID after the session closes. Browser Run recordings are replayable rrweb events in Browser Run logs/API, not MP4 files. Local attached Chrome remains the playable-video path.

What the result carries

run status
trace id
viewer URL
optional signed video URL
metadata for the task and provider

Every new trace is grant-gated by default. See Privacy.

When to record

Record when:

a browser task should be reviewable later
an agent run should produce proof, not just text logs
you want a video suitable for docs, debugging, or sharing