The driver plane is deliberately direct-CDP (nodriver-style), not Playwright / Puppeteer: anti-bot stacks block the Playwright control plane independently of how good the browser patches are, so this SDK speaks the Chrome DevTools Protocol over a raw websocket and never calls Runtime.enable.

Install

npm install @scalebrowser/sdk

Ships dual ESM + CJS with full type declarations, and needs Node ≥ 18. The SDK is MIT-licensed, and its source is public at blackdiamond-labs/scalebrowser-node: npm builds every release there and publishes it with a provenance attestation. The daemon it talks to is a separate, licensed product.

Quickstart

import { ScalebrowserClient } from '@scalebrowser/sdk';

const sb = new ScalebrowserClient({
  baseUrl: 'http://127.0.0.1:8787', // daemon native API (default)
  token: process.env.SCALEBROWSER_TOKEN,
});

// Create a coherent, per-seed-unlinkable profile.
const profile = await sb.createProfile({ name: 'acct-01' });

// Start it + open a direct-CDP session. `await using` stops the profile and
// closes CDP when the block exits.
await using session = await sb.launch(profile.id, { headless: true });

await session.cdp.navigate('https://example.com');
const title = await session.cdp.evaluate<string>('document.title');

// Humanized, trusted input is routed through the daemon (real OS/CDP events).
await session.cdp.humanizeMove(120, 220);
await session.cdp.humanizeClick(120, 220);

Without await using (or for explicit control):

const { cdp_ws } = await sb.startProfile(profile.id, { headless: true });
const cdp = await sb.connectCdp(cdp_ws, profile.id);
try {
  await cdp.navigate('https://example.com');
} finally {
  cdp.close();
  await sb.stopProfile(profile.id);
}

REST surface

Every /v1 endpoint is a typed method on ScalebrowserClient:

