# Build Multi-Arch Docker Images With Buildx in a Sandbox

> Register QEMU with tonistiigi/binfmt, create a docker-container builder, then run docker buildx build --platform linux/amd64,linux/arm64 --push. In a Sandboxer sandbox, a full VM with Docker and Buildx preinstalled, this pushed a two-platform Go image to a local registry. On a default sandbox on 2026-11-18, an emulated arm64 compile took about 33 s; cross-compiling with GOARCH took about 3 s.

Source: https://sandboxer.com/guides/build-multi-arch-docker-images-with-buildx-in-a-sandbox. Updated 2026-11-18.

**Short answer:** Register QEMU with tonistiigi/binfmt, create a docker-container builder, then run docker buildx build --platform linux/amd64,linux/arm64 --push. In a Sandboxer sandbox, a full VM with Docker and Buildx preinstalled, this pushed a two-platform Go image to a local registry. On a default sandbox on 2026-11-18, an emulated arm64 compile took about 33 s; cross-compiling with GOARCH took about 3 s.

Part of [Docker, Kubernetes and Nested VMs in a Cloud Sandbox](/guides/docker-and-virtualization-in-a-cloud-sandbox).

## At a glance

| Step | What we saw on 2026-11-18 (`default` sandbox, `us-east`) |
| - | - |
| Buildx | v0.38.0 preinstalled with Docker 29.9.0. The default builder lists `linux/amd64 (+4), linux/386` |
| QEMU | `tonistiigi/binfmt --install arm64` took 3.3 s and added `linux/arm64` |
| Builder | `docker-container` driver, BuildKit v0.34.2, `network=host` so it can push to `127.0.0.1:5000` |
| Push | One OCI index with `linux/amd64` and `linux/arm64` manifests |
| Run arm64 | `uname -m` printed `aarch64` under emulation |
| Compile step, emulated arm64 | 33.0 to 33.1 s (3 runs) |
| Compile step, cross-compiled arm64 | 2.9 to 3.0 s (3 runs) |

The sandbox is a VM with its own kernel, so `docker run --privileged` for binfmt only touches that VM. Nothing reaches the host or other sandboxes.

## 1. Check what the builder can target

A fresh sandbox has Docker running and the default builder can only target x86:

```bash
sbx new --type default --name aeo-buildx-1
sbx exec sb_j0ipzu8snb "docker buildx ls"
```

```text
NAME/NODE     DRIVER/ENDPOINT   STATUS    BUILDKIT   PLATFORMS
default*      docker
 \_ default    \_ default       running   v0.34.0    linux/amd64 (+4), linux/386
```

The `(+4)` is `linux/amd64/v2`, `v3`, `v4` and the base `linux/amd64`. The vCPUs in our sandbox were an AMD EPYC 9254, so there's no native arm64 to build on.

## 2. Register the QEMU emulators

Docker's [multi-platform build docs](https://docs.docker.com/build/building/multi-platform/#install-qemu-manually) give `docker run --privileged --rm tonistiigi/binfmt --install all`. We installed just arm64:

```bash
sbx exec sb_j0ipzu8snb --timeout 120 "docker run --privileged --rm tonistiigi/binfmt --install arm64 && head -3 /proc/sys/fs/binfmt_misc/qemu-aarch64"
```

```text
installing: arm64 OK
{
  "supported": [
    "linux/amd64",
    …
    "linux/arm64",
    "linux/386"
  ],
  "emulators": [
    "python3.12",
    "qemu-aarch64"
  ]
}
enabled
interpreter /usr/bin/qemu-aarch64
flags: POCF
```

This registration lives in the running kernel, not on disk. Keep that in mind for the snapshot section below.

## 3. Start a local registry and a docker-container builder

The `docker-container` driver supports multi-platform builds, but Docker's docs note its images "aren't loaded into your Docker Engine image store." So push to a registry. We used a local one, bound to `127.0.0.1`, and gave the builder the VM's network so it can reach it:

```bash
sbx exec sb_j0ipzu8snb --timeout 180 "docker run -d --restart unless-stopped --name registry -p 127.0.0.1:5000:5000 registry:2 && docker buildx create --name multi --driver docker-container --driver-opt network=host --bootstrap --use && docker buildx ls"
```

