Skip to content

Commit 5ff388e

Browse files
guergaboguergabo
committed
Trim Docker Sandboxes page to Kernel-unique content
Strip duplicated kit/sbx mechanics (loading methods, spec breakdown, generic troubleshooting, validation commands) and route those to Docker's docs and the kit README. Keeps only what's unique to the Kernel integration: the kit's value prop, proxy-managed KERNEL_API_KEY, and the quickstart command. Reduces drift risk as Docker evolves sbx.
1 parent 9c31d51 commit 5ff388e

1 file changed

Lines changed: 22 additions & 171 deletions

File tree

‎integrations/docker-sandboxes.mdx‎

Lines changed: 22 additions & 171 deletions
Original file line numberDiff line numberDiff line change
@@ -1,193 +1,44 @@
11
---
22
title: "Docker Sandboxes"
3-
description: "Add Kernel tooling and proxy-managed Kernel API auth to Docker Sandboxes via the Kernel kit"
3+
description: "Run agents inside Docker Sandboxes with Kernel tooling and proxy-managed API auth"
44
---
55

6-
[Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) (`sbx`) run AI agents in isolated, throwaway VMs. The [Kernel kit](https://github.com/kernel/docker-sbx-kit) is a [mixin kit](https://docs.docker.com/ai/sandboxes/customize/kits/) that drops Kernel's CLI, agent skills, and proxy-managed API authentication into any Docker sandbox — so an agent inside the sandbox can spin up cloud browsers without ever seeing your real `KERNEL_API_KEY`.
6+
The [Kernel kit](https://github.com/kernel/docker-sbx-kit) is a [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) [mixin](https://docs.docker.com/ai/sandboxes/customize/kits/) that gives any `sbx` agent:
77

8-
## Why use the Kernel kit
8+
- **Kernel CLI** (`@onkernel/cli`) installed at sandbox creation
9+
- **Kernel agent skills** from [`kernel/skills`](https://github.com/kernel/skills), so Claude Code (and any agent that reads `~/.agents/skills`) can drive Kernel without prompting
10+
- **Proxy-managed `KERNEL_API_KEY`** — your real key stays on the host. The `sbx` proxy injects it as `Authorization: Bearer …` on requests to `api.onkernel.com`. The agent inside the sandbox never sees the secret.
911

10-
- **Authenticated without exposure** — your `KERNEL_API_KEY` stays on the host. The `sbx` proxy injects it as a `Bearer` header on requests to `api.onkernel.com`. The agent inside the sandbox cannot read the key.
11-
- **Pre-installed tooling** — the [Kernel CLI](/info/cli) (`@onkernel/cli`) is installed at sandbox creation, so an agent can run `kernel browsers create`, `kernel invoke`, etc. immediately.
12-
- **Pre-installed skills** — every skill from [`kernel/skills`](https://github.com/kernel/skills) is installed for Claude Code (and copied to `~/.agents/skills` for other agent runners). Claude knows how to use Kernel out of the box.
13-
- **Network-locked** — the kit's allow-list grants only the domains needed for `npm`, GitHub, the skills registry, and `api.onkernel.com`.
14-
15-
## Prerequisites
16-
17-
- `sbx` installed and signed in. Follow the [Docker Sandboxes getting started guide](https://docs.docker.com/ai/sandboxes/get-started/).
18-
- A Kernel API key from the [Kernel Dashboard](https://dashboard.onkernel.com/api-keys).
19-
- An Anthropic API key from the [Anthropic Console](https://console.anthropic.com/) if you're using the built-in `claude` agent.
12+
The last point is what makes this integration worth using over `npm install -g @onkernel/cli` inside a custom kit.
2013

2114
## Quickstart
2215

23-
<Steps>
24-
<Step title="Clone the kit">
25-
```bash
26-
git clone https://github.com/kernel/docker-sbx-kit.git
27-
cd docker-sbx-kit
28-
```
29-
30-
You can also load it directly from Git without cloning — see [Loading the kit](#loading-the-kit) below.
31-
</Step>
32-
<Step title="Export your keys on the host">
33-
```bash
34-
export KERNEL_API_KEY=sk-kernel-...
35-
export ANTHROPIC_API_KEY=sk-ant-...
36-
```
37-
38-
The real `KERNEL_API_KEY` stays on the host. The kit declares it as a `proxyManaged` credential, so the sandbox sees a sentinel value — the proxy substitutes the real key on outbound requests.
39-
</Step>
40-
<Step title="Launch Claude with the Kernel kit">
41-
```bash
42-
sbx run --name kernel-demo --kit . claude -- \
43-
"Using the Kernel CLI, create a browser and navigate to news.ycombinator.com. Tell me the top five articles."
44-
```
45-
46-
Claude calls the Kernel CLI inside the sandbox, the CLI talks to `api.onkernel.com`, the `sbx` proxy attaches `Authorization: Bearer $KERNEL_API_KEY`, and the request lands on Kernel's API authenticated as you.
47-
</Step>
48-
</Steps>
49-
50-
## Loading the kit
51-
52-
The kit can be loaded from a local path, a Git ref, or an OCI registry. All three forms work with `sbx run` and `sbx create`:
53-
54-
```bash
55-
# Local path
56-
sbx run --kit ./docker-sbx-kit claude
57-
58-
# Git ref
59-
sbx run --kit "git+https://github.com/kernel/docker-sbx-kit.git" claude
60-
61-
# Stack with other kits
62-
sbx run --kit ./docker-sbx-kit --kit ./your-other-kit claude
63-
```
64-
65-
<Note>
66-
`--kit` only takes effect when the sandbox is created. To add the kit to a running sandbox, use `sbx kit add` instead.
67-
</Note>
68-
69-
## What the kit installs
70-
71-
The kit is a `mixin` — it layers on top of an existing agent (the built-in `claude` agent in the examples above, but any agent works). Its [`spec.yaml`](https://github.com/kernel/docker-sbx-kit/blob/main/spec.yaml) declares:
72-
73-
### Install commands
74-
75-
```yaml
76-
commands:
77-
install:
78-
- command: "npm install -g @onkernel/cli"
79-
description: Install Kernel tooling
80-
- command: "npx -y skills add kernel/skills --skill '*' --agent claude-code --global --copy --yes && cp -a \"$HOME/.claude/skills\" \"$HOME/.agents/skills\""
81-
user: "1000"
82-
description: Install Kernel skills for Claude Code
83-
```
84-
85-
The first command installs the [Kernel CLI](/info/cli) globally. The second installs every skill from [`kernel/skills`](https://github.com/kernel/skills) into `~/.claude/skills` for Claude Code, then copies them to `~/.agents/skills` so other agent runners (Codex, Cursor, custom loops) can find them at the standard skills path.
86-
87-
### Network allow-list
88-
89-
```yaml
90-
network:
91-
allowedDomains:
92-
- "registry.npmjs.org:443"
93-
- "github.com:443"
94-
- "api.github.com:443"
95-
- "raw.githubusercontent.com:443"
96-
- "release-assets.githubusercontent.com:443"
97-
- "add-skill.vercel.sh:443"
98-
- "skills.sh:443"
99-
- "api.onkernel.com:443"
100-
```
101-
102-
If your agent needs to reach additional domains (your own API, a customer site, a CDN), stack a second mixin with the extra `allowedDomains` rather than forking this kit.
103-
104-
### Proxy-managed credential
105-
106-
```yaml
107-
credentials:
108-
sources:
109-
kernel:
110-
env:
111-
- KERNEL_API_KEY
112-
113-
network:
114-
serviceDomains:
115-
api.onkernel.com: kernel
116-
serviceAuth:
117-
kernel:
118-
headerName: Authorization
119-
valueFormat: "Bearer %s"
120-
121-
environment:
122-
proxyManaged:
123-
- KERNEL_API_KEY
124-
```
125-
126-
The `KERNEL_API_KEY` is bound to the `kernel` credential source on the host. The `serviceDomains` map routes outbound traffic to `api.onkernel.com` through that source. The `serviceAuth` rule formats the header. `proxyManaged` ensures the sandbox-side env var is a sentinel — the agent can read it, but it isn't the real secret.
127-
128-
## Using a different agent
129-
130-
The Kernel kit is a mixin, so it works with any `sbx` agent — not just `claude`. Replace the agent name in `sbx run`:
131-
132-
```bash
133-
# Built-in Claude agent
134-
sbx run --kit . claude
135-
136-
# Your own agent kit
137-
sbx run --kit . --kit ./my-agent-kit my-agent
138-
```
139-
140-
See [Docker's kit reference](https://docs.docker.com/ai/sandboxes/customize/kits/) for building agent kits.
141-
142-
## Validating the kit
143-
144-
Before running, you can validate the kit and inspect its metadata:
145-
146-
```bash
147-
sbx kit validate ./docker-sbx-kit
148-
sbx kit inspect ./docker-sbx-kit
149-
```
150-
151-
The repo also includes a [smoke script](https://github.com/kernel/docker-sbx-kit/blob/main/scripts/smoke.sh) that creates a sandbox, checks that the CLI and skills are present, and verifies that Kernel API requests succeed through the proxy:
152-
15316
```bash
154-
KERNEL_API_KEY=sk-kernel-... ./scripts/smoke.sh --create
155-
```
156-
157-
## Troubleshooting
17+
export KERNEL_API_KEY=sk-kernel-...
18+
export ANTHROPIC_API_KEY=sk-ant-...
15819

159-
### Sandbox can't reach `api.onkernel.com`
160-
161-
Check the proxy log to see how outbound requests are being matched:
162-
163-
```bash
164-
sbx policy log | grep api.onkernel.com
20+
sbx run --name kernel-demo \
21+
--kit "git+https://github.com/kernel/docker-sbx-kit.git" \
22+
claude -- \
23+
"Using the Kernel CLI, create a browser and navigate to news.ycombinator.com. Tell me the top five articles."
16524
```
16625

167-
If requests aren't matching the `kernel` service, confirm `KERNEL_API_KEY` is exported in the host shell that ran `sbx run` or `sbx create`. The `sbx` proxy reads the credential from the host environment at the time of the API call.
26+
Claude calls `kernel` inside the sandbox → CLI hits `api.onkernel.com` → the `sbx` proxy attaches your `KERNEL_API_KEY` → the request authenticates as you.
16827

169-
### `kernel` command not found inside the sandbox
28+
The kit's full `spec.yaml`, install commands, and allowed domains live in the [repo README](https://github.com/kernel/docker-sbx-kit#readme).
17029

171-
Install commands only run during `sbx run` or `sbx create` — not on subsequent `sbx exec` calls. Confirm install succeeded by recreating the sandbox and watching the install output:
172-
173-
```bash
174-
sbx rm --force kernel-demo
175-
sbx run --name kernel-demo --kit ./docker-sbx-kit claude
176-
```
177-
178-
### Authentication errors from Kernel API
30+
## Prerequisites
17931

180-
Verify your host-side key works directly:
32+
- `sbx` installed and signed in — see [Docker's getting started guide](https://docs.docker.com/ai/sandboxes/get-started/)
33+
- A Kernel API key from the [Kernel Dashboard](https://dashboard.onkernel.com/api-keys)
34+
- An Anthropic API key from the [Anthropic Console](https://console.anthropic.com/) if you're using the built-in `claude` agent
18135

182-
```bash
183-
curl -H "Authorization: Bearer $KERNEL_API_KEY" https://api.onkernel.com/browsers
184-
```
36+
## Customizing or extending
18537

186-
If that fails, generate a new key in the [Kernel Dashboard](https://dashboard.onkernel.com/api-keys).
38+
For everything not specific to Kernel — loading kits from local paths or OCI registries, stacking multiple mixins, building your own agent kit, debugging the proxy, `sbx kit add` for running sandboxes — see [Docker's kit reference](https://docs.docker.com/ai/sandboxes/customize/kits/). The Kernel kit is a standard mixin and composes with anything else you put on top.
18739

18840
## Next steps
18941

190-
- Browse the [Kernel skills repo](https://github.com/kernel/skills) to see what Claude can do out of the box
42+
- Browse [`kernel/skills`](https://github.com/kernel/skills) to see what Claude can do out of the box
19143
- Read the [Kernel CLI reference](/info/cli) for commands available inside the sandbox
192-
- Learn about [browser creation](/browsers/create-a-browser) for what the agent can build with Kernel
193-
- Explore [stealth mode](/browsers/bot-detection/stealth) and [Profiles](/auth/profiles) for harder automation targets
44+
- Learn about [browser creation](/browsers/create-a-browser), [stealth mode](/browsers/bot-detection/stealth), and [Profiles](/auth/profiles) for harder automation targets

0 commit comments

Comments
 (0)