ARM64 Support Limitations and Requirements for CubeSandbox: A Technical Guide

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:

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 (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 (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 (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 (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 (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 (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:

   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:

   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:

   sudo ./install.sh

4. Verify the deployment health:

   sudo ./smoke.sh

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

   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 – Implements ARM VCPU initialization with PSCI, PMU, and power management bits (KVM_ARM_VCPU_* constants)

• 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 – Defines ARM-specific seccomp syscall whitelists, including KVM_ARM_VCPU_INIT (lines 401-408)

• hypervisor/virtio-devices/src/iommu.rs – Contains ARM-specific MMIO address range definitions (0x8000000-0x80FFFFF) at lines 54-56

• 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 – Canonical reference for ARM support limitations, including PVM exclusion and nested-virt requirements (lines 93-94)

• 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, memory_manager.rs, and 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 automatically detects the host page size and follows the appropriate "ARM64 64 KiB path" when necessary, ensuring compatibility with different ARM64 kernel configurations.

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