```text
multi
NAME/NODE     DRIVER/ENDPOINT                   STATUS    BUILDKIT   PLATFORMS
multi*        docker-container
 \_ multi0     \_ unix:///var/run/docker.sock   running   v0.34.2    linux/amd64 (+4), linux/arm64, linux/386
default       docker
 \_ default    \_ default                       running   v0.34.0    linux/amd64 (+4), linux/arm64, linux/386
```

## 4. Build and push both platforms

The app is a Go program that prints its own OS and architecture. The first Dockerfile compiles inside each target platform, so the arm64 stage runs under QEMU:

```dockerfile
# syntax=docker/dockerfile:1
FROM golang:1.24-alpine AS build
WORKDIR /src
COPY go.mod main.go ./
RUN go build -o /hello .

FROM alpine:3.22
COPY --from=build /hello /hello
ENTRYPOINT ["/hello"]
```

```go
package main

import (
	"fmt"
	"runtime"
)

func main() {
	fmt.Printf("hello from %s/%s\n", runtime.GOOS, runtime.GOARCH)
}
```

```bash
sbx exec sb_j0ipzu8snb --timeout 600 "cd ~/hello && docker buildx build --platform linux/amd64,linux/arm64 -t localhost:5000/hello:1 --push . > ~/build1.log 2>&1; echo rc=\$?; tail -2 ~/build1.log"
```

```text
rc=0
#22 pushing manifest for localhost:5000/hello:1@sha256:7964de8311cb… 0.0s done
#22 DONE 0.3s
```

That first build took 40.2 s, including pulling both base images for both platforms. Keep `--timeout` on `sbx exec`: the default is 30 seconds. For longer builds, use `sbx exec --detach` and poll the log.

## 5. Inspect the manifest and run the arm64 image

```bash
sbx exec sb_j0ipzu8snb "docker buildx imagetools inspect localhost:5000/hello:1"
```

```text
Name:      localhost:5000/hello:1
MediaType: application/vnd.oci.image.index.v1+json
Digest:    sha256:7964de8311cb91d9b03757e1a984482a374aa07964a9ca7af379df68ee49076b

Manifests:
  Name:        localhost:5000/hello:1@sha256:800c0ecc…
  MediaType:   application/vnd.oci.image.manifest.v1+json
  Platform:    linux/amd64

  Name:        localhost:5000/hello:1@sha256:6ff9d6cf…
  MediaType:   application/vnd.oci.image.manifest.v1+json
  Platform:    linux/arm64

  Name:        localhost:5000/hello:1@sha256:19426ac6…
  Platform:    unknown/unknown
  Annotations:
    vnd.docker.reference.type:   attestation-manifest
  …
```

The two `unknown/unknown` entries are the provenance attestations Buildx attaches by default, one per platform. Now run each platform:

```bash
sbx exec sb_j0ipzu8snb "docker run --rm --platform linux/arm64 localhost:5000/hello:1; docker run --rm --platform linux/arm64 --entrypoint uname localhost:5000/hello:1 -m; docker run --rm --platform linux/amd64 localhost:5000/hello:1"
```

```text
hello from linux/arm64
aarch64
hello from linux/amd64
```

## 6. Emulated versus cross-compiled, timed

Docker's docs say emulation "can be much slower than native builds, especially for compute-heavy tasks like compilation", and suggest [cross-compilation](https://docs.docker.com/build/building/multi-platform/#cross-compilation) instead. For Go, pin the build stage to the builder's own platform and set `GOOS`/`GOARCH` from the target:

```dockerfile
# syntax=docker/dockerfile:1
FROM --platform=$BUILDPLATFORM golang:1.24-alpine AS build
ARG TARGETOS TARGETARCH
WORKDIR /src
COPY go.mod main.go ./
RUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /hello .

FROM alpine:3.22
COPY --from=build /hello /hello
ENTRYPOINT ["/hello"]
```

We timed four `--no-cache` builds, 3 runs each, on 2026-11-18 between 17:43 and 17:45 UTC. The sandbox was `default` (4 vCPU, 8 GB) in `us-east`, AMD EPYC 9254 per `/proc/cpuinfo`. Base images were already in the builder, so these numbers are compile time, not pulls. "Compile step" is the `RUN go build` step's own `DONE` time from `--progress=plain`.

