sbx/claude-mixin:latest

schemaVersion: "3"
displayName: Claude Code (mixin)
author: Docker, Inc. https://docker.com
description: 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.
sourceUrl: https://github.com/docker-hardened-images/definitions
version: 2.1.322
licenses:
    - SEE LICENSE IN https://github.com/anthropics/claude-code/blob/main/LICENSE.md
kind: mixin
provides:
    - [email protected]
capabilities:
    - type: com.docker.sandbox/network-policy@1
      config:
        runtime:
            allow:
                - api.anthropic.com:443
                - platform.claude.com:443
                - downloads.claude.ai:443
                - claude.com:443
                - mcp-proxy.anthropic.com:443
                - bridge.claudeusercontent.com:443
    - type: com.docker.sandbox/credential@1
      optional: true
      config:
        apiKey:
            inject:
                - domain: api.anthropic.com
                  format: '%s'
                  header: x-api-key
                - domain: mcp-proxy.anthropic.com
                  format: '%s'
                  header: x-api-key
        oauth:
            credentialFile:
                path: ~/.claude/.credentials.json
                structure:
                    claudeAiOauth:
                        accessToken: '{{.AccessToken}}'
                        expiresAt: '{{.ExpiresAt}}'
                        refreshToken: '{{.RefreshToken}}'
                        scopes: '{{.Scopes}}'
                    primaryApiKey: '{{.PrimaryApiKey}}'
            sentinels:
                accessToken: sk-ant-oat01-proxy-managed
                refreshToken: sk-ant-ort01-proxy-managed
            tokenEndpoint:
                host: platform.claude.com
                path: /v1/oauth/token
        phase: runtime
        service: anthropic
      description: Anthropic API access (API key or claude.ai OAuth)
    - type: com.docker.sandbox/lifecycle@1
      config:
        install:
            - command: |
                set -e
                ws="${WORKSPACE_DIR:-/}"
                esc=$(printf '%s' "$ws" | sed 's/\\/\\\\/g; s/"/\\"/g; s/\t/\\t/g; s/\r/\\r/g')
                projects="\"/\": { \"hasTrustDialogAccepted\": true }"
                [ "$ws" = "/" ] || projects="$projects, \"$esc\": { \"hasTrustDialogAccepted\": true }"
                printf '%s\n' "{
                  \"bypassPermissionsModeAccepted\": true,
                  \"hasCompletedOnboarding\": true,
                  \"hasSeenAutoDefaultNudge\": true,
                  \"projects\": { $projects }
                }" > /home/agent/.claude.json
                chown agent:agent /home/agent/.claude.json
              description: Seed Claude bypass and trust flags
              env:
                - WORKSPACE_DIR
              user: "0"
            - command: mkdir -p /home/agent/.claude && chown agent:agent /home/agent/.claude
              description: Ensure ~/.claude is agent-owned before settings seed
              user: "0"
            - command: |
                set -e
                HELPER=''
                if [ "${SBX_CRED_ANTHROPIC_MODE:-none}" != none ]; then
                  HELPER='  "apiKeyHelper": "echo proxy-managed",
                '
                fi
                # Model selection from the create-phase args. The args'
                # patterns admit no quote or backslash, so the expanded
                # value is safe inside the JSON string. effortLevel accepts
                # low/medium/high/xhigh; max and auto persist only through
                # CLAUDE_CODE_EFFORT_LEVEL (settings.json rejects them).
                model='${{ kit.args.model }}'
                effort='${{ kit.args.reasoningEffort }}'
                MODEL=''
                EFFORT=''
                ENV_BLOCK=''
                [ -z "$model" ] || MODEL="  \"model\": \"$model\",
                "
                case "$effort" in
                  '') ;;
                  max|auto)
                    ENV_BLOCK="  \"env\": { \"CLAUDE_CODE_EFFORT_LEVEL\": \"$effort\" },
                "
                    ;;
                  *)
                    EFFORT="  \"effortLevel\": \"$effort\",
                "
                    ;;
                esac
                # Lifecycle hooks for Narwhal (see /usr/local/bin/sbx-claude-hook):
                # Stop and StopFailure report a finished turn, Notification the
                # moments Claude waits on the user, UserPromptSubmit the prompt
                # that names the conversation (Claude Code lists sessions by id
                # only). The script never fails, never writes stdout and runs
                # async, so a session without the desktop app sees no delay and
                # no hook error.
                HOOK='{ "type": "command", "command": "/usr/local/bin/sbx-claude-hook claude", "timeout": 10, "async": true }'
                HOOKS="  \"hooks\": {
                    \"Stop\": [ { \"hooks\": [ $HOOK ] } ],
                    \"StopFailure\": [ { \"hooks\": [ $HOOK ] } ],
                    \"UserPromptSubmit\": [ { \"hooks\": [ $HOOK ] } ],
                    \"Notification\": [ { \"matcher\": \"permission_prompt|idle_prompt|elicitation_dialog|elicitation_url_dialog|agent_needs_input\", \"hooks\": [ $HOOK ] } ]
                  },
                "
                # The statusLine command is the only place Claude Code exposes
                # the live session (model, context window, cost, lines changed);
                # sbx-agent-hook forwards it to Narwhal's status bar and prints
                # nothing, so no status line is drawn in the terminal. A mixin that
                # sets its own statusLine (e.g. claude-sbx-statusline) replaces
                # this one and the app's session view goes quiet for that sandbox.
                STATUSLINE="  \"statusLine\": { \"type\": \"command\", \"command\": \"/usr/local/bin/sbx-claude-hook claude-status\" },
                "
                printf '%s' "{
                  \"themeId\": 1,
                  \"alwaysThinkingEnabled\": true,
                ${HELPER}${MODEL}${EFFORT}${ENV_BLOCK}${HOOKS}${STATUSLINE}  \"permissions\": { \"defaultMode\": \"bypassPermissions\" },
                  \"bypassPermissionsModeAccepted\": true,
                  \"skipDangerousModePermissionPrompt\": true
                }
                " > /home/agent/.claude/settings.json
              description: Seed Claude settings.json from the surfaced auth mode
              env:
                - SBX_CRED_ANTHROPIC_MODE
              user: agent
            - command: |
                set -e
                [ -n "$MCP_GATEWAY_URL" ] || exit 0
                claude mcp add mcp-gateway "$MCP_GATEWAY_URL" \
                  --transport http \
                  --scope user \
                  --header "Authorization: Bearer $MCP_SENTINEL_TOKEN_NAME" || true
              description: Register the sandbox MCP gateway at install
              env:
                - MCP_GATEWAY_URL
                - MCP_SENTINEL_TOKEN_NAME
              user: agent
        startup:
            - command: |
                set -e
                [ -n "$MCP_GATEWAY_URL" ] || exit 0
                claude mcp add mcp-gateway "$MCP_GATEWAY_URL" \
                  --transport http \
                  --scope user \
                  --header "Authorization: Bearer $MCP_SENTINEL_TOKEN_NAME" || true
              description: Register the sandbox MCP gateway (startup fallback)
              env:
                - MCP_GATEWAY_URL
                - MCP_SENTINEL_TOKEN_NAME
              user: agent
    - type: com.docker.sandbox/agent-skills@1
      optional: true
      config:
        path: /home/agent/.claude/skills
    - type: com.docker.sandbox/agent-context@1
      optional: true
      config:
        content: |
            Claude Code is installed at `/usr/local/bin/claude`. Run `claude` for an
            interactive session or `claude -p "<prompt>"` for a one-shot answer.

            Authentication is proxy-mediated: with a key bound on the host
            (`sbx secret set anthropic`), the `apiKeyHelper` in
            `~/.claude/settings.json` returns the literal string `proxy-managed` and
            the sandbox proxy substitutes the real key on requests to Anthropic's
            APIs; claude.ai OAuth tokens in `~/.claude/.credentials.json` are
            sentinels the proxy swaps the same way. There is no real credential in
            this container. With nothing bound, `claude` will ask you to log in.
        directory: /home/agent/.claude
        filename: CLAUDE.md
    - type: com.docker.sandbox/agent-context@2
      optional: true
      config:
        content: |
            Claude Code is installed at `/usr/local/bin/claude`. Run `claude` for an
            interactive session or `claude -p "<prompt>"` for a one-shot answer.

            Authentication is proxy-mediated: with a key bound on the host
            (`sbx secret set anthropic`), the `apiKeyHelper` in
            `~/.claude/settings.json` returns the literal string `proxy-managed` and
            the sandbox proxy substitutes the real key on requests to Anthropic's
            APIs; claude.ai OAuth tokens in `~/.claude/.credentials.json` are
            sentinels the proxy swaps the same way. There is no real credential in
            this container. With nothing bound, `claude` will ask you to log in.
        directory: /home/agent/.claude
        filename: CLAUDE.md
args:
    model:
        default: ""
        description: Claude model to use (settings.json `model`); empty keeps the CLI default
        pattern: ^[A-Za-z0-9._-]*$
        env: CLAUDE_MODEL
    reasoningEffort:
        default: ""
        description: Effort level (settings.json `effortLevel`); empty keeps the CLI default
        enum:
            - ""
            - low
            - medium
            - high
            - xhigh
            - max
            - auto
        env: CLAUDE_REASONING_EFFORT
    version:
        required: true
        description: Claude Code release the overlay carries
        pattern: ^[0-9]+\.[0-9]+\.[0-9]+$
        buildArg: VERSION