SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsbuild-kernel-ts-sdk

build-kernel-ts-sdk

Agents & models

View repository

Updated 10-16 04:39

About this skill

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, 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
  • 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
  • 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.* / repl / webmcp.* / process.*
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, version, 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; invocations.create requires app_name, action_name, and version (all three are non-optional). 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 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 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 supported in SDK and CLI. With an org-wide API key, scope to a project by passing new Kernel({ projectID: '…' }) — the SDK stamps X-Kernel-Project-Id on every request and withOptions() carries it. A companion project option sets X-Kernel-Project. Both default to null and the SDK reads no project env var, so pass it explicitly (e.g. projectID: process.env.KERNEL_PROJECT). Hand-wiring defaultHeaders still works but is the escape hatch, not the idiom. In the CLI, project scope is passed via --project <project_id_or_name> (or export KERNEL_PROJECT=<project_id_or_name>), and project-scoped API keys can be provisioned with kernel api-keys create --name <name> --project-id <project_id>.
  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 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.
  • 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.

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: 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 — 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

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). 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

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
version, async: true, async_timeout_seconds: 1800 + invocations.follow omit the required version, or 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
Pass projectID: '…' to the Kernel constructor to scope an org-wide key hand-roll defaultHeaders for project scoping, or 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 v4 attaches over CDP; new Stagehand(...) is gone. The constructor is private — use Stagehand.create(), and pass a browser (it is required). Mirror the Stagehand extension onto the Kernel browser's filesystem first (browsers.fs.uploadZip), 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.

proxy_id is deprecated on browsers.create. 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' }.

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). App deployments support 'aws.us-east-1a' with multi-host routing.

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

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 Extended Memory & Dynamic Profile Binding: Pools can be created or updated with memory: '16GiB' (defaults to '8GiB'). browserPools.acquire supports dynamic profile binding (profile: { name }). Idle pool instances use auto-standby.

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. Paced autofill injects credentials into the DOM at human typing speed without exposing secrets. Supports 1Password Agentic Autofill (1pw_* operations), Stripe Link, AgentCard (checkout_origin), and autonomous MPP browser purchases via HTTP 402.

Bundled scripts

Script Use
scripts/check-kernel-sdk-version.sh Preflight Node/npm, installed Kernel package versions, npm latest versions, the installed SDK type declarations, 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/cli-reference.md Full @onkernel/cli reference across all 16 command groups and flags Running CLI commands, debugging shell automation, checking CLI equivalents
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/guides/telemetry.md Categories (operational vs opt-in), SSE stream, historical events query, OTLP destinations Streaming live session events or exporting to OpenTelemetry
references/patterns/browser-control-surfaces.md Decision tree across CDP, playwright.execute, computer.*, repl, webmcp.*, process.* Picking the right control surface for a task
references/patterns/vaults-and-payments.md Vaults, credentials, 1Password Agentic Autofill, Link, AgentCard, MPP browser purchases Managing credentials, cards, paced autofill, or agent payments
references/patterns/playwright-stagehand-integration.md connectOverCDP idiom, default-context warning, Stagehand connect/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, 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 (use run-agent-browser)
  • Browser Use's Python framework — there is no native TS package