sbx/qemu-kit:20260917-76ff755c31a3a7fc05fe7cbc53ae93753d7c6d85

schemaVersion: "2"
kind: mixin
name: qemu
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.
agentInstructions:
    content: |
        ## Multi-architecture emulation (QEMU / binfmt)

        QEMU user-mode emulators are registered with the kernel's binfmt_misc, so
        this sandbox can run and build container images for non-native CPU
        architectures (e.g. linux/arm64 on an amd64 host and vice versa).

        - Run a foreign-arch image directly:
          `docker run --rm --platform linux/arm64 alpine uname -m`
        - Build multi-arch images with buildx:
          `docker buildx build --platform linux/amd64,linux/arm64 .`
        - Check which emulators are registered:
          `docker run --privileged --rm tonistiigi/binfmt` prints them as JSON.
          `ls /proc/sys/fs/binfmt_misc/qemu-*` only works when binfmt_misc happens
          to be mounted in the sandbox, so an empty or missing directory does not
          mean emulation is unavailable — confirm with the `uname -m` command above.
        - If emulation is missing, read the startup log
          (`cat /var/log/sbx-kit-startup.log`) and re-run the registration:
          `docker run --privileged --rm tonistiigi/binfmt --install all`
permissions:
    network:
        allow:
            - registry-1.docker.io:443
            - auth.docker.io:443
            - production.cloudflare.docker.com:443
            - index.docker.io:443
            - archive.ubuntu.com:80
            - security.ubuntu.com:80
            - ports.ubuntu.com:80
            - download.docker.com:443
setup:
    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
          user: "0"
          description: Install `mount` for the binfmt_misc fast path (best-effort)
    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
          user: "0"
          description: Register QEMU binfmt emulators via Docker (best-effort)