DEVELOPER DOCUMENTATION

One browser.
Any CDP client.

Tabcast provides Cloud Chromium, persistent profiles, and Live View. It does not run an AI inference agent.

OpenAPI 3.1 specification ↗ · Open dashboard ↗

Quickstart

Sign in with Google or email and password. Browser access is gradually enabled for accounts. Once enabled, create an API key in your dashboard and start a session.

const session = await fetch('https://api.tabcast.io/v1/sessions', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + process.env.TABCAST_API_KEY,
             'Content-Type': 'application/json' },
  body: JSON.stringify({ profileId: process.env.TABCAST_PROFILE_ID })
}).then(r => r.json());
// Connect within 60 seconds; URL is single-use. Do not log it.

Authentication

Send API keys in the Authorization Bearer header. Keys are stored as SHA-256 hashes, shown once, and can be revoked. Read and write scopes are separate. Account login uses an HttpOnly, SameSite cookie. Never put long-lived keys in URLs.

Sessions & CDP

POST /v1/sessions creates a process; GET lists or retrieves sessions; DELETE gracefully closes it. States are creating, running, closing, closed and failed. POST /v1/sessions/:id/cdp-token issues a fresh one-use connection grant. Disconnecting a WebSocket does not end execution or metering. Browser.close can end only that session’s dedicated process; use DELETE for deterministic termination.

Playwright

import { chromium } from 'playwright';
const browser = await chromium.connectOverCDP(session.cdpUrl);
const context = browser.contexts()[0]; // persistent default context
const page = await context.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.close(); // remote disconnect semantics vary by client
// DELETE /v1/sessions/:id explicitly ends and flushes Chromium.

Puppeteer

import puppeteer from 'puppeteer-core';
const browser = await puppeteer.connect({ browserWSEndpoint: session.cdpUrl });
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.disconnect();

agent-browser

Use the official remote CDP URL option. Keep a dedicated agent-browser session name; do not reuse a local browser daemon.

agent-browser --session tabcast-demo --cdp "$TABCAST_CDP_URL" open https://example.com
agent-browser --session tabcast-demo get title

Stagehand compatibility is not yet verified.

Persistent Profiles

Create via POST /v1/profiles, then reuse profileId when creating a session. Cookies and localStorage in the default browser context survive normal browser shutdown. A profile is locked to one process. Incognito contexts are temporary. External login expiry still applies. Cross-OS profile portability is not guaranteed. Delete only an unlocked profile to permanently remove its files.

Live View

Open a running session in the dashboard. The preview streams JPEG frames from CDP Page.startScreencast, not screenshot polling. Select the same tab your automation uses. Take Control disconnects agent clients; Return to Agent allows new connections. Keyboard, paste, mouse and wheel events use session-scoped CDP Input. No OS-wide input is injected. Recording and audio are off.

1280×720 and 1920×1080 are available. Hidden viewer tabs pause delivery. Reconnection requests a new short-lived grant. Native OS dialogs and passkeys are outside the preview’s scope. 30fps and p95 200ms are targets pending measured validation, not service guarantees.

Security

Browser execution is currently restricted to approved accounts. Separate Chromium profiles and owner-checked gateways do not establish a safe untrusted-customer boundary. Network egress, host filesystem access, hard resource quotas and per-tenant encryption require isolated workers before public service. Do not run untrusted customer workloads here. Chromium sandbox remains enabled; downloads and extensions are disabled by default.

Limits

GET /v1/limits returns concurrency, idle timeout, maximum runtime, profile disk and monthly second limits. Defaults: 4 active sessions, 15-minute idle timeout, 60-minute maximum session and 60 minutes per UTC month. Runtime is metered until the browser exits, including disconnected time. No payment collection is enabled.

Troubleshooting

401: validate key or mint a fresh connection grant. 409: release the profile lock or create a new session. 429: inspect usage and limits. 503: inspect the dedicated worker. If a stream reconnects, verify the session is still running. After manager crashes, reconcile dedicated Tabcast processes before removing its lock; do not unlock an active Chromium profile.

One browser.Any CDP client.