Browser Sessions

Browser Sessions are currently in invite-only preview. Access is enabled for approved organizations, and API routes, SDK method names, response fields, limits, and pricing may change before general availability.

Browser Sessions create managed Chromium sessions for web agents and browser automation. OpenComputer handles API-key auth and org ownership, then returns browser connection URLs for tools such as Playwright and Magnitude. If your organization has not been invited to the preview, Browser Session API calls may fail even when your OpenComputer API key is valid. Use Browser Sessions when you want a cloud browser without installing Chromium inside an OpenComputer sandbox. Use sandboxes when you need a full Linux VM with your own browser runtime and filesystem.

Create a Browser

import { Browser } from "@opencomputer/sdk";

const browser = await Browser.create({
  headless: false,
  stealth: true,
  startUrl: "https://example.com",
  timeoutSeconds: 120,
});

console.log(browser.id);
console.log(browser.cdpWsUrl);
console.log(browser.liveViewUrl);

await browser.delete();

from opencomputer import Browser

browser = await Browser.create(
    headless=False,
    stealth=True,
    start_url="https://example.com",
    timeout_seconds=120,
)

print(browser.id)
print(browser.cdp_ws_url)
print(browser.live_view_url)

await browser.delete()

Headful browsers return a live-view URL. Headless browsers are lighter, but do not provide a live view. Telemetry is enabled by default for all browser sessions. Set telemetry: false / telemetry=False to disable it, or pass a Kernel telemetry configuration object directly. Replay recording is disabled by default. Set recording: true / recording=True to enable replay recording for a headful browser session.

Profile Auth Checks

Saved profiles can start an asynchronous auth check for a site. The SDK returns a run immediately; wait() polls with short requests until the run completes.

TypeScript

const profile = await BrowserProfile.connect("linkedin-profile");

const run = await profile.checkAuth({
  homepage: "https://www.linkedin.com/feed/",
  user: "motatoes",
  mode: "vision",
  compareFresh: true,
});

const result = await run.wait();
console.log(result.status, result.result);

Auth checks are read-only. They create temporary browser sessions with profile saving disabled and compare the saved profile against a fresh browser when compareFresh is enabled.

Playwright

The browser response includes a CDP WebSocket URL. Pass it directly to Playwright’s connectOverCDP.

import { Browser } from "@opencomputer/sdk";
import { chromium } from "playwright";

const ocBrowser = await Browser.create({
  headless: false,
  startUrl: "https://example.com",
});

try {
  const browser = await chromium.connectOverCDP(ocBrowser.cdpWsUrl);
  const context = browser.contexts()[0] || await browser.newContext();
  const page = context.pages()[0] || await context.newPage();

  await page.goto("https://example.com");
  console.log(await page.title());

  await browser.close();
} finally {
  await ocBrowser.delete();
}

from opencomputer import Browser
from playwright.async_api import async_playwright

oc_browser = await Browser.create(
    headless=False,
    start_url="https://example.com",
)

try:
    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(oc_browser.cdp_ws_url)
        context = browser.contexts[0] if browser.contexts else await browser.new_context()
        page = context.pages[0] if context.pages else await context.new_page()

        await page.goto("https://example.com")
        print(await page.title())

        await browser.close()
finally:
    await oc_browser.delete()

Magnitude

Magnitude can use a Playwright-connected browser. Create the OpenComputer browser first, connect over CDP, then hand the page to your Magnitude agent.

TypeScript

import { Browser } from "@opencomputer/sdk";
import { chromium } from "playwright";
import { startBrowserAgent } from "magnitude-core";

const ocBrowser = await Browser.create({
  headless: false,
  stealth: true,
  startUrl: "https://example.com",
});

try {
  const browser = await chromium.connectOverCDP(ocBrowser.cdpWsUrl);
  const context = browser.contexts()[0] || await browser.newContext();
  const page = context.pages()[0] || await context.newPage();

  const agent = await startBrowserAgent({ page });
  await agent.act("Find the page title and summarize what this site is for.");

  await browser.close();
} finally {
  await ocBrowser.delete();
}

Magnitude package names and constructors can vary by version. The OpenComputer-specific step is stable: create a Browser, connect to cdpWsUrl with Playwright, then pass the resulting page or browser object to Magnitude.

Save and Load Profiles

Profiles persist browser state such as cookies and local storage across browser sessions. Profiles are scoped to your OpenComputer org; another org cannot list, load, or delete your profiles. Create a profile once:

import { BrowserProfile } from "@opencomputer/sdk";

const profile = await BrowserProfile.create({
  name: "github-login",
});

from opencomputer import BrowserProfile

profile = await BrowserProfile.create(name="github-login")

Use the profile when creating a browser:

import { Browser } from "@opencomputer/sdk";

const browser = await Browser.create({
  profile: {
    id: profile.id,
    saveChanges: true,
  },
  headless: false,
});

// Log in or update session state, then delete the browser.
// With saveChanges enabled, changes are saved back to the profile.
await browser.delete();

from opencomputer import Browser

browser = await Browser.create(
    profile={
        "id": profile.id,
        "save_changes": True,
    },
    headless=False,
)

# Log in or update session state, then delete the browser.
# With save_changes enabled, changes are saved back to the profile.
await browser.delete()

Load the same profile later by ID or name:

import { Browser, BrowserProfile } from "@opencomputer/sdk";

const profile = await BrowserProfile.connect("github-login");

const browser = await Browser.create({
  profile: {
    id: profile.id,
    saveChanges: true,
  },
  headless: false,
});

from opencomputer import Browser, BrowserProfile

profile = await BrowserProfile.connect("github-login")

browser = await Browser.create(
    profile={
        "id": profile.id,
        "save_changes": True,
    },
    headless=False,
)

Authentication

The SDK uses your OpenComputer API key:

export OPENCOMPUTER_API_KEY="osb_..."

For local development against a non-production Browser Sessions endpoint, set OPENCOMPUTER_BROWSER_API_URL.

Getting Started

Sandboxes

Durable Agent Sessions

Reserved Capacity

CLI

Guides

TypeScript SDK

Python SDK

CLI Reference

API Reference

Resources

Browser Sessions

Create a Browser

Profile Auth Checks

Playwright

Magnitude

Save and Load Profiles

Authentication

​Create a Browser

​Profile Auth Checks

​Playwright

​Magnitude

​Save and Load Profiles

​Authentication

Create a Browser

Profile Auth Checks

Playwright

Magnitude

Save and Load Profiles

Authentication