docker/sbx-kit-qemu:1.0.0

schemaVersion: "3"
displayName: QEMU (multi-arch binfmt)
description: Registers QEMU user-mode emulators with the kernel's binfmt_misc via Docker (tonistiigi/binfmt) so the sandbox can run and build container images for other CPU architectures. Requires a Docker-in-Docker base template.
version: 1.0.0
kind: mixin
provides:
    - qemu-binfmt
requires:
    - deb/docker-ce
capabilities:
    - type: com.docker.sandbox/network-policy@1
      config:
        install:
            allow:
                - archive.ubuntu.com
                - security.ubuntu.com
                - ports.ubuntu.com
                - download.docker.com
        runtime:
            allow:
                - registry-1.docker.io
                - auth.docker.io
                - production.cloudflare.docker.com
                - index.docker.io
    - type: com.docker.sandbox/lifecycle@1
      config:
        install:
            - command: |
                set -u
                if ! command -v mount >/dev/null 2>&1; then
                  export DEBIAN_FRONTEND=noninteractive
                  if ! { apt-get update && apt-get install -y --no-install-recommends mount; }; then
                    echo "warning: could not install mount; the binfmt_misc fast path is unavailable (registration is unaffected)" >&2
                  fi
                  rm -rf /var/lib/apt/lists/*
                fi
                exit 0
              description: Install `mount` for the binfmt_misc fast path (best-effort)
              user: "0"
        startup:
            - command:
                - sh
                - -c
                - |
                  set -eu
                  # A missing docker is the only hard failure: it is a composition error
                  # the user has to fix. Everything after it is best-effort, because a
                  # non-zero exit from a startup command leaves the whole sandbox unable
                  # to start — so the rest only warns into the startup log.
                  if ! command -v docker >/dev/null 2>&1; then
                    echo "docker not found: the qemu kit needs a Docker-in-Docker base (compose it onto a *-docker template, e.g. docker/sandbox-templates:shell-docker)" >&2
                    exit 1
                  fi
                  # Registration happens inside the binfmt container's own mount
                  # namespace and does not need this mount; it only powers the fast path
                  # below and `ls /proc/sys/fs/binfmt_misc/qemu-*` in the sandbox.
                  if [ ! -e /proc/sys/fs/binfmt_misc/register ]; then
                    mount -t binfmt_misc binfmt_misc /proc/sys/fs/binfmt_misc || echo "warning: could not mount binfmt_misc; ls /proc/sys/fs/binfmt_misc will stay empty (registration is unaffected)" >&2
                  fi
                  # binfmt_misc registrations are kernel-global and survive sandbox
                  # restarts, so skip the network-heavy install when they are visible.
                  if ls /proc/sys/fs/binfmt_misc/qemu-* >/dev/null 2>&1; then
                    echo "QEMU binfmt emulators already registered; skipping install."
                    exit 0
                  fi
                  # The sandbox start waits for this hook and gives up after five
                  # minutes, so every network step here is bounded (60s + 180s).
                  deadline=$(( $(date +%s) + 60 ))
                  until timeout 5 docker info >/dev/null 2>&1; do
                    if [ "$(date +%s)" -ge "$deadline" ]; then
                      echo "warning: docker daemon not reachable after 60s; QEMU emulators not registered. Register manually with: docker run --privileged --rm tonistiigi/binfmt --install all" >&2
                      exit 0
                    fi
                    sleep 1
                  done
                  # `--install all` exits 0 even when an arch fails; its
                  # `installing: <arch> OK` log lines are the only success signal.
                  timeout 180 docker run --privileged --rm tonistiigi/binfmt --install all || echo "warning: tonistiigi/binfmt did not complete; QEMU emulators may be missing. Retry with: docker run --privileged --rm tonistiigi/binfmt --install all" >&2
              description: Register QEMU binfmt emulators via Docker (best-effort)
              env:
                - DOCKER_HOST
              user: "0"
    - type: com.docker.sandbox/agent-context@1
      config:
        contentFile: /usr/share/sandbox/kit/qemu/qemu-context.md