Customize your sandbox with kits

A Docker Sandbox starts from a fixed setup: an agent, the tools that come with it, and network rules for the places that agent needs to reach. Sooner or later your project needs something that setup didn’t include: a tool the agent should use, a service it should reach, or a different agent altogether.

You could open a shell in the sandbox and install things by hand. That works until you remove the sandbox, and then it’s gone. It also does nothing for the network policy, so the new tool may not be able to reach what it needs.

Kits solve this. In this guide, you’ll add a published kit that gives the agent a real browser to test your app with. Then you’ll swap Claude Code for Codex and watch the browser come along. This guide covers using kits that others have published, not writing your own.

Before you start

You can follow this whole guide in your browser. The terminals on this page are simulations: click through them to see what each command does.

To run it for real on your own machine, you need:

The sbx CLI, installed and signed in. Follow Install Docker Sandboxes, then run sbx login.
A way for Claude Code to reach its model: a Claude subscription, or an Anthropic API key stored with sbx secret set anthropic.
A project to work on. This guide calls it ~/my-app. A web app with a dev server shows off the browser best.
Optionally, an OpenAI account, to try swapping in Codex.

New to sandboxes? Run your first AI agent in a Docker Sandbox covers the basics this guide builds on.

What a kit is

Every sandbox is built from kits. When you run sbx run sbx/claude, sbx/claude is a kit: it installs Claude Code in the sandbox, adds Anthropic’s domains to the network policy, and tells the network proxy which credential to inject when Claude Code talks to Anthropic.

A kit is a container image with a small descriptor file inside, published to a registry like any other image. The descriptor declares what the kit needs:

Files and tools to install in the sandbox, such as an agent or a browser
Network rules that add the domains it needs to the sandbox’s network policy
Credential requests: which of your stored credentials the network proxy may inject, and for which domains. Never the credential itself
Context for the agent on how to use what the kit installed

Because one kit carries all of these, adding a tool and letting it work are the same step.

Workloads and mixins

A sandbox is built from kits in two roles:

A workload is the base of the sandbox, and decides what runs when you start it. sbx/claude is a workload: it builds the whole environment and starts Claude Code. You pass the workload as the first argument to sbx run.
A mixin adds something on top: a tool, network rules, or context. You add one with --kit, and you can add as many as you like.

There’s exactly one workload per sandbox, and that’s where the agent comes from. Mixins don’t care which workload they sit on, which is what makes swapping the agent easy later.

Try it. Pick a workload, add the Playwright mixin, and watch where each part lands.

Each kit adds to the microVM, the network policy, and the credentials the network proxy may inject:

Kit	In the microVM	Allowed by the network policy	Credentials injected
Claude Code (workload)	Claude Code, notes in `CLAUDE.md`	Anthropic’s API and sign-in sites	`anthropic`
Codex (workload)	Codex, notes in `AGENTS.md`	OpenAI’s API and sign-in sites, npm, GitHub	`openai`
Playwright (mixin)	Playwright, Chromium, and notes	Playwright’s browser download sites	None

Switch the workload from Claude Code to Codex and the agent’s row changes completely. The Playwright row stays exactly as it was, and its notes land in whichever file the new agent reads.

The tables leave out the Ubuntu and Docker package mirrors that each kit also lists, so it can install system packages when the sandbox is created.

Notice the Playwright kit asks for no credential at all. It doesn’t sign in to anything. It brings a tool, the few domains that tool needs, and context for the agent: that Chromium is already installed, that it runs headless, and that sites the network policy doesn’t allow will fail. A kit only declares what its tool actually needs.

Know what a kit asks for

A kit from someone else can add domains to the network policy and ask to use your credentials. So before you run one, it’s worth knowing what’s in it. Three things keep you in charge:

You approve every credential. The first time a kit asks to use one of your stored credentials, sbx stops and asks you, listing the sites the kit wants it sent to. Storing a secret doesn’t give any kit permission to use it. Your answer is saved in ~/.config/sbx/credentials.yaml, so you only answer once.
A kit can’t overrule your policy. A kit’s network rules can add domains for its own sandbox, but never beyond what your organization’s policy allows.
You can look first. sbx kit inspect <reference> shows a kit’s details before you run it.

This guide uses kits published by Docker under sbx/ on Docker Hub. Treat kits from anywhere else the way you’d treat any software you install: check who published it, and read what it asks for.

Add a kit to your sandbox

