bachkukkik/box64-cm5-walkthrough.md

Full walkthrough: building box64 on Raspberry Pi CM5 Lite (Debian 13) and running OpenCode Desktop natively on ARM64

Running amd64 Binaries & OpenCode Desktop on Raspberry Pi CM5 Lite

A full walkthrough for building box64 on a Raspberry Pi Compute Module 5 Lite and getting OpenCode Desktop running natively on ARM64.

System Info

Component	Detail
Board	Raspberry Pi Compute Module 5 Lite Rev 1.0
SoC	BCM2712 — ARM Cortex-A76 (4 cores)
RAM	16 GB LPDDR4X
OS	Debian 13 (trixie), aarch64
dpkg architectures	`arm64` (native), `armhf` (foreign)

Step 1: Install Build Dependencies

sudo apt update
sudo apt install cmake build-essential python3

Note: cmake is not pre-installed on the minimal Debian image — make sure to include it.

Step 2: Build box64 from Source

git clone https://github.com/ptitSeb/box64.git ~/box64
cd ~/box64

mkdir build && cd build
cmake .. -D RPI5ARM64=1 -D CMAKE_BUILD_TYPE=RelWithDebInfo
make -j2

Important: Use -j2, not -j4. The CM5 Lite can thermally throttle during sustained compile workloads. Builds with -j4 may time out or fail on this board.

Step 3: Install box64

sudo make install

This installs:

Path	Description
`/usr/local/bin/box64`	Main binary (v0.4.3 at time of writing)
`/usr/local/bin/box64-bash`	box64-aware bash wrapper
`/etc/binfmt.d/box64.conf`	binfmt registration for x86_64
`/etc/box64.box64rc`	Runtime configuration
`/usr/lib/box64-x86_64-linux-gnu/`	x86_64 compatibility libraries

Step 4: Register binfmt

This tells the Linux kernel to use box64 for x86_64 ELF binaries automatically:

sudo systemctl restart systemd-binfmt

Verify registration:

cat /proc/sys/fs/binfmt_misc/x86_64

Step 5: Running amd64 Binaries

Method A — Automatic (via binfmt)

# Make the amd64 binary executable
chmod +x ./some-x86_64-binary
./some-x86_64-binary

Method B — Explicit

box64 ./some-x86_64-binary

Caveat: Rust / Tauri Applications

Rust-compiled and Tauri-based GUI applications (e.g., Electron-like desktop apps) may segfault (SIGSEGV) under box64. This is a known limitation — box64's dynarec doesn't fully handle the complex runtime these frameworks produce.

If a native ARM64 build exists, prefer that instead.

Bonus: OpenCode Desktop — Native ARM64

OpenCode Desktop provides a native ARM64 .deb, so box64 isn't needed for this app.

# Download the ARM64 build
wget https://github.com/anomalyco/opencode/releases/download/v1.14.30/opencode-desktop-linux-arm64.deb

# Install
sudo apt install ./opencode-desktop-linux-arm64.deb

This installs:

/usr/bin/OpenCode — GUI desktop app
/usr/bin/opencode-cli — CLI tool

Both are native aarch64 ELF binaries — no emulation needed.

Appendix: Goose Desktop (amd64) — Failure Report

Tested: goose_1.33.1_amd64.deb from block/goose v1.33.1 Date: April 30, 2026

Attempt 1: Multiarch dpkg install

sudo dpkg --add-architecture amd64
sudo apt update
sudo apt install ./goose_1.33.1_amd64.deb

Result: Failed. The Raspberry Pi repo ships libc6:arm64=2.41-12+rpt1+deb13u2 which conflicts with the Debian repo's libc6:amd64. APT's solver cannot satisfy both simultaneously — every amd64 dependency chain ultimately requires libc6:amd64, which breaks the installed libc6:arm64.

Attempt 2: Manual extraction + box64

mkdir -p ~/.local/share/goose-amd64
dpkg-deb -x goose_1.33.1_amd64.deb ~/.local/share/goose-amd64
box64 ~/.local/share/goose-amd64/usr/lib/goose/Goose

Result: Failed — SIGILL (Illegal Instruction), exit code 132.

This confirms the Rust/Tauri caveat noted in Step 5. The Goose desktop binary is a Tauri-based application (Rust + WebView2) and cannot execute under box64's dynarec.

Workaround: Native ARM64 CLI

Goose provides a native aarch64-unknown-linux-gnu CLI build (no desktop GUI):

wget https://github.com/block/goose/releases/download/v1.33.1/goose-aarch64-unknown-linux-gnu.tar.gz
mkdir -p ~/.local/share/goose-arm64
tar xzf goose-aarch64-unknown-linux-gnu.tar.gz -C ~/.local/share/goose-arm64/
cp ~/.local/share/goose-arm64/goose ~/.local/bin/goose

Verify:

$ goose --version
1.33.1

This is a native aarch64 ELF binary — no emulation needed. Only the CLI is available for ARM64 Linux; the desktop GUI has no ARM64 .deb build.

Cleanup

If you added amd64 as a foreign architecture during the failed Attempt 1, roll it back:

sudo dpkg --remove-architecture amd64
sudo apt update

Key Takeaways

box64 works well on the CM5 Lite with the RPI5ARM64 dynarec for many amd64 binaries.
Build with -j2 to avoid thermal throttling on the CM5 Lite.
Rust/Tauri apps may crash under box64 — always check for native ARM64 builds first.
OpenCode Desktop has a native ARM64 .deb — install it directly for the best experience.
box64 stays installed and ready for any future amd64-only binaries you encounter.

Tested on Debian 13 (trixie) aarch64, Raspberry Pi CM5 Lite Rev 1.0, box64 v0.4.3.