build-kernel-ts-sdk

name	build-kernel-ts-sdk
description	Use if building browser-automation apps on the Kernel TS SDK (@onkernel/sdk) — browsers, pools.

Build Kernel TS SDK

Build with the Kernel TypeScript SDK (@onkernel/sdk, generated from Kernel's OpenAPI spec by Stainless) and the React helper @onkernel/managed-auth-react. 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, or kernel.browsers.computer.*
• 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
• using profiles (profiles.*), browser pools (browserPools.*), credentials (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 per project via defaultHeaders: { 'X-Kernel-Project-Id': '…' }
• 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) — use run-agent-browser. This skill owns Kernel-SDK code; run-agent-browser owns 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 (build-langchain-ts-app).

Cross-skill disambiguation

Situation	Use
TypeScript code importing @onkernel/sdk or deploying a Kernel App	build-kernel-ts-sdk
agent-browser CLI loops, including agent-browser -p kernel	run-agent-browser
LangChain.js/LangGraph agent where browser tools are optional	build-langchain-ts-app

Two operating modes — decide first

Mode	When	Code lives	Invocation
A. Embed	Drive Kernel from your own service (Next.js route, worker, CLI tool)	Your repo	new Kernel() → browsers.create → CDP / playwright.execute / computer.*
B. Deploy	Long-running, browser-co-located actions; want zero CDP latency or per-invocation isolation	A Kernel App (your repo, deployed via kernel deploy)	Register actions → kernel deploy → kernel.invocations.create({ app_name, action_name, payload })

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; track invocation.id, sync/async mode, status, logs/events, and output handling.

Hard rules — load-bearing

1. KERNEL_API_KEY from env. Never hardcode. Env wins over apiKey: option only when the option is omitted; passing both is allowed.
2. Pin the SDK. @onkernel/sdk is auto-generated by Stainless and rev's frequently. Pin a minor version range; verify method names from the installed node_modules/@onkernel/sdk/api.md if unsure.
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 cap is ~100 s. Anything longer must use async: true with async_timeout_seconds (10–3600) and invocations.follow(id) for SSE. Switching after the fact requires re-deploying.
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 header-driven. With an org-wide API key, scope to a project by passing defaultHeaders: { 'X-Kernel-Project-Id': '…' } to the constructor. The SDK does NOT auto-read KERNEL_PROJECT — wire it through. OAuth (CLI) is always org-wide.
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 limits are doc-conflicted. App development and CLI docs say 64 KB; app invocation docs say 4.5 MB. Verify live docs before relying on large payloads; route multi-MB artifacts through browsers.fs.* or object storage.

Default stance

• stealth: true for any non-trivial site — bot detection is the rule, not the exception.
• timeout_seconds: 300 minimum; the 60 s default is too aggressive for real automation. Max is 259200 (72 h).
• 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.
• 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 connected browser is "active". After 5 s with no CDP/live-view connection it enters standby (zero compute cost) and only THEN does its timeout_seconds countdown to deletion start.

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
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: read node_modules/@onkernel/sdk/api.md when present — Stainless regenerates frequently and method names move.
• 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

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.

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 are optional). For local dev hitting https://localhost:3001/, pass environment: 'development', baseURL: null. For project-scoped API keys, wire X-Kernel-Project-Id through defaultHeaders. See references/guides/client-and-config.md.
3. Pick the browser-control surface — raw CDP / Playwright-inside-VM / computer-controls / browser-curl. See references/patterns/browser-control-surfaces.md.
4. Wire profiles or Managed Auth if the agent needs persistent login. 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

Do this	Not that
await kernel.browsers.deleteByID(session.session_id) in a finally	await browser.close() and assume the browser is gone
chromium.connectOverCDP(session.cdp_ws_url) then browser.contexts()[0]	browser.newContext() to "isolate" the test
kernel.browsers.playwright.execute(id, { code: '…' }) for hot paths	round-trip every call over CDP from your service
async: true, async_timeout_seconds: 1800 + invocations.follow	depend on the sync invocation cap holding for a multi-minute scrape
JSON.stringify(payload) and JSON.parse(invocation.output ?? 'null')	pass non-JSON-serializable objects to payload
try { ... } catch (e) { if (e instanceof Kernel.APIError) … }	swallow errors or catch (e: any) without checking subclasses
browsers.create({ profile: { name } }) after Managed Auth completes	re-prompt the user every session
Pin @onkernel/sdk to a minor range and bump deliberately	track latest (Stainless regenerates frequently)
kernel.browsers.curl(id, { url }) for HTTP from inside the browser's TLS fingerprint	spin up a separate Playwright request context and lose the fingerprint
Wire defaultHeaders: { 'X-Kernel-Project-Id': '…' } for project-scoped API keys	rely on key scope and get cross-project lists

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. Switching after the fact requires re-deploying.

