sbx/kernel-kit repository overview

⁠Kernel Browser

A mixin kit (kind: mixin) that gives any Docker Sandbox agent access to Kernel⁠ cloud browsers. The kit installs the Kernel CLI, adds an agent quick-reference guide, and routes API authentication through the sandbox proxy so the real credential never enters the sandbox.

⁠Prerequisites

Create a Kernel⁠ account and store its API key once in Docker Sandboxes' host-side secret store:

sbx secret set kernel

⁠Usage

The primary form is the published OCI artifact on Docker Hub:

sbx run --kit "docker.io/sbx/kernel-kit:latest" claude

Or target this repo directly over git:

sbx run --kit "git+https://github.com/docker/sbx-kits-contrib.git#dir=kernel" claude

Or use a local clone:

sbx run --kit ./kernel/ claude

Mix it with another kit by repeating --kit:

sbx run --kit ./kernel/ --kit ./ruff-lint/ claude

The kit works with any agent that ships npm. It installs the kernel CLI globally so the agent can run kernel browsers create, kernel browsers list, and so on directly from the terminal.

A quick-reference guide is dropped at /home/agent/.kernel/quickstart.md on every sandbox start.

⁠Adding the SDK to your project

The kit installs the CLI but not the SDK — that belongs in your project's package.json or requirements.txt:

TypeScript / JavaScript:

npm install @onkernel/sdk playwright-core

Use playwright-core (not playwright): it provides connectOverCDP without downloading local Chromium binaries that you won't use.

Python:

PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 pip install kernel playwright

⁠How auth works

The kit declares two things:

• credentials[].apiKey.inject maps api.onkernel.com to the kernel credential, telling the proxy to inject Authorization: Bearer <key> on outbound requests to that host.
• permissions.network.allow uses *.onkernel.com to also permit CDP WebSocket proxy URLs (wss://proxy.<region>.onkernel.com:8443/...), which don't get auth injection.

The inject domain is intentionally narrow (just the REST API host). A wildcard there would put the proxy into TLS-intercept mode for all *.onkernel.com traffic — including the CDP WebSocket connections that carry browser data — which would corrupt them.

KERNEL_API_KEY is declared with apiKey.proxyManaged: true: the sandbox holds a placeholder value; the proxy substitutes the real credential at request time. The real key comes from the host secret stored under the kernel service name.

⁠What gets installed

⁠Cleanup

The kit creates no persistent host-side state. Browser sessions created inside the sandbox are scoped to your Kernel organization and can be deleted from the Kernel dashboard⁠ or with kernel browsers delete <id>.