# System Requirements for CubeSandbox: Complete Hardware and Software Prerequisites

> Discover CubeSandbox system requirements. Deploy micro-VMs on x86_64 or ARM64 Linux with KVM, root, Docker, 8GB RAM, and 50GB disk. Get started with TencentCloud.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: architecture
- Published: 2026-07-14

---

**CubeSandbox requires an x86_64 or ARM64 Linux host running kernel 4.11 or later with KVM enabled, root privileges, Docker Engine, at least 8 GB of RAM, and 50 GB of free disk space to deploy micro-VMs via the TencentCloud open-source platform.**

Before deploying CubeSandbox from the TencentCloud repository, ensure your bare-metal or virtualized host meets the necessary hardware, kernel, and software dependencies. The platform orchestrates micro-virtual machines using a KVM-based hypervisor wrapped in containerized control plane components, imposing specific system requirements that differ from standard container-only runtimes.

## Hardware and Architecture Prerequisites

CubeSandbox supports two primary CPU architectures for the host machine. According to the root [`README.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/README.md) and bare-metal deployment guide, you must prepare a Linux server matching one of these specifications.

### Supported CPU Architectures

- **x86_64 (AMD64)**: Standard Intel or AMD 64-bit processors
- **aarch64 (ARM64)**: ARM-based servers such as AWS Graviton or Ampere Altra

Both architectures are fully supported for running the KVM-based micro-VM hypervisor, though ARM64 hosts may have specific limitations regarding performance monitoring hardware.

### Memory and Storage Requirements

As documented in [`docs/guide/bare-metal-deploy.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/guide/bare-metal-deploy.md), the host requires:

- **Minimum 8 GB RAM**: This is the baseline for the control plane and a few micro-VMs; production workloads with high concurrency require significantly more
- **At least 50 GB free disk space**: Allocated for VM images, templates, container layers, and log files

## Kernel and Virtualization Requirements

The hypervisor components depend on Linux kernel features for hardware-assisted virtualization. The [`hypervisor/README.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/hypervisor/README.md) specifies strict kernel versioning and device accessibility rules.

### Kernel Version and KVM Support

The host must run **Linux kernel 4.11 or later** with **KVM (Kernel-based Virtual Machine)** support enabled. The hypervisor requires access to the virtualization device:

```bash

# Verify KVM device exists and is accessible

ls -la /dev/kvm

# Expected output: crw-rw-rw- root kvm /dev/kvm

```

If `/dev/kvm` is missing or permissions are incorrect, CubeSandbox cannot instantiate micro-VMs. Additionally, the runtime configuration in [`configs/single-node/cubelet.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/configs/single-node/cubelet.yaml) expects this KVM capability to be present at startup.

### Root Privileges

Root access is mandatory for installation and runtime operations. According to [`docs/guide/bare-metal-deploy.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/guide/bare-metal-deploy.md), the installation scripts must run as root to create device nodes, configure network bridges, and manage the KVM subsystem required by the `docker/Dockerfile.cube-base` foundation image.

## Container Runtime Prerequisites

Unlike pure KVM orchestrators, CubeSandbox deploys its control plane as Docker containers, necessitating a functional container engine before installation.

### Docker Engine Installation

Docker must be installed and running before executing the deployment scripts:

```bash

# Install Docker via official script (requires root)

curl -fsSL https://get.docker.com | bash
systemctl enable --now docker

```

The `docker/Dockerfile.cube-base` assumes the underlying host provides KVM access, and the orchestration layer mounts the Docker socket and `/dev/kvm` into control plane containers.

### Network Connectivity

Internet access is required during initial setup to download release packages, base VM images, and Docker container layers from the registry. Air-gapped installations would require manually mirroring these artifacts beforehand.

## Pre-Installation Verification Checklist

Validate your environment against CubeSandbox requirements using these commands prior to running the installer:

```bash

# Check kernel version (must be >= 4.11)

uname -r

# Verify KVM availability and permissions

ls -la /dev/kvm

# Confirm Docker is running

docker version

# Check available memory and disk

free -h
df -h /

```

If these checks pass, you can proceed with the one-click installer for x86_64 hosts:

```bash
curl -sL https://cnb.cool/CubeSandbox/CubeSandbox/-/git/raw/master/deploy/one-click/online-install.sh | bash

```

## Optional: ARM64 Architecture Considerations

While ARM64 hosts are supported, the documentation in [`docs/guide/bare-metal-deploy.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/guide/bare-metal-deploy.md) notes a specific hardware limitation. Some ARM64 servers lack a guest Performance Monitoring Unit (PMU), meaning **performance counters will be unavailable** inside micro-VMs. This does not prevent CubeSandbox from booting or functioning; it only affects performance profiling capabilities within guests. No additional configuration is required to work around this limitation.

## Summary

- **Hardware**: x86_64 or aarch64 Linux machine with minimum 8 GB RAM and 50 GB storage
- **Kernel**: Linux 4.11+ with accessible `/dev/kvm` device (KVM mandatory)
- **Permissions**: Root access required for installation and device management
- **Containers**: Docker Engine must be installed and running before deployment
- **Network**: Internet connectivity required for downloading packages and images
- **ARM64 Notes**: Guest performance counters may be unavailable depending on host PMU support

## Frequently Asked Questions

### Can CubeSandbox run on a virtual machine instead of bare metal?

Yes, CubeSandbox can run on nested virtualization environments, provided the underlying hypervisor exposes KVM to the guest. Ensure the virtual machine has access to `/dev/kvm` and meets the same kernel version requirements (4.11+) as documented in [`docs/guide/bare-metal-deploy.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/guide/bare-metal-deploy.md).

### Is it possible to install CubeSandbox without Docker?

No. The control plane components are exclusively distributed as Docker containers defined in the repository's Dockerfiles, including `docker/Dockerfile.cube-base`. Docker Engine is a hard dependency for the deployment scripts and runtime operation.

### What happens if my kernel is older than 4.11?

CubeSandbox's hypervisor component requires features introduced in Linux kernel 4.11. According to [`hypervisor/README.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/hypervisor/README.md), attempting to run on older kernels will fail during micro-VM initialization because the necessary KVM APIs and device handling mechanisms are unavailable.

### Does CubeSandbox support 32-bit x86 or other architectures?

No. The project only supports x86_64 (AMD64) and aarch64 (ARM64) architectures as explicitly listed in the root [`README.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/README.md) quick-start section. Other architectures like i386, RISC-V, or PowerPC are not currently supported by the KVM-based hypervisor implementation.