|
| 1 | +--- |
| 2 | +title: "Docker Sandboxes" |
| 3 | +description: "Add Kernel tooling and proxy-managed Kernel API auth to Docker Sandboxes via the Kernel kit" |
| 4 | +--- |
| 5 | + |
| 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`. |
| 7 | + |
| 8 | +## Why use the Kernel kit |
| 9 | + |
| 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. |
| 20 | + |
| 21 | +## Quickstart |
| 22 | + |
| 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 | + |
| 153 | +```bash |
| 154 | +KERNEL_API_KEY=sk-kernel-... ./scripts/smoke.sh --create |
| 155 | +``` |
| 156 | + |
| 157 | +## Troubleshooting |
| 158 | + |
| 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 |
| 165 | +``` |
| 166 | + |
| 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. |
| 168 | + |
| 169 | +### `kernel` command not found inside the sandbox |
| 170 | + |
| 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 |
| 179 | + |
| 180 | +Verify your host-side key works directly: |
| 181 | + |
| 182 | +```bash |
| 183 | +curl -H "Authorization: Bearer $KERNEL_API_KEY" https://api.onkernel.com/browsers |
| 184 | +``` |
| 185 | + |
| 186 | +If that fails, generate a new key in the [Kernel Dashboard](https://dashboard.onkernel.com/api-keys). |
| 187 | + |
| 188 | +## Next steps |
| 189 | + |
| 190 | +- Browse the [Kernel skills repo](https://github.com/kernel/skills) to see what Claude can do out of the box |
| 191 | +- 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 |
0 commit comments