Quickstart
Sign in, set a key, and connect the Playwright you already use to a Chrome in its own microVM. Everything the SDK does is one REST call underneath.
01
Get a key
Make an account with your email or GitHub. The dashboard makes API keys, shows each one once, and lists your sessions with everything that happened to them.- Sessions at once
- 2
- Longest session
- 60 minutes (15 by default)
- Browser time
- 60 minutes a day
- Sign up
- Email or GitHub, no card
02
Install the SDK and Playwright
Puppeteer works too, withpuppeteer.connect({ browserWSEndpoint: session.connectUrl }).terminalnpm install batonvm playwright-core export BATON_API_KEY=bk_...03
Run a browser
Create a session, connect over CDP, then move it, copy it, put it to sleep and start one already logged in.first-session.tsimport { Baton } from "batonvm"; import { chromium } from "playwright-core"; const baton = new Baton(); // reads BATON_API_KEY const session = await baton.sessions.create(); const browser = await chromium.connectOverCDP(session.connectUrl); const context = browser.contexts()[0]; const page = context.pages()[0] ?? (await context.newPage()); await page.goto("https://example.com"); console.log(await page.title()); const move = await session.migrate(); // the browser changes machines mid-script console.log(`moved ${move.from} → ${move.to}, paused ${move.pausedMs} ms`); console.log(await page.title()); // same page, same connection const { sessions: [copy] } = await session.fork(1); // a copy: same pages, cookies, storage const twin = await chromium.connectOverCDP(copy.connectUrl); console.log(twin.contexts()[0].pages().map((p) => p.url())); await copy.close(); // Sleep: store the browser and free its machine, then bring it back anywhere. await session.pause(); // idle browsers cost nothing; kept up to 7 days await session.resume(); // same pages and cookies; session.connectUrl is fresh // Log in once, save it, and start later sessions already logged in. await session.saveProfile("shop"); const later = await baton.sessions.create({ profile: "shop" }); await session.close(); await later.close();04
Or from Python
The same calls in Python's naming, with Playwright for Python.AsyncBatonis the asyncio version, for browser-use and Playwright's async API.terminalpip install batonvm playwright export BATON_API_KEY=bk_...first_session.pyfrom batonvm import Baton from playwright.sync_api import sync_playwright baton = Baton() # reads BATON_API_KEY with baton.sessions.create() as session, sync_playwright() as p: browser = p.chromium.connect_over_cdp(session.connect_url) page = browser.contexts[0].pages[0] page.goto("https://example.com") print(page.title()) move = session.migrate() # the browser changes machines mid-script print(f"moved {move.from_node} → {move.to_node}, paused {move.paused_ms} ms") print(page.title()) # same page, same connection copy = session.fork(1).sessions[0] # a copy: same pages, cookies, storage copy.close() session.pause() # stored; no machine holds it; kept up to 7 days session.resume() # back on any machine; session.connect_url is fresh session.save_profile("shop") # log in once... later = baton.sessions.create(profile="shop") # ...start already logged in later.close() # the session ends with the with-block
Session options
Set per session when you create it. The browser has them before you connect, on every tab it opens, and keeps them when it moves, forks, pauses and resumes.
const session = await baton.sessions.create({
viewport: { width: 1280, height: 800 },
userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
locale: "fr-FR", // Accept-Language, navigator.language, Intl
timezone: "Europe/Paris", // Date and Intl in every page
timeoutMinutes: 45, // up to 60; the default is 15
proxy: { server: "proxy.example.com:8080", username: "me", password: "..." },
});session = baton.sessions.create(
viewport=(1280, 800),
user_agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
locale="fr-FR",
timezone="Europe/Paris",
timeout_minutes=45,
proxy={"server": "proxy.example.com:8080", "username": "me", "password": "..."},
)| option | what it does |
|---|---|
viewport | Page size in CSS pixels, 320-3840 by 240-2160. |
userAgent | Sent with every request and reported by navigator.userAgent. |
locale | A language tag like fr-FR: the Accept-Language header, navigator.language and number and date formats. |
timezone | An IANA name like Europe/Paris, for Date and Intl. |
timeoutMinutes | How long the session may run, up to 60. The default is 15. |
proxy | Your own HTTP proxy (it must support CONNECT). Every connection the browser opens goes out through it, so sites see its address. UDP is blocked, so QUIC and WebRTC can't go around it. |
The REST API
Every call takes Authorization: Bearer <key>. The SDK is a thin layer over these.
curl -X POST https://batonvm.vercel.app/api/v1/sessions \
-H "Authorization: Bearer $BATON_API_KEY"
# → { "id": "vm-...", "status": "running", "connectUrl": "wss://.../cdp/...", "expiresAt": "..." }| call | what it does |
|---|---|
POST /api/v1/sessions {profile?, ...options} | Start a browser (from a saved profile: already logged in), with the options below; returns connectUrl |
GET /api/v1/sessions[/:id] | Your sessions |
DELETE /api/v1/sessions/:id | End it |
POST /api/v1/sessions/:id/migrate | Move it to another machine, connection kept |
POST /api/v1/sessions/:id/fork {count} | Copy the running browser into new sessions: same pages, cookies, storage |
POST /api/v1/sessions/:id/pause | Store the running browser and free its machine; open connections close |
POST /api/v1/sessions/:id/resume | Bring a paused browser back, on any machine; returns a fresh connectUrl |
GET /api/v1/sessions/:id/events | What happened to it: created, migrated (with the pause), forked, paused, ended and why |
GET /api/v1/profiles | Your saved profiles |
POST /api/v1/profiles {session, name} | Save a running browser’s pages, cookies and storage; it keeps running |
DELETE /api/v1/profiles/:name | Delete a profile |
POST /api/v1/sessions/:id/live | A short-lived URL to watch it |
GET /api/v1/usage | Sessions running, minutes used today |
Limits on the free tier
Over a limit, the API answers 429. Out of capacity, 503 with Retry-After; creating and resuming wait for the new machine, about a minute, instead of failing.
2
sessions running at once
10 new sessions a minute
60 min
longest session
15 unless you set timeoutMinutes
60 min
browser time a day
paused time doesn’t count
5 · 3
paused sessions · profiles
paused ones kept 7 days