# ARM64 Support Limitations and Requirements for CubeSandbox: A Technical Guide

> Discover ARM64 support limitations and requirements for CubeSandbox v0.5.0. Learn about KVM, Docker buildx, and UEFI needs for seamless operation.

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

---

**CubeSandbox natively supports ARM64 (AArch64) architecture starting from version 0.5.0, requiring KVM with nested virtualization (or bare-metal hosts), Docker with buildx, and UEFI firmware, while excluding PVM and x86-specific boot methods.**

CubeSandbox is an open-source secure sandbox environment maintained by TencentCloud. Understanding the ARM64 support limitations and requirements for CubeSandbox is essential for deploying secure workloads on modern ARM-based servers or cloud instances, as the architecture introduces specific constraints around virtualization modes and boot firmware that differ significantly from x86_64 deployments.

## Runtime Prerequisites for ARM64 Deployment

Deploying CubeSandbox on ARM64 hardware requires satisfying several architectural and software dependencies. The host environment must provide specific kernel capabilities and virtualization features that differ from standard x86_64 deployments.

### Host Architecture and Operating System

CubeSandbox requires a native AArch64 Linux server to run the hypervisor, guest kernels, and platform binaries. While the codebase supports multiple distributions, **OpenCloudOS 9** with kernel **6.6 or later** represents a validated target environment. The system must expose hardware virtualization extensions through KVM, which you can verify by running:

```bash
lsmod | grep kvm

```

If the command returns no results, your kernel either lacks KVM support or the modules are not loaded.

### Nested Virtualization Constraints

On ARM64 cloud VMs, **nested virtualization is mandatory**. According to the ARM support documentation in [`docs/zh/blog/posts/2026-07-08-cubesandbox-arm-support.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/zh/blog/posts/2026-07-08-cubesandbox-arm-support.md) (lines 93-94), if the cloud provider does not expose nested virtualization capabilities, you must deploy on **physical bare-metal machines** instead. This requirement stems from the hypervisor's direct dependency on ARM-specific KVM syscalls that cannot passthrough without nested-virt enabled.

### Container Engine and Privileges

You must install **Docker version 20 or later** with the `buildx` plugin to support multi-architecture image builds. All deployment commands require **root privileges** to install system services, load kernel modules, and create network namespaces. The one-click installer automatically detects the ARM64 architecture and pulls the appropriate UEFI firmware binary, replacing the x86-specific SeaBIOS implementation documented in [`network-agent/docs/DEVELOPMENT.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/docs/DEVELOPMENT.md) (lines 83-85).

## ARM64-Specific Limitations

Certain CubeSandbox features available on x86_64 are explicitly unsupported or restricted on ARM64 architectures.

### PVM and Alternative Hypervisors

**PVM (Pagetable-based VM)**, which provides a lightweight "Micro-VM" mode for x86_64 environments lacking `/dev/kvm` access, **is not supported on ARM64**. As noted in the ARM support blog (lines 93-94), PVM remains an x86_64-only feature. ARM64 deployments must use standard KVM virtualization and cannot fall back to PVM mode.

### GPU and IOMMU Address Ranges

While basic IOMMU functionality is supported, the implementation contains hard-coded ARM-specific MMIO regions. In [`hypervisor/virtio-devices/src/iommu.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/hypervisor/virtio-devices/src/iommu.rs) (lines 54-56), the code defines specific address ranges such as `0x8000000-0x80FFFFF` for ARM64 systems. These predefined ranges require no manual configuration for standard workloads but represent architecture-specific constraints that differ from x86 IOMMU implementations.

## Supported ARM64 Capabilities

Despite the limitations, CubeSandbox implements comprehensive support for core ARM64 virtualization features through targeted source code modifications.

### VCPU Initialization and ARM-Specific Features

The VCPU initialization logic in [`hypervisor/vmm/src/cpu.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/hypervisor/vmm/src/cpu.rs) (lines 415-450) configures essential ARM64 characteristics including **PSCI** (Power State Coordination Interface), **PMU-V3** (Performance Monitoring Unit), and power-off handling through `KVM_ARM_VCPU_INIT` syscalls. These initializations ensure proper guest CPU bring-up and power management on AArch64 hosts.

### Memory Page Size Handling

CubeSandbox correctly handles ARM64's variable page sizes, including **64 KiB pages**. The memory manager in [`hypervisor/vmm/src/memory_manager.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/hypervisor/vmm/src/memory_manager.rs) (lines 196-200) detects and follows the host's page size, automatically selecting the "ARM64 64 KiB path" when running on systems configured with 64 KiB kernel pages rather than the standard 4 KiB.

### Security Filtering

