Sign inSign up

sbx/claude-mixin

Verified Publisher

By Docker, Inc

•Updated about 9 hours ago

Anthropic's Claude Code as a mixin — the native install in an overlay, with the `anthropic` cre...

Sandbox Kit
0

10K+

sbx/claude-mixin repository overview

Digest

sha256:f1ab6d1a0850…

Size

130.5 MB

Schema

v3

Pushed

about 9 hours ago

Specificationspec.yaml
MIXIN

The Claude Code CLI as a mixin — the native binary in an overlay, with the Anthropic credential (API key or claude.ai OAuth) and the hooks the agent needs. Layer it onto a shell base and run `claude`; compose claude-sessions to keep session state on the host.

Arguments
NameRequiredDefaultDescription
modelOptional

Claude model to use (settings.json `model`); empty keeps the CLI default

reasoningEffortOptional

Effort level (settings.json `effortLevel`); empty keeps the CLI default

Options: , low, medium, high, xhigh, max, auto
versionRequired—

Claude Code release the overlay carries

Provides[email protected]
CapabilitiesExpand a row to see its full configuration. See the full spec for the complete descriptor.
TypeRequiredDescription
com.docker.sandbox/network-policy@1Required—
com.docker.sandbox/credential@1OptionalAnthropic API access (API key or claude.ai OAuth)
com.docker.sandbox/lifecycle@1Required—
com.docker.sandbox/agent-skills@1Optional—
com.docker.sandbox/agent-context@1Optional—
com.docker.sandbox/agent-context@2Optional—

Apply this mixin to a sandbox

sbx run <agent> --kit sbx/claude-mixin:latest

Make sure you have docker sbx installed

Run the following command to install sbx on your machine.

macOS
brew install docker/tap/sbx
Windows
winget install Docker.sbx
Learn more about docker sbx⁠

Note

Experimental: Sandbox Kit v3

This kit uses the experimental Sandbox Kit specification⁠, specifically v3⁠. The format and runtime behavior may change before v3 is stable.

⁠claude-mixin

Claude Code⁠ as a mixin (kind: mixin, schemaVersion: "3") — the same agent the claude⁠ workload kit (now a Docker Hardened Image) ships, packaged as an overlay you layer onto a shell base instead of booting as the whole environment.

Use this one when the sandbox already has a workload you want to keep (a shell, a language toolchain, another team's base image) and you want claude in it. Use claude⁠ when Claude Code is the environment.

⁠Composing it

sbx run --kit ./claude-mixin/ <base-agent>

The two are mutually exclusive: both provides: ["claude"], and a composition with two providers of one name is refused — the workload already carries the agent this mixin installs.

⁠What it carries

Everything the workload declares that belongs to the agent rather than to the environment:

  • the anthropic credential, covering both a console API key and a Claude subscription, with the same deliberate omission of proxyManaged (see below⁠);
  • the same egress allow-list, including the apt hosts the background apt-get update needs;
  • the same five ~/.claude/ session-state volumes;
  • the same install and startup hooks — trust flags, settings.json seeded from the surfaced auth mode, MCP gateway registration;
  • a body for the composed CLAUDE.md.

The install itself is the unmodified upstream one, run over the workload's base in a build stage and staged into a scratch overlay. Anthropic's installer is not relocatable and the install method is what claude update drives, so the mixin keeps it rather than swapping in a --prefix build.

⁠Why the API key is not proxyManaged

This is the one deviation from the pattern every other apiKey credential in this repo follows, and it is load-bearing rather than an oversight carried forward.

With proxyManaged: true the engine sets ANTHROPIC_API_KEY to the literal proxy-managed inside the container. Claude Code resolves auth in a fixed order in which an ANTHROPIC_API_KEY in the environment outranks the OAuth credentials file — so that sentinel would shadow a bound Claude subscription on every sandbox, and the session would try to authenticate as a console API key that may not exist.

Without it, the variable is simply not populated, and the sentinel Claude Code is meant to send arrives by a different route: a lifecycle install hook writes "apiKeyHelper": "echo proxy-managed" into ~/.claude/settings.json when the bound credential is an API key, and the credential's inject rules swap the real value in at request time. The container never holds a usable key either way.

⁠What it deliberately leaves to the base workload

Left outWhy
ENTRYPOINTThe base's launch command stays; you run claude from the shell.
sbx@1A mixin's image config is not the composed image's, so the identity and shells that type is a claim about are the base's.
agent-context filename:CLAUDE.md names the profile, which belongs to the workload. This kit contributes a body to it.
agent-sessions@1The session verbs are argv tails on a launch command this kit does not own.
IS_SANDBOX and the telemetry switches as image ENVA mixin's ENV does not become the composed image's, so they ride the overlay as /etc/profile.d/claude-mixin-env.sh exports instead.

⁠Related