A sandbox’s kits are chosen when it’s created, so you can’t add one to a sandbox you already have. Create a new one with the sbx/claude workload plus the Playwright mixin. From your project directory, run:

Host machine (~/my-app)

sbx run sbx/claude --name claude-playwright --kit sbx/playwright

Pulling kit sbx/claude...
Pulling kit sbx/playwright...
Creating sandbox claude-playwright for the current workspace...
Starting Claude Code in sandbox claude-playwright...

Is a browser available? Check, and tell me in one sentence.

Yes: Playwright 1.61.1 is installed globally with a headless Chromium in /opt/ms-playwright, so I can run browser tests here.

Reading the command piece by piece:

sbx/claude is the workload: Claude Code.
--name claude-playwright names the new sandbox, so it doesn’t collide with any sandbox you already have.
--kit sbx/playwright adds the mixin. Repeat --kit to add more.
Your current directory is shared into the sandbox as its workspace.

The first time, sbx pulls both kits and installs the libraries Chromium needs, so creation takes a little longer. Claude Code then starts as usual. It knows about the browser without being told, because the Playwright kit added context to the file Claude Code reads.

Now give it real work. If your app has a dev server, ask something like:

Start the dev server, then write a Playwright test that loads the home page and checks the title. Run it and show me the result.

The agent writes a test into your project, runs it against the server on localhost inside the sandbox, and reports back. The test file lands in ~/my-app, where you can review and keep it.

When you’re done, type /exit to leave Claude Code.

Swap the agent

The agent comes from the workload, so swapping agents means swapping that one kit. Keep the same --kit.

First, give Codex a way to sign in. If you use ChatGPT to sign in to Codex:

$ sbx secret set openai --oauth

Or, to use an API key, run sbx secret set openai and paste the key when prompted. Then run the same command as before with the Codex workload and a new name:

Host machine (~/my-app)

sbx run sbx/codex --name codex-playwright --kit sbx/playwright

Pulling kit sbx/codex...
Creating sandbox codex-playwright for the current workspace...
Starting Codex in sandbox codex-playwright...

Is a browser available? Check, and tell me in one sentence.

Yes: Playwright 1.61.1 and a headless Chromium are installed, so I can run the browser test in this project.

If sbx asks you to approve the Codex kit’s use of your openai credential, check the sites it lists and approve them.

The agent changed, and the browser came along. The Playwright kit doesn’t care which agent it sits next to. Its context now lands in AGENTS.md, the file Codex reads, instead of CLAUDE.md. Behind the scenes, Anthropic’s domains left the network policy and OpenAI’s joined it, because those rules belong to the workload.

If you had Claude Code write a test earlier, ask Codex to run it. It’s in your project, so it’s already there.

That’s the payoff of kits. Your tools and their rules stay put while the agent changes. Docker publishes workloads for other agents too, such as sbx/opencode, sbx/copilot, and sbx/cursor. Images whose names end in -kit, such as sbx/claude-kit, use the older format, so don’t mix them with these.

Type /exit to leave Codex.

Clean up

Each combination you tried is its own sandbox. Remove both from your host:

Host machine

sbx rm claude-playwright codex-playwright

Removed claude-playwright
Removed codex-playwright

Removing a sandbox discards everything inside it. Your project files in ~/my-app, including any tests the agents wrote, stay as they are.

Check yourself

You add the Playwright kit. It changes the microVM and the network policy: Playwright, Chromium, and context go in, and the browser download sites are allowed. It asks for no credential.
You swap the workload from Claude Code to Codex. All three change: a different agent, OpenAI’s domains instead of Anthropic’s, and the openai credential instead of anthropic.
You add a kit of team notes. Only the microVM changes. The notes go in for the agent to read.
You add a --kit when reopening an existing sandbox. Nothing changes. A sandbox keeps the kits it was created with.

In short

A kit bundles what one kind of work needs: files and tools for the microVM, network rules, and requests for the credentials it needs, and no others.
The workload is the base of the sandbox and brings the agent. Mixins add to it with --kit.
You approve every credential a kit asks for, and its rules can’t go past your policy.
Kits are fixed when a sandbox is created. To try a new combination, make a new sandbox.
Swapping the agent is swapping the workload, and your mixins come along.

That sbx run command is getting long, and typing it again tomorrow, or explaining it to a teammate, isn’t much fun. Next, define and share your sandbox environment in a file, so one short command rebuilds the same sandbox every time.