Build Kernel Ts Sdk

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 `` 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](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](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](references/patterns/profiles-pools-credentials.md) and [references/guides/managed-auth.md](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](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](references/guides/apps-deploy-invoke.md) and [references/examples/deploy-and-invoke-app.md](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](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](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](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](references/guides/managed-auth.md) | 3-piece architecture, auth.connections.*, ` props, profile interop | Authenticating an agent on a user's behalf into a SaaS | | [references/patterns/browser-control-surfaces.md](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](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](references/patterns/profiles-pools-credentials.md) | profiles., browserPools., credentials., credentialProviders. (1Password) | Persistent login state, pool warm-starts, credential providers | | [references/patterns/integrations-matrix.md](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](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](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](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](references/troubleshooting/pitfalls.md) | The 16 production gotchas in priority order | Debugging unexpected behavior or before shipping | | [references/troubleshooting/files-and-replays.md](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](references/troubleshooting/auth-and-profil

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yigitkonur
• Source: yigitkonur/skills-by-yigitkonur
• License: MIT

Install and usage instructions live in the source repository linked above.