Stagehand connects via local-CDP, not Browserbase. With @browserbasehq/stagehand and Kernel, set env: 'LOCAL' and localBrowserLaunchOptions.cdpUrl: session.cdp_ws_url. Do not set apiKey or projectId — those are Browserbase-only.

browsers.delete (singular) is deprecated. Use browsers.deleteByID(id). The plural form takes a persistent_id and belongs to the deprecated persistence model.

Bundled scripts

Script	Use
scripts/check-kernel-sdk-version.sh	Preflight Node/npm, installed Kernel package versions, npm latest versions, local api.md, and KERNEL_API_KEY presence. See scripts/check-kernel-sdk-version.sh.md.
scripts/scaffold-kernel-app.sh	Generate a minimal embedded SDK example or deployable Kernel App in an empty directory. See scripts/scaffold-kernel-app.sh.md.

Reference routing

Document	What it contains	Load when
references/guides/client-and-config.md	Env vars, environments, retries, idempotency, pagination, error taxonomy, request options	Constructing the client, debugging auth/network errors, handling pagination
references/guides/browsers-lifecycle.md	browsers.create params, BrowserCreateResponse, standby, termination, viewport, timeout semantics	Creating, configuring, or terminating browsers
references/guides/apps-deploy-invoke.md	deployments.*, invocations.create sync vs async, invocations.follow SSE, secrets, logs	Deploying a Kernel App or invoking it from another service
references/guides/managed-auth.md	3-piece architecture, auth.connections.*, <KernelManagedAuth /> props, profile interop	Authenticating an agent on a user's behalf into a SaaS
references/patterns/browser-control-surfaces.md	Decision tree across CDP, playwright.execute, computer.*, curl	Picking the right control surface for a task
references/patterns/playwright-stagehand-integration.md	connectOverCDP idiom, default-context warning, Stagehand v3 launch options, kernel create --template	Wiring Playwright or Stagehand to a Kernel browser
references/patterns/profiles-pools-credentials.md	profiles.*, browserPools.*, credentials.*, credentialProviders.* (1Password)	Persistent login state, pool warm-starts, credential providers
references/patterns/integrations-matrix.md	Hookup snippets per integration (Stagehand, Browser Use, Claude Agent SDK, Vibium, etc.)	Connecting a third-party agent framework to a Kernel browser
references/examples/browser-screenshot.md	Minimal end-to-end TS example	Sanity-check first run; copy as a starting scaffold
references/examples/deploy-and-invoke-app.md	kernel deploy + invocations.create + invocations.follow walkthrough	Building or invoking a Kernel App
references/examples/managed-auth-flow.md	Full Next.js page + backend route + browser launch	Implementing the Managed Auth handoff end-to-end
references/troubleshooting/pitfalls.md	The 16 production gotchas in priority order	Debugging unexpected behavior or before shipping
references/troubleshooting/files-and-replays.md	browsers.fs.*, browsers.replays.*, download timing, multipart	File I/O or replay download is failing or slow
references/troubleshooting/auth-and-profile-errors.md	409 conflict, profile not found, hosted-page handoff failures	Managed Auth or profile errors

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; node_modules/@onkernel/sdk/api.md exists and matches the methods you call.
2. KERNEL_API_KEY resolves at runtime; if the key is org-wide, defaultHeaders: { 'X-Kernel-Project-Id': '…' } is wired through the constructor.
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 and @onkernel/managed-auth-react in TypeScript. It does not cover:

• The Python SDK (kernel-python-sdk)
• Terminal-driving the agent-browser CLI (use run-agent-browser)
• The full kernel CLI surface beyond deploy and invoke (read kernel --help directly)
• Browser Use's Python framework — there is no native TS package