baton

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.

  1. 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
  2. 02

    Install the SDK and Playwright

    Puppeteer works too, with puppeteer.connect({ browserWSEndpoint: session.connectUrl }).
    terminal
    npm install batonvm playwright-core
    export BATON_API_KEY=bk_...
  3. 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.ts
    import { 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();
  4. 04

    Or from Python

    The same calls in Python's naming, with Playwright for Python. AsyncBaton is the asyncio version, for browser-use and Playwright's async API.
    terminal
    pip install batonvm playwright
    export BATON_API_KEY=bk_...
    first_session.py
    from 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.

options.ts
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: "..." },
});
options.py
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": "..."},
)
optionwhat it does
viewportPage size in CSS pixels, 320-3840 by 240-2160.
userAgentSent with every request and reported by navigator.userAgent.
localeA language tag like fr-FR: the Accept-Language header, navigator.language and number and date formats.
timezoneAn IANA name like Europe/Paris, for Date and Intl.
timeoutMinutesHow long the session may run, up to 60. The default is 15.
proxyYour 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.

any language
curl -X POST https://batonvm.vercel.app/api/v1/sessions \
  -H "Authorization: Bearer $BATON_API_KEY"
# → { "id": "vm-...", "status": "running", "connectUrl": "wss://.../cdp/...", "expiresAt": "..." }
callwhat 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/:idEnd it
POST /api/v1/sessions/:id/migrateMove 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/pauseStore the running browser and free its machine; open connections close
POST /api/v1/sessions/:id/resumeBring a paused browser back, on any machine; returns a fresh connectUrl
GET /api/v1/sessions/:id/eventsWhat happened to it: created, migrated (with the pause), forked, paused, ended and why
GET /api/v1/profilesYour saved profiles
POST /api/v1/profiles {session, name}Save a running browser’s pages, cookies and storage; it keeps running
DELETE /api/v1/profiles/:nameDelete a profile
POST /api/v1/sessions/:id/liveA short-lived URL to watch it
GET /api/v1/usageSessions 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