docker/sbx-kit-builder:1.1.0

schemaVersion: "3"
displayName: Kit Builder
description: DHI-based Docker-in-Docker sandbox for building kits — dockerd, buildx with a dedicated container-driver builder, and QEMU binfmt emulators for multi-arch builds. Every package installed from the DHI deb repository. BuildKit can listen on TCP so the host can attach via docker buildx --driver remote.
sourceUrl: https://github.com/docker/sandbox-kit-spec
version: 1.1.0
kind: workload
provides:
    - kit-builder
    - deb/[email protected]
    - deb/[email protected]
    - deb/ca-certificates@20250419
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
    - deb/[email protected]
capabilities:
    - type: com.docker.sandbox/privileged@1
    - type: com.docker.sandbox/kit-registry@1
      description: Push built kit images into the runtime's image store
    - type: com.docker.sandbox/volume@1
      config:
        path: /var/lib/docker
        size: ${{ kit.args.volumeSize }}
    - type: com.docker.sandbox/port@1
      config:
        container: ${{ kit.args.buildkitPort }}
        name: buildkit
        transport: tcp
    - type: com.docker.sandbox/resources@1
      config:
        cpu: 4
        memory: 8g
    - type: com.docker.sandbox/network-policy@1
      config:
        runtime:
            allow:
                - '**'
    - type: com.docker.sandbox/lifecycle@1
      config:
        startup:
            - background: true
              command:
                - sh
                - -c
                - |
                  set -eu
                  if docker info >/dev/null 2>&1; then exit 0; fi
                  if ! pgrep -x dockerd >/dev/null 2>&1; then
                    dockerd >/var/log/dockerd.log 2>&1 &
                  fi
              description: Start dockerd unless the runtime already did
              user: "0"
            - command:
                - sh
                - -c
                - |
                  set -eu
                  i=0
                  until docker info >/dev/null 2>&1; do
                    i=$((i + 1))
                    [ "$i" -lt 60 ] || { echo "dockerd did not come up" >&2; exit 1; }
                    sleep 1
                  done
                  if [ ! -e /proc/sys/fs/binfmt_misc/register ]; then
                    mount -t binfmt_misc binfmt_misc /proc/sys/fs/binfmt_misc
                  fi
                  if ! ls /proc/sys/fs/binfmt_misc/qemu-* >/dev/null 2>&1; then
                    docker run --privileged --rm tonistiigi/binfmt --install all
                  fi
              description: Register QEMU emulators for multi-arch builds
              user: "0"
            - command:
                - sh
                - -c
                - |
                  set -eu
                  i=0
                  until [ -f /usr/local/share/ca-certificates/proxy-ca.crt ]; do
                    i=$((i + 1))
                    [ "$i" -lt 15 ] || break
                    sleep 1
                  done
                  addrs='--addr unix:///run/buildkit/buildkitd.sock'
                  if [ '${{ kit.args.buildkitExpose }}' = true ]; then
                    addrs="--addr tcp://0.0.0.0:${{ kit.args.buildkitPort }} $addrs"
                  fi
                  if ! docker buildx inspect sbx-builder >/dev/null 2>&1; then
                    mkdir -p /home/agent/.config/buildkit
                    printf '[registry."host.docker.internal:5411"]\n  http = true\n' \
                      > /home/agent/.config/buildkit/sbx-builder.toml
                    docker buildx create --name sbx-builder \
                      --driver docker-container \
                      --driver-opt network=host \
                      --buildkitd-flags "$addrs" \
                      ${HTTPS_PROXY:+--driver-opt env.HTTPS_PROXY="$HTTPS_PROXY"} \
                      ${HTTP_PROXY:+--driver-opt env.HTTP_PROXY="$HTTP_PROXY"} \
                      --config /home/agent/.config/buildkit/sbx-builder.toml \
                      --bootstrap --use
                  fi
                  if docker inspect buildx_buildkit_sbx-builder0 >/dev/null 2>&1; then
                    docker cp /etc/ssl/certs/ca-certificates.crt \
                      buildx_buildkit_sbx-builder0:/etc/ssl/certs/ca-certificates.crt
                  fi
              description: Bootstrap the agent's container-driver buildx builder
              env:
                - HTTP_PROXY
                - HTTPS_PROXY
              user: "1000"
    - type: com.docker.sandbox/agent-context@1
      optional: true
      config:
        content: |
            ## Kit builder sandbox

            This sandbox builds kit images with Docker-in-Docker.

            - Build a kit: `docker buildx build . -f <kit>.yaml` — the buildx
              builder `sbx-builder` (docker-container driver) is already selected.
            - Multi-arch builds work via registered QEMU emulators:
              `docker buildx build --platform linux/amd64,linux/arm64 .`
            - Export for the host: add `--output type=oci,dest=out.tar`.
            - The engine store under /var/lib/docker persists across restarts and
              serves as the build cache (default 20g; override with
              `--kit-arg volumeSize=…` at create).

            ### Attach from the host

            Off by default. Create the sandbox with
            `--kit-arg buildkitExpose=true` and BuildKit also listens on TCP
            ${{ kit.args.buildkitPort }} (`--kit-arg buildkitPort=…` to move
            it), which the runtime publishes to a host port. Read the mapping
            from `sbx kit builder status`, then:

                docker buildx create --name sbx-remote --driver remote \
                  tcp://127.0.0.1:<host-port> --use
                docker buildx build --builder sbx-remote . -f <kit>.yaml

            Re-create the remote builder if the host port changes after a
            sandbox recreate. That endpoint is an unauthenticated root build
            API, so only turn it on where the host binds loopback.
        filename: AGENTS.md
    - type: com.docker.sandbox/agent-context@2
      optional: true
      config:
        content: |
            ## Kit builder sandbox

            This sandbox builds kit images with Docker-in-Docker.

            - Build a kit: `docker buildx build . -f <kit>.yaml` — the buildx
              builder `sbx-builder` (docker-container driver) is already selected.
            - Multi-arch builds work via registered QEMU emulators:
              `docker buildx build --platform linux/amd64,linux/arm64 .`
            - Export for the host: add `--output type=oci,dest=out.tar`.
            - The engine store under /var/lib/docker persists across restarts and
              serves as the build cache (default 20g; override with
              `--kit-arg volumeSize=…` at create).

            ### Attach from the host

            Off by default. Create the sandbox with
            `--kit-arg buildkitExpose=true` and BuildKit also listens on TCP
            ${{ kit.args.buildkitPort }} (`--kit-arg buildkitPort=…` to move
            it), which the runtime publishes to a host port. Read the mapping
            from `sbx kit builder status`, then:

                docker buildx create --name sbx-remote --driver remote \
                  tcp://127.0.0.1:<host-port> --use
                docker buildx build --builder sbx-remote . -f <kit>.yaml

            Re-create the remote builder if the host port changes after a
            sandbox recreate. That endpoint is an unauthenticated root build
            API, so only turn it on where the host binds loopback.
        filename: AGENTS.md
args:
    buildkitExpose:
        default: "false"
        description: Let BuildKit listen on TCP for the host's remote driver (unauthenticated root build API)
        enum:
            - "false"
            - "true"
    buildkitPort:
        default: "3330"
        description: In-container TCP port BuildKit listens on when buildkitExpose is true
        pattern: ^[0-9]{4,5}$
    volumeSize:
        default: 20g
        description: Capacity of the /var/lib/docker engine-store volume (build cache)
        pattern: ^[0-9]+(\.[0-9]+)?\s*([kKmMgGtT]i?[bB]?)?$