Check your Mac
Before building anything, check what your Mac and Docker Desktop are actually running, because the fixes later in this guide depend on it. Four commands tell you nearly everything.
uname -m on the Mac says arm64, and docker version should say the Docker server is arm64 too: that's Docker Desktop's Linux VM. docker info shows how many CPUs and how much memory that VM has. Memory is the limit you'll hit first. It's set in Docker Desktop's settings (Resources), and every container shares it. A native FRR router uses tens of megabytes, but a VyOS VM uses about 1.7 GB.
As a guide from these labs: 8 GB comfortably runs FRR and Linux labs and one or two VyOS VMs. Three VyOS VMs at about 1.8 GB each, plus everything else, got one of them killed by the out-of-memory killer. If you plan to run several VMs, give Docker Desktop 12 GB or more, and give each VM a little less memory (VYOS_MEM).
How x86 programs run: binfmt_misc
When the Linux kernel is asked to run a program built for a different processor, it looks the program up in binfmt_misc, a list of "interpreters" for foreign binaries. On this Mac, Docker Desktop has registered two for x86-64 programs: Apple's Rosetta, and QEMU's user-mode emulator (x86_64). The list also has entries for older and stranger architectures.
An amd64 container proves which one is in use: it reports its processor as VirtualApple, which is Rosetta. The same command in a native container reports aarch64 and an Apple CPU (implementer 0x61).
If amd64 containers fail with exec format error, no interpreter is registered: turn on Rosetta in Docker Desktop's settings (General), or register QEMU's with docker run --privileged --rm tonistiigi/binfmt --install amd64. A QEMU registration made that way is lost when Docker Desktop restarts, so it's the first thing to check after a restart.
mac$ uname -m
arm64
mac$ sysctl -n machdep.cpu.brand_string
Apple M4 Max
mac$ docker version --format 'Client: {{.Client.Arch}} Server: {{.Server.Arch}} Kernel: {{.Server.KernelVersion}}'
Client: arm64 Server: arm64 Kernel: 7.0.14-linuxkit
mac$ docker info --format 'CPUs: {{.NCPU}} Memory: {{.MemTotal}} bytes'
CPUs: 16 Memory: 8318709760 bytes- Line 2: The Mac itself: ARM.
- Line 8: Docker's server (its Linux VM) is arm64 too, running a LinuxKit kernel.
- Line 11: What Docker Desktop's VM has to share between every container. About 7.7 GiB here: the 8 GB setting.
mac$ docker run --rm --privileged alpine sh -c 'mount -t binfmt_misc binfmt_misc /proc/sys/fs/binfmt_misc; ls /proc/sys/fs/binfmt_misc'
arm
i386
mips64
mips64le
ppc64le
register
riscv64
rosetta
rosetta-wrapper
s390x
status
x86_64
mac$ docker run --rm --platform linux/amd64 alpine sh -c 'uname -m; grep -m1 "model name" /proc/cpuinfo'
x86_64
model name : VirtualApple @ 2.50GHz
mac$ docker run --rm alpine sh -c 'uname -m; grep -m1 -iE "model name|CPU implementer" /proc/cpuinfo'
aarch64
CPU implementer : 0x61- Line 1: A privileged container can mount and list the kernel's binfmt_misc table.
- Lines 9–10: Rosetta's interpreter, registered by Docker Desktop.
- Line 13: QEMU's user-mode x86-64 interpreter, registered earlier with
tonistiigi/binfmt. - Lines 15–17: An amd64 container: x86_64, on a VirtualApple CPU. That's Rosetta doing the work.
- Lines 19–21: The same command natively: aarch64, and implementer 0x61 is Apple.
Check your understanding
A colleague's lab fails on their M2 Mac with exec format error the moment an amd64 container starts. What's the most likely fix?
- Register an x86 interpreter: turn on Rosetta in Docker Desktop's settings, or install QEMU's with tonistiigi/binfmt.
- Give Docker Desktop more memory.
- Use a layer-2-only network.
- Run the container as privileged.