# How to Achieve Native Full-Stack ARM64 Deployment with CubeSandbox

> Achieve native full-stack ARM64 deployment with CubeSandbox v0.5.0. Run hypervisor, CubeShim, and guest agents directly on ARM bare-metal, leveraging KVM acceleration.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: how-to-guide
- Published: 2026-07-16

---

**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`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/zh/changelog/v0.5.0.md). Extract the bundle and verify that the [`run_vm.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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:

```bash

# 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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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.