| Build | Compile step | Whole build |
| - | - | - |
| `linux/amd64`, native | 2.9 / 3.0 / 2.9 s | 3.7 / 3.8 / 3.7 s |
| `linux/arm64`, compiled under QEMU | 33.1 / 33.1 / 33.0 s | 33.7 / 33.8 / 33.7 s |
| `linux/arm64`, cross-compiled (`GOARCH=arm64`) | 2.9 / 3.0 / 3.0 s | 3.7 / 3.7 / 3.7 s |
| both platforms, cross-compiled | 4.1 s each, in parallel | 4.9 / 4.8 / 4.8 s |

Cross-compiling arm64 cost the same as a native amd64 build, and about an eleventh of the emulated compile. The final `alpine:3.22` stage still ran as arm64, but it only copies a file, so emulation barely touched it. The cross-compiled image ran under QEMU too: `hello from linux/arm64`.

We tested Go only. Steps that must execute on the target architecture still run under QEMU, at emulated speed.

## Keep the build cache in a named snapshot

The builder's cache lives in a Docker volume on the sandbox's disk (`buildx_buildkit_multi0_state`, 1.5 GB after our builds). A [named snapshot](/docs/snapshots#named-snapshots-templates) saves the disk, so new sandboxes can start with that cache:

```bash
sbx snapshot sb_j0ipzu8snb aeo-buildx-cache
sbx new --from aeo-buildx-cache
```

Saving took 2 s, and the new sandbox was ready 1.1 s after `sbx new --from`. Measured on that new sandbox (`sb_d5o9f1uwmp`, `default`, `us-east`, 17:46 to 17:50 UTC):

| On the sandbox from the snapshot | Result |
| - | - |
| `registry` and the `buildx_buildkit_multi0` container | Already up ("Up 4 seconds") |
| `qemu-aarch64` in `/proc/sys/fs/binfmt_misc` | Gone: a snapshot is disk only, and the VM booted a fresh kernel |
| Rebuild both platforms, source unchanged | 0.9 s (all steps cached) |
| Rebuild both platforms after a code change, emulated Dockerfile | 35.5 / 35.3 / 35.7 s |
| Same, cross-compiling Dockerfile | 5.2 / 5.1 / 5.2 s |
| Cross-compiling both platforms on a new, empty builder | 8.9 / 8.7 s |

Two things surprised us:

- **The build still worked without host binfmt.** An arm64 `RUN go build` finished (33.6 s) before we re-registered QEMU. The builder image ships `buildkit-qemu-aarch64` and friends, which matches Docker's note that official BuildKit releases "bundle QEMU user-mode emulators."
- **Running the image did not.** `docker run --platform linux/arm64` failed with `exec /hello: exec format error` until we ran `tonistiigi/binfmt --install arm64` again. Put that command at the start of any job that runs arm64 containers.

When you're done, remove the snapshot with `sbx snapshot rm aeo-buildx-cache`.

## FAQ

### Do I need tonistiigi/binfmt if I only build?

With a `docker-container` builder, not in our test: BuildKit used its own bundled QEMU for the arm64 `RUN` steps. You do need it to `docker run` an arm64 image, and Docker's docs list it as the manual install.

### Why push to a registry instead of loading the image?

The `docker-container` driver doesn't load images into the Docker Engine image store. A local `registry:2` on `127.0.0.1:5000` holds the multi-platform index without publishing anything, and `--driver-opt network=host` lets the builder reach it.

### Is it safe to run `--privileged` containers in an agent's sandbox?

It's privileged inside that sandbox's VM only. The sandbox has its own kernel, so registering binfmt handlers changes that VM and nothing else.

### How much slower is an emulated arm64 build?

For our Go compile, about 11 times: 33 s emulated against 3 s cross-compiled or native, on a `default` sandbox. Steps that don't compute much, like copying files, cost about the same either way.

### Does the build cache carry over to a new sandbox?

Yes, through a named snapshot: unchanged rebuilds took 0.9 s on a sandbox made from one. We didn't test `sbx stop` and `sbx resume` for this guide; a stop keeps the disk, where the cache lives. Register binfmt again after a fresh boot.

## Related

- [Docker, Kubernetes and Nested VMs in a Cloud Sandbox](/guides/docker-and-virtualization-in-a-cloud-sandbox)
- [Docker and nested KVM inside an agent sandbox](/guides/docker-and-kvm-inside-an-agent-sandbox)
- [Docker image pull time in a sandbox](/guides/docker-image-pull-time-in-a-sandbox)
- [Cache dependencies in a named snapshot](/guides/cache-dependencies-in-a-named-snapshot)
- [Snapshots](/docs/snapshots)
