How to Achieve Native Full-Stack ARM64 Deployment with CubeSandbox

CubeSandbox v0.5.0 introduced native ARM64 (aarch64) support, enabling the hypervisor, CubeShim, and guest agents to run directly on ARM bare-metal with KVM acceleration, provided you avoid the x86_64-only PVM nested-virtualization mode.

CubeSandbox, TencentCloud's container-native virtualization platform, achieved production-ready ARM64 compatibility in its v0.5.0 release, allowing operators to deploy the complete virtualization stack on ARM-based servers without cross-architecture emulation. Native full-stack ARM64 deployment requires specific hardware capabilities and architectural adaptations, particularly the transition from PIO-based to MMIO-based device communication. This guide details the prerequisites, installation procedures, and architectural changes required to deploy CubeSandbox on ARM64 hardware.

Prerequisites: Bare-Metal ARM64 with Native KVM

Unlike x86_64 deployments, ARM64 requires bare-metal or physical ARM servers because the PVM (nested-KVM) mode is strictly limited to x86_64 architecture according to the source code. Your host must expose /dev/kvm and run a kernel that supports ARM64 virtualization extensions. Physical servers are mandatory; virtualized ARM64 instances cannot provide the necessary KVM nesting capabilities required by CubeSandbox's hypervisor.

Installing the ARM64 One-Click Bundle

Download the architecture-specific bundle cube-sandbox-one-click-*-arm64.tar.gz from the official releases page. This package contains the hypervisor, CubeShim, guest agent, and supporting binaries pre-compiled for aarch64, as documented in docs/zh/changelog/v0.5.0.md. Extract the bundle and verify that the run_vm.sh script is present, which automatically detects ARM64 and configures the machine virt profile with qemu-efi-aarch64 UEFI firmware.

Core Architecture Changes for ARM64

MMIO-Based Device Communication

The CubeSandbox hypervisor rewired the SysCtrl device from Port I/O (PIO)—which is x86-only—to Memory-Mapped I/O (MMIO) for ARM64 compatibility. According to docs/zh/changelog/v0.5.0.md, the guest agent now signals RPC readiness via /dev/mem MMIO at physical address 0x0903_0000 instead of using x86 PIO port writes. This change ensures proper device initialization on ARM64 hosts where port-mapped I/O is unavailable.

Boot Parameters and UART Configuration

CubeShim adapts kernel command-line arguments for ARM-specific hardware. The bootloader automatically sets console=ttyAMA0,115200 to use the ARM PL011 UART instead of x86-compatible serial devices. The run_vm.sh script, referenced in the deployment guides, handles this configuration automatically when it detects the aarch64 architecture.

Seccomp Filter Adjustments

The ARM64 implementation requires updated seccomp filters to accommodate different system call conventions. The source code shows replacements of SYS_mkdir with SYS_mkdirat and the addition of SYS_faccessat2 to the allowed syscall list. Release scripts also automatically select the correct mkcert binary and other architecture-specific assets during deployment.

Multi-Architecture Container Images

The official sandbox-code:latest image is multi-arch, supporting both x86_64 and ARM64 platforms without modification. However, if deploying custom templates, you may need to build ARM64 variants using Docker's multi-platform build features and the "template-from-image" workflow described in docs/zh/guide/self-build-deploy.md. Always verify image availability for your target architecture before production deployment.

Deployment Verification

Execute the following commands to verify your ARM64 deployment:

# Download the ARM64 bundle

curl -LO https://github.com/TencentCloud/CubeSandbox/releases/download/v0.5.0/cube-sandbox-one-click-arm64.tar.gz
tar -xzf cube-sandbox-one-click-arm64.tar.gz
cd cube-sandbox-one-click-arm64

# Verify KVM is available

ls /dev/kvm   # should exist

# Install ARM-specific QEMU tools (optional)

sudo apt-get install qemu-system-aarch64 qemu-img

# Start the sandbox (auto-detects ARM64 and uses machine virt + UEFI)

./run_vm.sh

# Create a multi-arch template from an OCI image

cube-cli template create --image docker.io/library/ubuntu:22.04 \
                         --name my-arm-template \
                         --platform linux/arm64

These commands assume execution on an ARM64 host with root privileges.

Known Limitations

Several features remain x86_64-only and are unavailable on ARM64 deployments:

• PVM (nested-KVM) mode: ARM64 deployments must use bare-metal KVM; nested virtualization is not supported.
• Live migration: Currently limited to x86_64 hosts.
• PMUv3 support: Older ARM kernels may lack Performance Monitor Unit v3 support; the runtime automatically falls back to PMU-less mode, as noted in hypervisor/release-notes.md.

Summary

• Native ARM64 support requires bare-metal ARM servers with /dev/kvm exposed; PVM nested-virtualization is x86_64-only.
• Use the cube-sandbox-one-click-*-arm64.tar.gz bundle containing pre-compiled aarch64 binaries.
• Architectural adaptations include MMIO-based SysCtrl communication at address 0x0903_0000, PL011 UART configuration (ttyAMA0), and updated seccomp filters (SYS_mkdirat, SYS_faccessat2).
• Leverage multi-arch images like sandbox-code:latest or build custom ARM64 templates using the template-from-image workflow.
• Live migration and PVM mode are not available on ARM64; plan for bare-metal static deployments.

Frequently Asked Questions

Does CubeSandbox support nested virtualization on ARM64?

No. The PVM (nested-KVM) mode is strictly limited to x86_64 architecture. ARM64 deployments require bare-metal hosts with native KVM support, as the hypervisor cannot run nested on virtualized ARM64 instances.

What specific hardware address does the ARM64 guest agent use for signaling?

The ARM64 guest agent uses MMIO at physical address 0x0903_0000 via /dev/mem to signal RPC readiness, replacing the x86-specific PIO port writes used in x86_64 deployments.

Can I migrate running VMs between ARM64 hosts?

No. Live migration is currently only supported on x86_64 architecture. ARM64 deployments require static instance placement or cold migration strategies until this feature is ported.

Do I need to modify container images for ARM64 deployment?

The official sandbox-code:latest image is multi-arch and works natively on ARM64. However, custom images may require rebuilding using Docker's multi-platform build capabilities to ensure proper ARM64 compatibility.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}