Build Kernel TS Sdk

Build Kernel TS SDK

Build with the Kernel TypeScript SDK (@onkernel/sdk@0.123.0, generated from Kernel's OpenAPI spec by Stainless), @onkernel/cli@0.47.0, and the React helpers @onkernel/managed-auth-react@0.5.5 and @onkernel/vault-react@0.2.0. Kernel runs each browser as a unikernel-isolated VM and co-locates your code with the browser to remove CDP latency. The SDK and CLI surface the same API.

When to use this skill

Use this skill if the task involves any of:

• building or extending TypeScript code that imports @onkernel/sdk or constructs new Kernel(...)
• driving a Kernel browser via kernel.browsers.create, cdp_ws_url, kernel.browsers.playwright.execute, kernel.browsers.computer.*, kernel.browsers.repl, kernel.browsers.webmcp.*, or kernel.browsers.process.*
• deploying a Kernel App with kernel deploy and invoking it via kernel.invocations.create (sync or async with invocations.follow)
• wiring Playwright, Stagehand, Browser Use, Claude Agent SDK, Vibium, Notte, Magnitude, Laminar, or Val Town to a Kernel browser
• configuring proxies (proxies.*), per-host proxy routing (network.proxy_routes), or ISP/Residential/Mobile/Custom tiers
• performing multi-provider web search and content extraction via kernel.search.* or kernel search
• using in-VM Browser REPL (kernel.browsers.repl), Code Mode, or WebMCP page tool discovery (kernel.browsers.webmcp.*)
• using profiles (profiles.*), browser pools (browserPools.*), vaults/credentials (vaults.*, credentials.*), or replays/file I/O (browsers.fs.*, browsers.replays.*)
• implementing Managed Auth with auth.connections.* and the React <KernelManagedAuth /> component
• scoping KERNEL_API_KEY or CLI requests per project via projectID client option or CLI --project / KERNEL_PROJECT
• finding recommended browser/proxy settings for a bot-protected site (kernel.configRegistry.*), Web Bot Auth signing, or SSH into a browser VM
• audit logs, spending caps, projects, API keys, org limits/entitlements
• connecting an agent or IDE to the hosted Kernel MCP server (kernel mcp install)
• debugging Kernel-specific failures: browser.close() not cleaning up, sync-invocation 100 s timeout, default-context confusion, 409 profile conflicts

Do NOT use this skill for:

• Terminal-driving the agent-browser CLI (agent-browser -p kernel, @ref snapshots, snapshot -i --json) — out of scope. This skill owns Kernel-SDK code; follow the CLI's own docs for the CLI.
• Python Kernel SDK (kernel-python-sdk), or Browser Use's Python framework — no native TS package.
• LangChain.js / LangGraph agents that may incidentally call browser tools but are not Kernel-specific.

Cross-skill disambiguation

Two operating modes — decide first

Mixing is fine — most production setups deploy long-running browser work as a Kernel App and invoke it from an embedding service. Don't try to make a single function do both.

Deploy vs invoke glossary

• App: named deployed codebase containing one or more actions.
• Action: named function registered inside an app.
• Deployment: build/version event that creates or updates an app version; track deployment.id, app name, and version.
• Invocation: one execution of one action; invocations.create requires app_name, action_name, and version (all three are non-optional; version is a deployed label or latest). Track invocation.id, sync/async mode, status, logs/events, and output handling.

Hard rules — load-bearing

1. KERNEL_API_KEY from env. Never hardcode. The env var is only the default: an explicit apiKey: option overrides it (client.ts: apiKey = readEnv('KERNEL_API_KEY')).
2. Pin the SDK. @onkernel/sdk is auto-generated by Stainless and rev's frequently. Pin @onkernel/sdk@0.123.0 and @onkernel/cli@0.47.0; verify method names against the installed type declarations — node_modules/@onkernel/sdk/client.d.ts for the top-level resource list, node_modules/@onkernel/sdk/resources/**/*.d.ts for method signatures and params. The npm package ships no api.md.
3. Never use browser.close() as cleanup. Playwright/Puppeteer close() only severs the local CDP connection. Always call kernel.browsers.deleteByID(session_id) (or rely on timeout_seconds).
4. Sync invocation: ~100 s server cap, but the default SDK client gives up at 60 s and retries twice. A 60–100 s sync run is aborted client-side and re-sent. Anything longer than ~50 s must use async: true with async_timeout_seconds (10–3600) and invocations.follow(id) for SSE; if you must stay sync pass { timeout: 110_000, maxRetries: 0 }. Sync vs async is chosen per request — no re-deploy.
5. Default browser context only. Kernel browsers ship with one default context and one open page. Use browser.contexts()[0] and pages()[0] — do not call browser.newContext() / context.newPage() to make a "fresh" one.
6. Project scoping is supported in SDK and CLI. With an org-wide API key, scope to a project with new Kernel({ projectID: 'proj_…' }) (sends X-Kernel-Project-Id, ID only) or new Kernel({ project: '<id-or-exact-name>' }) (sends X-Kernel-Project). Both default to null, withOptions() carries them, and the SDK reads no project env var, so pass it yourself (e.g. projectID: process.env.KERNEL_PROJECT). Hand-wiring defaultHeaders is the escape hatch, not the idiom. In the CLI, the global --project flag and KERNEL_PROJECT send X-Kernel-Project and accept a project ID or an exact project name (CLI v0.47.0 source and tests; the docs page reference/cli/projects still says ID only). Project-scoped API keys: kernel api-keys create --name <name> --project-id <project_id>; a scoped key plus a mismatching project header is rejected with 403.
7. Runtime requirements. TypeScript ≥ 4.9. Supported runtimes: up-to-date browsers, Node 20 LTS+, Deno 1.28+, Bun 1.0+, Cloudflare Workers, Vercel Edge Runtime, Jest 28+ ("node" env), Nitro v2.6+. React Native is unsupported.
8. Payload size: the docs disagree and nothing enforces it client-side. apps/develop and the CLI --payload row say 64 KB; apps/invoke says stringified JSON up to 4.5 MB. SDK types and CLI source carry no limit. Treat 64 KB as the safe limit; send larger data through browsers.fs.* or object storage and pass a pointer. Log lines over 64 KiB are truncated.
9. Retries re-run side effects. The client retries timeouts, 408, 409, 429 and ≥ 500. Pass { maxRetries: 0 } for webmcp.invokeTool, invocations.create, deployments.create and search.create (a retry starts a second run); for playwright.execute / repl with timeout_sec above ~50 pass { timeout: (timeout_sec + 15) * 1000, maxRetries: 0 }. See references/guides/client-and-config.md.
10. A 403 on create/acquire/invoke can be a spending cap, not a code bug (80% email, 100% pause). See references/guides/org-audit-and-limits.md.

Default stance

• stealth: true for any non-trivial site — bot detection is the rule, not the exception.
• timeout_seconds: 300 as your floor for real automation — the 60 s default reaps too aggressively. The API range is 10–259200 (72 h) and inactivity is polled every 5 s, so short-lived headless scrapes may legitimately go lower.
• Headful when you need live view, replays, or GPU. Headless for fast scripted scrapes (~8× cheaper, faster boot, but more detectable).
• Prefer kernel.browsers.playwright.execute(id, { code }) for hot paths (runs in the browser VM with no CDP roundtrip). Reserve raw CDP for long-lived interactive sessions.
• For a bot-protected target, check kernel.configRegistry.lookup({ url }) first (see references/guides/stealth-and-config-registry.md).
• Use Kernel profiles for any flow that needs login state across sessions; create named profiles explicitly. Reach for Managed Auth when those credentials belong to your end-users.
• Only one parallel browser should write the same profile with save_changes: true; other parallel browsers should load it read-only.
• A browser is "active" while a CDP client, a WebDriver/BiDi client, or a live-view client is connected, or a computer.* request is in flight. After 5 s with none of those it enters standby (zero compute cost) and only THEN does its timeout_seconds countdown to deletion start. GPU browsers do not support standby — they bill for their entire lifetime at ~48× the headless rate, so keep timeout_seconds tight and delete explicitly. Standby stops charges, not the concurrency slot: delete browsers to free it.

Quick start

For a new scratch project, use the scaffold script so package pins come from npm at generation time:

bash scripts/scaffold-kernel-app.sh --mode embed --dir ./kernel-embed-demo
cd ./kernel-embed-demo
npm install
export KERNEL_API_KEY=...   # never commit; use .env.example only as template
npm run check
npm run start

For an existing repo, install explicitly and keep a pinned range:

npm install @onkernel/sdk@^$(npm view @onkernel/sdk version) playwright-core   # or `playwright` if you also launch local browsers
npm install -D tsx typescript @types/node

First browser creation must print the session_id, do the work, then call kernel.browsers.deleteByID(session_id) in finally. If a browser, pool lease, auth session, deployment, or invocation is intentionally left alive, report the ID, timeout, and reason.

Current-doc/version check

• Existing repo: run scripts/check-kernel-sdk-version.sh before changing Kernel code. Read scripts/check-kernel-sdk-version.sh.md for output interpretation.
• New repo: run npm view @onkernel/sdk version dist-tags --json before pinning; prefer a minor range for scaffolds, not latest.
• Installed SDK: the npm package does not ship api.md. Read the shipped declarations — node_modules/@onkernel/sdk/client.d.ts for the resource list, node_modules/@onkernel/sdk/resources/**/*.d.ts for methods and params (e.g. grep -nE '^ [a-zA-Z]+\(' node_modules/@onkernel/sdk/resources/browsers/browsers.d.ts). Stainless regenerates frequently and method names move. The generated api.md index lives only in the source repo (https://github.com/kernel/kernel-node-sdk/blob/main/api.md), tracks main rather than your pin, and omits lib-only helpers such as browsers.fetch (streams a response; works only for a session this client created, retrieved or listed) — the local .d.ts files win on any disagreement.
• Live docs: for pricing, billing, Managed Auth, profiles, browser pools, deployment/invocation, or payload-size claims, check https://www.kernel.sh/docs/llms.txt and the linked page before changing code.

Cost-facing preflight

Before running code, name every operation that may create paid or quota-bound resources:

• browsers.create, especially headful, GPU, high-resolution viewport, long timeout_seconds, proxy, extension, or profile-backed sessions
• browser pool create, acquire, and unreleased acquired browsers
• Kernel App deployments.create, kernel deploy, and invocations.create
• Managed Auth connections/login sessions and credential providers
• proxies and file/replay artifacts that require a live browser to read back
• App invocations: billed per second of execution in addition to the browsers they create; failed and cancelled runs still bill

For each resource, decide the cleanup path before running: deleteByID, pool release, invocation/browser cleanup by invocation_id, deployment terminal state, or explicit timeout with reason. Report anything left alive.

Read the real caps instead of guessing at plan tiers: await kernel.organization.limits.retrieve() returns max_concurrent_sessions, default_project_max_concurrent_sessions, concurrent_sessions_used, concurrent_sessions_available, max_auth_connections vs auth_connections_used, vaults_used, max_vaults, and min_health_check_interval_seconds. Per-project overrides live at kernel.projects.limits.retrieve(idOrName). concurrent_sessions_used/available, max_auth_connections and max_vaults can be null; project limits also carry max_concurrent_invocations, and exceeding invocation concurrency throws RateLimitError (429) immediately. Gate features on (await kernel.organization.entitlements.retrieve()).features.<name>.enabled. Discover project ids with kernel.projects.list() or kernel.projects.retrieve('<id-or-name>').

Workflow

1. Classify the operating mode (A vs B). If mixed, name which surface each piece is on.
2. Construct the client. import Kernel from '@onkernel/sdk'. Verify env (KERNEL_API_KEY is the only required one; KERNEL_LOG, KERNEL_BASE_URL, KERNEL_CUSTOM_HEADERS, KERNEL_SUPPRESS_BUN_WARNING, and KERNEL_BROWSER_ROUTING_SUBRESOURCES — comma-separated path prefixes routed direct-to-VM, default curl,telemetry/stream,computer,playwright,process,fs,logs/stream, empty string disables direct routing — are optional). For local dev hitting https://localhost:3001/, pass environment: 'development', baseURL: null. For project-scoped work with an org-wide key, pass projectID to the constructor. See references/guides/client-and-config.md.
3. Pick the browser-control surface — raw CDP / Playwright-inside-VM / computer-controls / browser-curl / browser REPL / WebMCP / process execution. See references/patterns/browser-control-surfaces.md.
4. Wire profiles, browser pools, or Managed Auth / Vaults if the agent needs persistent state or credentials. See references/patterns/profiles-pools-credentials.md and references/guides/managed-auth.md.
5. Handle lifecycle. Always pair browsers.create with browsers.deleteByID, even on error paths. Use try/finally. See references/guides/browsers-lifecycle.md.
6. Deploy or run. For Mode B, kernel deploy and consume invocations; for Mode A, run inside your service. See references/guides/apps-deploy-invoke.md and references/examples/deploy-and-invoke-app.md.

Do this, not that

Steering callouts

browser.close() is not cleanup. Closing the Playwright Browser only disconnects CDP. The Kernel browser keeps running until timeout_seconds elapses or you call kernel.browsers.deleteByID(session_id). Always pair create with deleteByID in a finally block.

There is already a default context and page. Calling browser.newContext() makes a second context; cookies, storage, and profile state live on the default one. Use browser.contexts()[0].pages()[0].

Sync invocations time out at ~100 s. If your action does any non-trivial browser work, set async: true and invocations.follow(id) instead. The default SDK client gives up at 60 s, so for sync calls pass { timeout: 110_000, maxRetries: 0 }. The CLI mirrors this: kernel invoke is async and follows the stream; --sync is one POST that times out after 60 s.

Stagehand v4 attaches over CDP; new Stagehand(...) is gone. The constructor is private — use Stagehand.create(), and pass a browser (it is required). Upload the extension first with browsers.fs.uploadZip(id, { dest_path, zip_file }), where dest_path is the same absolute path Stagehand reads locally (<@browserbasehq/stagehand dist>/extension, zip at assets/stagehand-extension.zip), then const browser = await localBrowser.connect({ cdpUrl: session.cdp_ws_url }) and await Stagehand.create({ browser, model: { modelName: 'openai/gpt-4o', apiKey: process.env.MODEL_API_KEY } }). env: 'LOCAL' and localBrowserLaunchOptions are v3-only and do not exist in v4; modelName must be namespaced (openai/…, anthropic/…), never bare 'gpt-4o'. Top-level apiKey is the Stagehand key — model credentials belong in model.apiKey. projectId is not a Stagehand.create option at all; Browserbase credentials live on browserbase.connect(...). stagehand.page was removed — act/extract/observe are on the instance; extract returns { data }; get the page with await browser.context.activePage(); clean up stagehand.close() → browser.close() → deleteByID.

proxy_id is deprecated on browsers.create. Deprecated in @onkernel/sdk@0.88.0 (2026-08-10). Pass the typed proxy object instead — proxy: { id }, proxy: { name }, or proxy: { mode: 'direct' | 'default' }. proxy and proxy_id cannot be combined, and proxy_id is @deprecated on every browser response shape too. disable_default_proxy is deprecated in favor of proxy: { mode: 'direct' }. For per-host routing, use network.proxy_routes (e.g. hosts: ['example.com', '*.example.com'], proxy: { name }), which fails closed on route failure. The datacenter proxy type was dropped from the SDK types in 0.121.0 (the API deprecated it); use isp. Pools take proxy_id, not proxy. See references/guides/proxies.md.

Multi-Provider Search API: kernel.search.create routes across 10 providers (Brave, Exa, Perplexity, Tavily, …) with strategy { type: 'auto' }, { type: 'pinned', provider: { provider: 'exa' } } or { type: 'fallback', providers: [{ provider: 'exa' }, …] }; results are retained 24 h. The API is entitlement-gated (features.search.enabled), billed, and must be called with { maxRetries: 0 }. See references/guides/search.md.

Browser REPL & WebMCP: The in-VM REPL (kernel.browsers.repl) provides stateful Node.js execution with pre-injected page helpers (gotoUrl, pageInfo, click, fillInput, js) and dynamic module imports (patchright), enabling single-turn Code Mode agents. WebMCP discovers and invokes native page tools (kernel.browsers.webmcp.*). A REPL call that exceeds timeout_sec destroys all REPL state (check repl_terminated). WebMCP does not retry the tool server-side, but the SDK client retries 5xx, so pass { maxRetries: 0 } to invokeTool; HTTP 504 outcome_unknown means the action may have run. See references/patterns/browser-repl.md and references/patterns/webmcp.md.

Supported Regions: Kernel supports four browser and browser-pool regions: 'us-east' | 'us-west' | 'eu-west' | 'ap-southeast' (requires Start-Up or Enterprise plan, defaults to us-east). The docs regions page lists only us-east, eu-west and ap-southeast; us-west is in the SDK types (added in @onkernel/sdk 0.120.0) and the CLI flags. Regions do not provide data residency. App deployments support 'aws.us-east-1a' with multi-host routing.

Audio: Headful browsers play audio by default. Replays support record_audio: boolean (defaults to false).

GPU & Video Memory: GPU headful sessions (Start-Up/Enterprise, us-east only, not in pools) take video_memory '2GiB' (default; 4 vCPU, 6 GiB memory) or '4GiB' (8 vCPU, 12 GiB memory). GPU browsers do not support standby.

Unified Concurrency Limits: On-demand and browser-pool concurrency limits are unified in max_concurrent_sessions. The API and CLI report concurrent_sessions_used and concurrent_sessions_available; max_pooled_sessions is @deprecated.

Browser Pools: Pools can be created or updated with memory: '16GiB' (headful only; defaults to '8GiB'; updates apply to newly created browsers). browserPools.acquire supports dynamic profile binding (profile: { name }). Idle pooled browsers suspend automatically (there is no auto_standby parameter); pool capacity still counts against max_concurrent_sessions. Default to on-demand browsers.create; use a pool only for steady or bursty demand. Pools also take egress allowlists (network.allowed_hosts) and network.proxy_routes.

Persistent Browsers EOL: Kernel has end-of-lifed persistent VMs (persistent: true). Use timeout_seconds + Profiles (save_changes: true) for state persistence.

Vaults, 1Password Autofill & MPP Purchases: Pass vaults: [{ id }] to bind project-scoped credential or payment vaults at session creation. Vault links are immutable after session boot. fill writes real values into the page and never submits; page scripts, extensions and an unrestricted agent can read them, so authorize the destination yourself. 1Password 1pw_fill requires page_url on the approved login's origin and locks CDP/WebDriver/API (423) during the fill; live view is not locked. AgentCard uses Luhn-valid alias egress interception (not DOM fill). MPP allows autonomous agents without a Kernel account to buy temporary 30-min browser sessions via HTTP 402 with Stripe Link (link-cli mpp pay). A Managed Auth login() cancels a flow in progress — verify with ensureAuthenticated, do not call it twice. See references/patterns/vaults-and-payments.md.

Kernel MCP server: hosted at https://mcp.onkernel.com/mcp (OAuth 2.1, or Authorization: Bearer <KERNEL_API_KEY>; stdio via npx -y mcp-remote). Configure with kernel mcp install --target cursor|claude|claude-code|antigravity|windsurf|vscode|goose|zed|fx. The source registry lists 34 tool names; a plain connection sees 25, vault tools need the vaults entitlement, web_search needs the Search entitlement, open_auth_login needs an MCP-Apps client. Browser tools accept a live session's name or ID (deleted sessions and pool release need the ID). Do not hard-code a tool count. See references/guides/mcp-server.md.

Bundled scripts

Reference routing

Output contract

When finishing a Kernel task, report only fields that apply:

• operating mode: embed, deploy, or mixed
• package versions checked and package range pinned
• created browser session_id values and whether each was deleted, pool-released, intentionally timed out, or left running with reason
• live view URL or replay/artifact path when relevant
• profile name/id and whether save_changes was used
• Managed Auth connection id, final flow_status/status, and profile name
• deployment id, app name, version, and action name
• invocation id, sync/async mode, terminal status, and how logs/events were consumed
• payload/output size strategy for large artifacts
• verification rung actually reached: typecheck, script run, live browser run, deployment/invocation observed

Verification

End-to-end checks for any Kernel-TS task:

1. The SDK is installed at a pinned version, and every method you call appears in the installed declarations (node_modules/@onkernel/sdk/client.d.ts for resources, node_modules/@onkernel/sdk/resources/**/*.d.ts for signatures) — npx tsc --noEmit passes. The package ships no api.md; do not gate on one.
2. KERNEL_API_KEY resolves at runtime; if the key is org-wide, projectID is passed to the constructor. Confirm with await kernel.auth.context.retrieve() — authorization.credential_scope.project_id === null means the key is org-wide, and authorization.effective_scope.project_id must equal the project you intended.
3. Every browsers.create is paired with a deleteByID in a finally (grep the diff).
4. Long-running invocations use async: true and consume invocations.follow(id) events (log, invocation_state, error, sse_heartbeat).
5. Stagehand/Playwright wiring uses browser.contexts()[0] not newContext().
6. Stealth is on (stealth: true) for anything user-facing or against a real SaaS.
7. For Managed Auth: <KernelManagedAuth /> is a client component ("use client"), the backend route calls auth.connections.create and auth.connections.login, and downstream browsers.create uses the same profile.name.

Cost cleanup check

• List open browsers when SDK/CLI is available; created session_id values must be deleted, released back to a pool, intentionally timed out, or left running with a reason.
• For browser pools, release every acquired browser or explain why it was destroyed/rebuilt.
• For deployments/invocations, report deployment/invocation ids, app/action/version, terminal status, and how logs/events were consumed.
• For large artifacts, report whether they moved through browsers.fs.*, replay download, or object storage before browser cleanup.

Final checks

• KERNEL_API_KEY is read from env, not hardcoded.
• @onkernel/sdk version is pinned.
• Every browsers.create is paired with deleteByID (or wrapped by an invocation that will reap).
• Sync vs async invocation chosen deliberately; the right *_timeout_seconds is set.
• Default-context-only: no browser.newContext() against a Kernel browser.
• Errors are caught with instanceof Kernel.APIError (or specific subclass).
• If Managed Auth is used: backend creates the connection, the React component is "use client", the success handler launches a browser with the matching profile.name.
• If Mode B: package.json has "type": "module" for TS apps; kernel deploy succeeded; the action is registered.
• No leftover browser.close() as the only cleanup.
• Stealth + timeout defaults match the Default stance above unless the task justifies otherwise.

Scope boundaries

This skill covers @onkernel/sdk, @onkernel/managed-auth-react, and the corresponding @onkernel/cli workflows in TypeScript. It does not cover:

• The Python SDK (kernel-python-sdk)
• Terminal-driving the agent-browser CLI (out of scope: follow the CLI's own docs)
• Browser Use's Python framework — there is no native TS package