The platform maintains security isolation through architecture-specific seccomp filters. In [`hypervisor/vmm/src/seccomp_filters.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/hypervisor/vmm/src/seccomp_filters.rs) (lines 401-408), the code implements separate syscall whitelists for ARM64, explicitly allowing ARM-specific ioctls such as `KVM_ARM_VCPU_INIT` while maintaining the sandbox boundaries enforced across both x86 and ARM architectures.

## Deployment Workflow on ARM64

Follow this sequence to deploy CubeSandbox on ARM64 hardware:

1. Download the ARM64-specific one-click package containing multi-architecture images:

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

2. Configure the environment variables by copying the example file:

   ```bash
   cp env.example .env
   # Edit .env to set CUBE_SANDBOX_NODE_IP and CUBE_SANDBOX_NETWORK_CIDR if your NIC is not eth0

   ```

3. Execute the installer with root privileges:

   ```bash
   sudo ./install.sh
   ```

4. Verify the deployment health:

   ```bash
   sudo ./smoke.sh
   ```

5. Launch a sandbox using the Python SDK, which automatically detects the `aarch64` architecture:

   ```python
   import os
   from e2b_code_interpreter import Sandbox

   os.environ["CUBE_TEMPLATE_ID"] = "<your-template-id>"
   with Sandbox.create(template=os.getenv("CUBE_TEMPLATE_ID")) as sbx:
       result = sbx.run_code("import platform; print(platform.machine())")
       print(result)  # Expected: aarch64

   ```

## Key Source Files and Implementation Details

The following files in the TencentCloud/CubeSandbox repository contain the ARM64-specific implementation:

- **[`hypervisor/vmm/src/cpu.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/hypervisor/vmm/src/cpu.rs)** – Implements ARM VCPU initialization with PSCI, PMU, and power management bits (`KVM_ARM_VCPU_*` constants)

- **[`hypervisor/vmm/src/memory_manager.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/hypervisor/vmm/src/memory_manager.rs)** – Handles 64 KiB page-size detection and memory granularity for ARM64 hosts (lines 196-200)

- **[`hypervisor/vmm/src/seccomp_filters.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/hypervisor/vmm/src/seccomp_filters.rs)** – Defines ARM-specific seccomp syscall whitelists, including `KVM_ARM_VCPU_INIT` (lines 401-408)

- **[`hypervisor/virtio-devices/src/iommu.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/hypervisor/virtio-devices/src/iommu.rs)** – Contains ARM-specific MMIO address range definitions (`0x8000000-0x80FFFFF`) at lines 54-56

- **[`network-agent/docs/DEVELOPMENT.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/docs/DEVELOPMENT.md)** – Documents the UEFI boot requirement for ARM64, replacing SeaBIOS (lines 83-85)

- **[`docs/zh/blog/posts/2026-07-08-cubesandbox-arm-support.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/zh/blog/posts/2026-07-08-cubesandbox-arm-support.md)** – Canonical reference for ARM support limitations, including PVM exclusion and nested-virt requirements (lines 93-94)

- **[`deploy/one-click/online-install.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/deploy/one-click/online-install.sh)** – Deployment script that respects the `CUBE_PVM_ENABLE` flag (ignored on ARM platforms)

## Summary

- CubeSandbox added **native ARM64 support in version 0.5.0**, enabling full build, deploy, and runtime operations on AArch64 hosts

- **Nested virtualization is required** for cloud VM deployments; bare-metal servers are necessary when nested-virt is unavailable

- **PVM (Pagetable-based VM) is unsupported** on ARM64, restricting deployments to KVM-based virtualization only

- The implementation handles **ARM-specific boot requirements** through UEFI firmware rather than SeaBIOS, and properly manages **64 KiB page sizes** and **ARM seccomp filters**

- Source code modifications in [`cpu.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/cpu.rs), [`memory_manager.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/memory_manager.rs), and [`seccomp_filters.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/seccomp_filters.rs) provide the architectural adaptations necessary for secure ARM64 sandbox execution

## Frequently Asked Questions

### Does CubeSandbox fully support ARM64 processors?

Yes, CubeSandbox provides complete ARM64 (AArch64) support starting from version 0.5.0, including building, deploying, and running sandboxes. However, this support excludes the PVM hypervisor alternative and requires proper KVM configuration with nested virtualization for cloud environments.

### Why does CubeSandbox require nested virtualization on ARM64 cloud instances?

ARM64 cloud VMs must expose nested virtualization to allow CubeSandbox's KVM-based hypervisor to function. Without this capability, the ARM-specific KVM syscalls cannot operate correctly, forcing a migration to bare-metal hosts where full hardware access is available. This requirement is documented in the ARM support blog at lines 93-94.

### Can I run CubeSandbox on ARM64 without KVM using PVM?

No. **PVM (Pagetable-based VM)** is explicitly unsupported on ARM64 architecture. This lightweight alternative to KVM, which allows operation on systems without `/dev/kvm` access, is available only on x86_64 platforms. ARM64 deployments must have access to hardware KVM virtualization.

### What memory page sizes does CubeSandbox support on ARM64?

CubeSandbox supports standard 4 KiB pages and **64 KiB pages** on ARM64 systems. The memory manager in [`hypervisor/vmm/src/memory_manager.rs`](https://github.com/TencentCloud/CubeSandbox/blob/main/hypervisor/vmm/src/memory_manager.rs) automatically detects the host page size and follows the appropriate "ARM64 64 KiB path" when necessary, ensuring compatibility with different ARM64 kernel configurations.