feat: ARM64 architecture detection and build system

- Add TargetArch() utility for runtime architecture resolution with
  TARGET_ARCH env var override and alias normalization (x86_64↔amd64,
  aarch64↔arm64)
- Add BUILD_ARCH/BUILD_PLATFORM variables to api, client-proxy, envd,
  and orchestrator Makefiles (defaults to host GOARCH)
- Add fetch-busybox target for ARM64 busybox binary swap

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

packages/api/Makefile

@@ -6,6 +6,13 @@ PREFIX := $(strip $(subst ",,$(PREFIX)))
 HOSTNAME := $(shell hostname 2> /dev/null || hostnamectl hostname 2> /dev/null)
 $(if $(HOSTNAME),,$(error Failed to determine hostname: both 'hostname' and 'hostnamectl' failed))
 
+# Architecture for builds. Defaults to local arch; override for cross-compilation
+# (e.g., BUILD_ARCH=amd64 make build-and-upload from an ARM64 host).
+BUILD_ARCH ?= $(shell go env GOARCH)
+# Docker platform string. Override for multi-arch builds:
+#   BUILD_PLATFORM=linux/amd64,linux/arm64 make build-and-upload
+BUILD_PLATFORM ?= linux/$(BUILD_ARCH)
+
 expectedMigration := $(shell ./../../scripts/get-latest-migration.sh)
 
 ifeq ($(PROVIDER),aws)

packages/client-proxy/Makefile

@@ -6,6 +6,13 @@ PREFIX := $(strip $(subst ",,$(PREFIX)))
 HOSTNAME := $(shell hostname 2> /dev/null || hostnamectl hostname 2> /dev/null)
 $(if $(HOSTNAME),,$(error Failed to determine hostname: both 'hostname' and 'hostnamectl' failed))
 
+# Architecture for builds. Defaults to local arch; override for cross-compilation
+# (e.g., BUILD_ARCH=amd64 make build-and-upload from an ARM64 host).
+BUILD_ARCH ?= $(shell go env GOARCH)
+# Docker platform string. Override for multi-arch builds:
+#   BUILD_PLATFORM=linux/amd64,linux/arm64 make build-and-upload
+BUILD_PLATFORM ?= linux/$(BUILD_ARCH)
+
 ifeq ($(PROVIDER),aws)
 	IMAGE_REGISTRY := $(AWS_ACCOUNT_ID).dkr.ecr.$(AWS_REGION).amazonaws.com/$(PREFIX)core/client-proxy
 else
@@ -16,7 +23,7 @@ endif
 build:
 	# Allow for passing commit sha directly for docker builds
 	$(eval COMMIT_SHA ?= $(shell git rev-parse --short HEAD))
-	CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o bin/client-proxy -ldflags "-X=main.commitSHA=$(COMMIT_SHA)" .
+	CGO_ENABLED=0 GOOS=linux GOARCH=$(BUILD_ARCH) go build -o bin/client-proxy -ldflags "-X=main.commitSHA=$(COMMIT_SHA)" .
 
 .PHONY: build-debug
 build-debug:
@@ -26,7 +33,7 @@ build-debug:
 .PHONY: build-and-upload
 build-and-upload:
 	$(eval COMMIT_SHA := $(shell git rev-parse --short HEAD))
-	@docker buildx build --platform linux/amd64 --tag $(IMAGE_REGISTRY) --push --build-arg COMMIT_SHA="$(COMMIT_SHA)" -f ./Dockerfile ..
+	@docker buildx build --platform $(BUILD_PLATFORM) --tag $(IMAGE_REGISTRY) --push --build-arg COMMIT_SHA="$(COMMIT_SHA)" -f ./Dockerfile ..
 
 .PHONY: run
 run:

packages/envd/Makefile

@@ -7,6 +7,13 @@ LDFLAGS=-ldflags "-X=main.commitSHA=$(BUILD)"
 AWS_BUCKET_PREFIX ?= $(PREFIX)$(AWS_ACCOUNT_ID)-
 GCP_BUCKET_PREFIX ?= $(GCP_PROJECT_ID)-
 
+# Architecture for builds. Defaults to local arch; override for cross-compilation
+# (e.g., BUILD_ARCH=amd64 make build from an ARM64 host).
+BUILD_ARCH ?= $(shell go env GOARCH)
+# Docker platform string. Override for multi-arch builds:
+#   BUILD_PLATFORM=linux/amd64,linux/arm64 make start-docker
+BUILD_PLATFORM ?= linux/$(BUILD_ARCH)
+
 .PHONY: init
 init:
 	brew install protobuf
@@ -20,17 +27,17 @@ else
 endif
 
 build:
-	CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -a -o bin/envd ${LDFLAGS}
+	CGO_ENABLED=0 GOOS=linux GOARCH=$(BUILD_ARCH) go build -a -o bin/envd ${LDFLAGS}
 
 build-debug:
 	CGO_ENABLED=1 go build -race -gcflags=all="-N -l" -o bin/debug/envd ${LDFLAGS}
 
 start-docker:
 	make build
-	DOCKER_BUILDKIT=1 docker build --platform linux/amd64 -t envd-debug . -f debug.Dockerfile
+	DOCKER_BUILDKIT=1 docker build --platform $(BUILD_PLATFORM) -t envd-debug . -f debug.Dockerfile
 	docker run \
 	--name envd \
-	--platform linux/amd64 \
+	--platform $(BUILD_PLATFORM) \
 	-p 49983:49983 \
 	-p 2345:2345 \
 	-p 9999:9999 \

packages/orchestrator/Makefile

@@ -7,6 +7,13 @@ GCP_BUCKET_PREFIX ?= $(GCP_PROJECT_ID)-
 HOSTNAME := $(shell hostname 2> /dev/null || hostnamectl hostname 2> /dev/null)
 $(if $(HOSTNAME),,$(error Failed to determine hostname: both 'hostname' and 'hostnamectl' failed))
 
+# Architecture for builds. Defaults to local arch; override for cross-compilation
+# (e.g., BUILD_ARCH=amd64 make build from an ARM64 host).
+BUILD_ARCH ?= $(shell go env GOARCH)
+# Docker platform string. Override for multi-arch builds:
+#   BUILD_PLATFORM=linux/amd64,linux/arm64 make build
+BUILD_PLATFORM ?= linux/$(BUILD_ARCH)
+
 .PHONY: init
 init:
 	brew install protobuf
@@ -18,18 +25,18 @@ generate:
 .PHONY: build
 build:
 	$(eval COMMIT_SHA := $(shell git rev-parse --short HEAD))
-	@docker build --platform linux/amd64 --output=bin --build-arg COMMIT_SHA="$(COMMIT_SHA)" -f ./Dockerfile ..
+	@docker build --platform $(BUILD_PLATFORM) --output=bin --build-arg COMMIT_SHA="$(COMMIT_SHA)" -f ./Dockerfile ..
 
 .PHONY: build-local
-build-local:
+build-local: fetch-busybox
 	# Allow for passing commit sha directly for docker builds
 	$(eval COMMIT_SHA ?= $(shell git rev-parse --short HEAD))
-	CGO_ENABLED=1 GOOS=linux GOARCH=amd64 go build -o bin/orchestrator -ldflags "-X=main.commitSHA=$(COMMIT_SHA)" .
-	CGO_ENABLED=1 GOOS=linux GOARCH=amd64 go build -o bin/clean-nfs-cache -ldflags "-X=main.commitSHA=$(COMMIT_SHA)" ./cmd/clean-nfs-cache
+	CGO_ENABLED=1 GOOS=linux GOARCH=$(BUILD_ARCH) go build -o bin/orchestrator -ldflags "-X=main.commitSHA=$(COMMIT_SHA)" .
+	CGO_ENABLED=1 GOOS=linux GOARCH=$(BUILD_ARCH) go build -o bin/clean-nfs-cache -ldflags "-X=main.commitSHA=$(COMMIT_SHA)" ./cmd/clean-nfs-cache
 
 .PHONY: build-debug
-build-debug:
-	CGO_ENABLED=1 GOOS=linux GOARCH=amd64 go build -race -gcflags=all="-N -l" -o bin/orchestrator .
+build-debug: fetch-busybox
+	CGO_ENABLED=1 GOOS=linux GOARCH=$(BUILD_ARCH) go build -race -gcflags=all="-N -l" -o bin/orchestrator .
 
 .PHONY: run-debug
 run-debug:
@@ -105,7 +112,7 @@ test-docker:
 	@cp -r ../shared .shared/
 	@rm -rf .clickhouse/
 	@cp -r ../clickhouse .clickhouse/
-	@docker build --platform linux/amd64 -f test.Dockerfile --no-cache-filter runner --progress=plain -t orchestrator-test .
+	@docker build --platform $(BUILD_PLATFORM) -f test.Dockerfile --no-cache-filter runner --progress=plain -t orchestrator-test .
 	@rm -rf .shared/
 	@rm -rf .clickhouse/
 	@echo "Done"
@@ -125,6 +132,34 @@ build-template:
 	-kernel $(KERNEL_VERSION) \
 	-firecracker $(FIRECRACKER_VERSION)
 
+.PHONY: fetch-busybox
+fetch-busybox:
+	@ARCH=$(BUILD_ARCH); \
+	BUSYBOX_TARGET=./pkg/template/build/core/systeminit/busybox_1.36.1-2; \
+	if [ "$$ARCH" != "arm64" ]; then \
+		echo "✓ Using bundled amd64 busybox"; \
+	elif file "$$BUSYBOX_TARGET" 2>/dev/null | grep -q 'aarch64\|ARM aarch64'; then \
+		echo "✓ Busybox is already arm64"; \
+	elif command -v busybox >/dev/null 2>&1 && file "$$(command -v busybox)" 2>/dev/null | grep -q 'aarch64\|ARM aarch64' && file "$$(command -v busybox)" 2>/dev/null | grep -q 'statically linked'; then \
+		cp "$$(command -v busybox)" "$$BUSYBOX_TARGET" && \
+		echo "✓ Copied host busybox (arm64, static) to embedded path"; \
+	elif command -v apt-get >/dev/null 2>&1 && command -v dpkg-deb >/dev/null 2>&1; then \
+		echo "Fetching arm64 busybox via apt..."; \
+		TMPDIR=$$(mktemp -d); \
+		apt-get download busybox-static 2>/dev/null && \
+			dpkg-deb -x busybox-static_*.deb "$$TMPDIR" && \
+			cp "$$TMPDIR/bin/busybox" "$$BUSYBOX_TARGET" && \
+			rm -rf "$$TMPDIR" busybox-static_*.deb && \
+			echo "✓ Replaced embedded busybox with arm64 binary (from busybox-static package)" || \
+			{ rm -rf "$$TMPDIR" busybox-static_*.deb; echo "⚠ apt-get download failed"; exit 1; }; \
+	else \
+		echo "⚠ ARM64 busybox required but no method available to fetch it."; \
+		echo "  Options:"; \
+		echo "    1. Install busybox-static: apt install busybox-static, then re-run"; \
+		echo "    2. Manually place an arm64 busybox binary at: $$BUSYBOX_TARGET"; \
+		exit 1; \
+	fi
+
 .PHONY: migrate
 migrate:
 	./scripts/upload-envs.sh /mnt/disks/fc-envs/v1 $(TEMPLATE_BUCKET_NAME)

packages/shared/pkg/utils/env.go

@@ -3,9 +3,35 @@ package utils
 import (
 	"fmt"
 	"os"
+	"runtime"
 	"strings"
 )
 
+// archAliases normalizes common architecture names to Go convention.
+var archAliases = map[string]string{
+	"amd64":   "amd64",
+	"x86_64":  "amd64",
+	"arm64":   "arm64",
+	"aarch64": "arm64",
+}
+
+// TargetArch returns the target architecture for binary paths and OCI platform.
+// If TARGET_ARCH is set, it is normalized to Go convention ("amd64" or "arm64");
+// otherwise defaults to the host architecture (runtime.GOARCH).
+func TargetArch() string {
+	if arch := os.Getenv("TARGET_ARCH"); arch != "" {
+		if normalized, ok := archAliases[arch]; ok {
+			return normalized
+		}
+
+		fmt.Fprintf(os.Stderr, "WARNING: unrecognized TARGET_ARCH=%q, falling back to %s\n", arch, runtime.GOARCH)
+
+		return runtime.GOARCH
+	}
+
+	return runtime.GOARCH
+}
+
 // RequiredEnv returns the value of the environment variable for key if it is set, non-empty and not only whitespace.
 // It panics otherwise.
 //

packages/shared/pkg/utils/env_test.go

@@ -0,0 +1,66 @@
+package utils
+
+import (
+	"runtime"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestTargetArch_DefaultsToHostArch(t *testing.T) {
+	t.Setenv("TARGET_ARCH", "")
+
+	result := TargetArch()
+
+	assert.Equal(t, runtime.GOARCH, result)
+}
+
+func TestTargetArch_RespectsValidOverride(t *testing.T) {
+	tests := []struct {
+		name     string
+		arch     string
+		expected string
+	}{
+		{name: "amd64", arch: "amd64", expected: "amd64"},
+		{name: "arm64", arch: "arm64", expected: "arm64"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Setenv("TARGET_ARCH", tt.arch)
+
+			result := TargetArch()
+
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}
+
+func TestTargetArch_NormalizesAliases(t *testing.T) {
+	tests := []struct {
+		name     string
+		arch     string
+		expected string
+	}{
+		{name: "x86_64 → amd64", arch: "x86_64", expected: "amd64"},
+		{name: "aarch64 → arm64", arch: "aarch64", expected: "arm64"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Setenv("TARGET_ARCH", tt.arch)
+
+			result := TargetArch()
+
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}
+
+func TestTargetArch_FallsBackOnUnknown(t *testing.T) {
+	t.Setenv("TARGET_ARCH", "mips")
+
+	result := TargetArch()
+
+	assert.Equal(t, runtime.GOARCH, result)
+}