Profiles: listProfiles, listProfileIds, countProfiles, getProfile, createProfile, updateProfile, deleteProfile, startProfile, stopProfile. releaseProfile drops an agent's lease without its handle (the operator's way out), and takeoverProfile asks for a profile that is open on another machine of your account
Bulk: bulkCreateProfiles, bulkStart, bulkStop, bulkDelete, bulkAssignProxy, bulkAssignExtensions
Groups / Presets: listGroups/createGroup/getGroup/updateGroup/deleteGroup, listPresets/createPreset/getPreset/updatePreset/deletePreset, getPersonaConstraints. A preset is config (what the profiles do: geo_mode, proxy_id, …) plus constraints (what they are: country, which pins the persona's language, timezone and voices). Both are typed and the daemon refuses an unknown key with a 400, so read the valid regions from getPersonaConstraints() rather than hardcoding them.
Proxies: listProxies, createProxy, getProxy, updateProxy, deleteProxy, checkProxy, checkProxyConfig (probe a config before you save it; pass id to reuse an existing proxy's stored credentials). Credentials are write-only, never returned
Extensions: listExtensions, attachExtension, detachExtension, plus the daemon-wide library (listLibraryExtensions, uploadExtension, getLibraryExtension, deleteLibraryExtension, deleteLibraryExtensionVersion). An attached package IS loaded into the browser at launch, under the canonical Web-Store id its own key derives
Credentials: listCredentials, putCredential, deleteCredential, revealCredential (needs the vault password), exportCredentials, importCredentials. The vault password itself: vaultStatus, setVaultPassword
Secret layer: getSecretLayer, setSecretLayer, listSecrets, updateSecret, deleteSecret. scrubText filters a text you hold against a profile's values, and runWithSecrets runs a command with named values in its environment, so no value crosses a socket
Cookies: revealCookies, the one route a cookie VALUE leaves through, behind the same vault password
Recorded requests: revealRequest, the one route what a request carried (query, header values, body) leaves through, behind the same vault password
Sessions: exportSession, importSession
Mailboxes: listInboxes, createInbox, updateInbox, deleteInbox, getInboxBindings, bindInbox, unbindInbox, which is where a profile's confirmation codes arrive
Passkeys: listPasskeys, deletePasskey. Metadata only: the private key has no field and no endpoint
Agent runs: listRuns, getRun, listRunSteps, getRunShot, getActivity. Read-only, all of it
Interruptions: listInterruptionLocks, setInterruptionLock, listInterruptionRules, setInterruptionRule, deleteInterruptionRule: who may answer when the browser asks something
Artifacts: putArtifact (hand the daemon a file to upload later), getArtifact (fetch a screenshot, download or saved PDF as bytes)
Tasks and memory: listTasks, createTasks, cancelTask, deleteTask, plus a profile's standing instructions for agents, its PROFILE.md: getProfileMemory, putProfileMemory, deleteProfileMemory
Videos: listVideos, getVideo, renameVideo, deleteVideo, cancelVideo, rerenderVideo, videoAccess, downloadVideoFile, videosStorage; recordings with listRecordings, getRecording, deleteRecordingRaw, renderRecording; public links with share, shareStatus, revokeShare
Video presets: listVideoPresets, getVideoPreset, createVideoPreset, updateVideoPreset, duplicateVideoPreset, deleteVideoPreset, and a look at an unsaved config with previewVideoPreset, previewVideoPresetClip, downloadVideoPresetClip. The files a preset points at: listMedia, uploadMedia, deleteMedia, mediaFile. Narration keys: listTtsProviders, putTtsProvider, verifyTtsProvider, deleteTtsProvider. Encoders: getCodecs, setCodecEnabled
Fingerprint audit: startAudit drives the profile's running browser through the external detector pages, getAudit reads the state and the last report
Exit addresses: getExitStatus (which addresses a profile owns), and the machine's rule that one address belongs to one profile: getExitRule, setExitRule
Machine settings: getRemoteAccess, setRemoteAccess (may a chat service reach this machine's browsers), getAgentTools, setAgentToolGroup (which optional MCP tool groups agents see), getConnection (which installation answered: its data directory and its binary)
Input: sendInput
Metrics / Account / Health: getMetrics, getAccount, health, ready. The first two answer 404 on a daemon without them, which the SDK treats as information rather than as an error: metrics are then derived from profile state, and the account reads licensed: false, which is what "self-hosted, no control plane" means

setToken swaps the bearer token on a live client.

Errors map to typed exceptions carrying the daemon's numeric code (4001–4013):

import { ApiError, ErrorCode } from '@scalebrowser/sdk';

try {
  await sb.startProfile(id);
} catch (err) {
  if (err instanceof ApiError && err.code === ErrorCode.Capacity) {
    // 4003: capacity exceeded
  }
}

Lifecycle events (SSE)

// callback form
const unsubscribe = sb.subscribeEvents({
  onEvent: (e) => {
    if (e.type === 'profile_crashed') console.warn(e.profile_id, e.reason);
  },
});

// or async-iterator form
for await (const e of sb.events()) {
  if (e.type === 'profile_started') console.log(e.cdp_ws);
}

Direct-CDP driver

CdpSession (returned by connectCdp / launch) gives you:

send<T>(method, params?): raw CDP command, awaited by id (concurrent-safe)
navigate(url, { wait, timeout }), evaluate<T>(expr, { isolated }). The wait for the load reads from an isolated world, so a page that watches its own document.readyState sees no foreign read; isolated: true asks for the world of the document that is loaded now, on every call
createIsolatedWorld(frameId?, worldName?)
attachToPage({ targetId?, create?, url? })
on(method, cb) / events(): CDP event subscription scoped to the session
humanizeMove / humanizeClick / humanizeType / humanizeScroll
close()

Security

Bearer token is sent on every request and the SSE/CDP handshakes; it is never logged (the client's inspect output masks it).
Proxy credentials are injected by the daemon and never travel over CDP.
The CDP endpoint is guarded by the OS user, not by that token. The engine's DevTools port has no authentication of its own: it answers a bogus bearer with 200, measured, so the engine drops any connection whose peer process runs as a different user. Nothing to configure and nothing to pass: your process is the one that started the profile, so it is on the allowed side. A helper running as another account will not get in, by design.

Develop

npm install
npm run typecheck   # tsc --noEmit (strict)
npm run build       # tsup → dist/ (ESM + CJS + .d.ts)
npm test            # vitest (unit; e2e skipped unless SCALEBROWSER_E2E=1)

The env-gated end-to-end test runs the full path against a real daemon + mock engine:

SCALEBROWSER_E2E=1 SCALEBROWSER_BASE_URL=http://127.0.0.1:8787 \
  SCALEBROWSER_TOKEN=… npm test

Keywords

chrome-devtools-protocol

FAQs

What is @scalebrowser/sdk?

Is @scalebrowser/sdk well maintained?

Package last updated on 22 Oct 2026

@scalebrowser/sdk