Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

fix(sandbox): build real arm64 sandbox images and ship arm64 Cube variants

hailongzhao176aa0d02b30
diff --git a/.github/workflows/docker-image.yml b/.github/workflows/docker-image.yml
index a5921c4a1..c97895f5f 100644
--- a/.github/workflows/docker-image.yml
+++ b/.github/workflows/docker-image.yml
@@ -148,13 +148,11 @@ jobs:
flavor: |
suffix=-cube,onlatest=true
- # amd64 only: cubesandbox-base, the source of the envd binary, publishes
- # no arm64 image.
- name: Build sandbox Cube Image
uses: docker/build-push-action@v7
with:
push: true
- platforms: linux/amd64
+ platforms: linux/amd64,linux/arm64
file: docker/Dockerfile.sandbox
target: cube
context: .
@@ -192,12 +190,11 @@ jobs:
flavor: |
suffix=-desktop-cube,onlatest=true
- # amd64 only: same cubesandbox-base constraint as the cube target.
- name: Build sandbox desktop Cube Image
uses: docker/build-push-action@v7
with:
push: true
- platforms: linux/amd64
+ platforms: linux/amd64,linux/arm64
file: docker/Dockerfile.sandbox
target: desktop-cube
context: .
diff --git a/docker/Dockerfile.sandbox b/docker/Dockerfile.sandbox
index b789ed42e..10c7b209d 100644
--- a/docker/Dockerfile.sandbox
+++ b/docker/Dockerfile.sandbox
@@ -14,28 +14,41 @@
# tag; the desktop and desktop-cube targets sit on it.
# desktop - desktop-runtime, tagged for E2B (and a future Docker
# desktop path). The Docker backend does not use this yet.
-# desktop-cube - desktop-runtime plus Cube envd. amd64 only, same reason
-# as cube.
+# desktop-cube - desktop-runtime plus Cube envd.
#
-# Pin every FROM to TARGETPLATFORM. `docker build --platform` alone is not
-# enough: the legacy builder (DOCKER_BUILDKIT=0) on Apple Silicon still
-# pulls the host's arm64 python/node, then COPY's amd64 envd — Cube probes
-# that mixed image as READY and Exec fails with "exec format error".
-# Default amd64 matches cube/desktop-cube; BuildKit overrides this when
-# --platform is linux/arm64 (sandbox / desktop).
-ARG TARGETPLATFORM=linux/amd64
+# Pin every FROM to TARGETPLATFORM. BuildKit already honours --platform; the
+# pin is for the legacy builder (DOCKER_BUILDKIT=0), which ignores --platform
+# whenever the host's arm64 python/node is already cached. The cube target
+# can then COPY envd of one architecture onto a runtime of the other — Cube
+# probes the mixed image as READY and Exec fails with "exec format error".
+#
+# Do not give this ARG a default. A declared default beats the value BuildKit
+# injects per platform, so a multi-platform build would run every platform on
+# the amd64 rootfs and only relabel the config. The legacy builder injects
+# nothing and rejects an empty --platform, hence the amd64 fallback in FROM:
+# under that builder an arm64 image needs --build-arg TARGETPLATFORM.
+ARG TARGETPLATFORM
# Stage 1: Get Node.js binaries
-FROM --platform=$TARGETPLATFORM node:20-slim AS node-base
+FROM --platform=${TARGETPLATFORM:-linux/amd64} node:20-slim AS node-base
-FROM --platform=$TARGETPLATFORM ghcr.io/astral-sh/uv:0.12.4 AS uv-base
+FROM --platform=${TARGETPLATFORM:-linux/amd64} ghcr.io/astral-sh/uv:0.12.4 AS uv-base
# Stage 2: Runtime image
#
# 3.12 is the floor because skill sources commonly use PEP 701 nested quotes
# in f-strings (f"x={d["k"]}"). Install-time ast.parse runs this interpreter;
# 3.11 rejects that syntax and the whole skill install fails.
-FROM --platform=$TARGETPLATFORM python:3.12-slim AS runtime
+FROM --platform=${TARGETPLATFORM:-linux/amd64} python:3.12-slim AS runtime
+
+# Fail the build when the rootfs is not the platform being built. No default:
+# BuildKit sets TARGETARCH per platform; the legacy builder leaves it empty.
+ARG TARGETARCH
+RUN arch="$(dpkg --print-architecture)"; \
+ if [ -n "$TARGETARCH" ] && [ "$arch" != "$TARGETARCH" ]; then \
+ echo "runtime rootfs is $arch but TARGETARCH=$TARGETARCH" >&2; \
+ exit 1; \
+ fi
# Copy Node.js from node image (avoids NodeSource install overhead)
COPY --from=node-base /usr/local/bin/node /usr/local/bin/
@@ -109,21 +122,25 @@ USER root
# runs as root and selects the account named in each request. WeKnora names
# root by default, matching the runtime stage.
#
-# This target is linux/amd64 only: cubesandbox-base publishes no arm64 image,
-# which matches Cube itself (PVM is x86_64-only). Hard-pin the FROM so a
-# forgotten --platform cannot copy an amd64 envd onto an arm64 runtime.
-FROM --platform=linux/amd64 ghcr.io/tencentcloud/cubesandbox-base:2026.16 AS cube-base
+# Built for amd64 and arm64: cubesandbox-base ships both, and Cube runs on
+# x86_64 (PVM or bare-metal KVM) and on arm64 bare-metal KVM. PVM itself is
+# x86_64-only, so an arm64 Cube host needs native KVM.
+FROM --platform=${TARGETPLATFORM:-linux/amd64} ghcr.io/tencentcloud/cubesandbox-base:2026.16 AS cube-base
FROM runtime AS cube
-ARG TARGETARCH=amd64
USER root
-RUN if [ "$TARGETARCH" != "amd64" ]; then \
- echo "cube is linux/amd64 only (cubesandbox-base has no arm64), got TARGETARCH=$TARGETARCH" >&2; \
- exit 1; \
- fi
COPY --from=cube-base /usr/bin/envd /usr/bin/envd
COPY --from=cube-base /usr/local/bin/cube-entrypoint.sh /usr/local/bin/cube-entrypoint.sh
+# Compare envd with the rootfs rather than trusting TARGETARCH: the legacy
+# builder leaves TARGETARCH empty, and a mixed image is exactly what this
+# guard exists to stop.
+RUN arch="$(dpkg --print-architecture)"; \
+ case "$arch" in amd64) elf=x86-64 ;; arm64) elf=aarch64 ;; *) elf="$arch" ;; esac; \
+ if ! file -bL /usr/bin/envd | grep -q "$elf"; then \
+ echo "envd is$(file -bL /usr/bin/envd | cut -d, -f2) but rootfs is $arch" >&2; \
+ exit 1; \
+ fi
EXPOSE 49983
# The entrypoint backgrounds envd and then waits on it, since this image
@@ -186,17 +203,18 @@ RUN chmod 0755 /usr/local/bin/start-desktop.sh \
FROM desktop-runtime AS desktop
EXPOSE 6080
-# Stage 6: desktop + Cube envd. linux/amd64 only, same constraint as cube.
+# Stage 6: desktop + Cube envd. Same platforms and envd check as cube.
FROM desktop-runtime AS desktop-cube
-ARG TARGETARCH=amd64
USER root
-RUN if [ "$TARGETARCH" != "amd64" ]; then \
- echo "desktop-cube is linux/amd64 only (cubesandbox-base has no arm64), got TARGETARCH=$TARGETARCH" >&2; \
- exit 1; \
- fi
COPY --from=cube-base /usr/bin/envd /usr/bin/envd
COPY --from=cube-base /usr/local/bin/cube-entrypoint.sh /usr/local/bin/cube-entrypoint.sh
+RUN arch="$(dpkg --print-architecture)"; \
+ case "$arch" in amd64) elf=x86-64 ;; arm64) elf=aarch64 ;; *) elf="$arch" ;; esac; \
+ if ! file -bL /usr/bin/envd | grep -q "$elf"; then \
+ echo "envd is$(file -bL /usr/bin/envd | cut -d, -f2) but rootfs is $arch" >&2; \
+ exit 1; \
+ fi
# cube-entrypoint.sh redirects envd to /var/log/envd.log. Cube packs this
# ~1.5GiB image into a 1.5GiB ext4 with no spare blocks; mkdir/write of that
diff --git a/internal/sandbox/sandbox.go b/internal/sandbox/sandbox.go
index 44850b4fc..e71e5d571 100644
--- a/internal/sandbox/sandbox.go
+++ b/internal/sandbox/sandbox.go
@@ -76,7 +76,7 @@ const (
DefaultDesktopDockerImage = "wechatopenai/weknora-sandbox:main-desktop"
// DefaultCubeDesktopTemplateImage is DefaultDesktopDockerImage plus Cube
- // envd (target "desktop-cube"). amd64 only, same reason as the cube target.
+ // envd (target "desktop-cube").
DefaultCubeDesktopTemplateImage = "wechatopenai/weknora-sandbox:main-desktop-cube"
// DesktopWebsockifyPort is websockify inside the sandbox. WeKnora dials
diff --git a/scripts/build_images.sh b/scripts/build_images.sh
index 3df3261b0..f500b61bd 100755
--- a/scripts/build_images.sh
+++ b/scripts/build_images.sh
@@ -234,13 +234,11 @@ build_sandbox_image() {
# Cube 从镜像直接构建模板,并以 :49983/health 探活,缺 envd 必然失败,
# 因此 Cube 用的是注入了 envd 的变体镜像。详见 website-docs/06-development/04-sandbox-deployment.md。
- # 固定 linux/amd64:envd 的来源镜像 cubesandbox-base 不发布 arm64。
log_info "构建沙箱镜像 Cube 变体 (weknora-sandbox:main-cube)..."
docker build \
- --platform linux/amd64 \
- --build-arg TARGETPLATFORM=linux/amd64 \
- --build-arg TARGETARCH=amd64 \
+ --platform $PLATFORM \
+ --build-arg TARGETPLATFORM=$PLATFORM \
-f docker/Dockerfile.sandbox \
--target cube \
-t wechatopenai/weknora-sandbox:latest-cube \
@@ -273,9 +271,8 @@ build_sandbox_image() {
log_info "构建沙箱镜像桌面 Cube 变体 (weknora-sandbox:main-desktop-cube)..."
docker build \
- --platform linux/amd64 \
- --build-arg TARGETPLATFORM=linux/amd64 \
- --build-arg TARGETARCH=amd64 \
+ --platform $PLATFORM \
+ --build-arg TARGETPLATFORM=$PLATFORM \
-f docker/Dockerfile.sandbox \
--target desktop-cube \
-t wechatopenai/weknora-sandbox:latest-desktop-cube \