System Requirements for CubeSandbox: Complete Hardware and Software Prerequisites

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

# 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 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, 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:

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

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

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 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.

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, 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 quick-start section. Other architectures like i386, RISC-V, or PowerPC are not currently supported by the KVM-based hypervisor implementation.

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