VMM · v0.3.4 · GPL v3

TenBox
跨平台虚拟机
监视器

基于 C++ 构建的轻量级 VMM，支持 Windows（WHVP）和 macOS Apple Silicon（Hypervisor Framework），可运行完整的 Linux 桌面环境，具备硬件加速虚拟化、GPU 显示、音频和剪贴板集成。

112 Stars
22 Forks
C++ Language
GPL v3 License
查看源码 快速开始
TenBox Architecture
Manager Process
tenbox-manager.exe TenBox.app Win32 UI SwiftUI Clipboard Audio
↕
IPC Protocol v1
Named Pipe (Win) Unix Socket (macOS)
↕
VM Runtime Process [per VM]
WHVP / HVF x86_64 / arm64 VirtIO MMIO lwIP NAT vdagent guest-agent
Core Features

完整的虚拟化功能栈

从底层 hypervisor 接口到高层 GUI 管理，TenBox 提供一体化的 Linux 虚拟化体验

🖥️

跨平台 Hypervisor 后端

Windows 使用 Windows Hypervisor Platform（WHVP），macOS Apple Silicon 使用 Hypervisor Framework（HVF），充分利用硬件加速虚拟化能力。

WHVP HVF 硬件加速
🎮

GPU 显示输出

基于 virtio-gpu 和 SPICE 协议实现 GPU 显示，支持可调整大小的显示窗口，在虚拟机内获得完整的图形界面体验。

virtio-gpu SPICE 可缩放窗口
🔊

音频输出集成

virtio-snd 音频流通过 Windows 的 WASAPI 和 macOS 的 CoreAudio 传输到宿主机，虚拟机音频无缝播放。

virtio-snd WASAPI CoreAudio
📁

共享文件夹 & 剪贴板

通过 virtiofs（virtio-fs）实现宿主机与虚拟机的目录共享，支持只读模式。SPICE vdagent 协议实现双向剪贴板同步。

virtiofs 只读模式 双向剪贴板
💾

灵活的磁盘镜像支持

同时支持 qcow2 和 raw 格式磁盘镜像，qcow2 支持 zlib 和 zstd 压缩簇，以及写时复制（copy-on-write）功能。

qcow2 raw zlib/zstd CoW
🌐

NAT 网络 & 端口转发

内置 DHCP 服务器，基于 lwIP 的 TCP/UDP NAT 代理，支持 ICMP 中继。可将虚拟机 TCP 服务暴露到宿主机端口，灵活配置端口转发。

lwIP DHCP 端口转发 NAT
⚙️

完整 VirtIO MMIO 设备

实现完整的 VirtIO MMIO 设备栈：block、network、GPU、input、serial、sound 和 filesystem，满足 Linux 客户机的各类 I/O 需求。

blk net gpu input snd fs
🖱️

原生 GUI 管理器

Windows 采用 Win32 原生 GUI 管理器，macOS 采用 SwiftUI/AppKit 管理器，提供创建、编辑、启动、停止、重启和删除虚拟机的完整图形界面。

Win32 SwiftUI 多 VM 管理
🤖

客户机代理集成

集成 qemu-guest-agent 协议处理器，实现虚拟机生命周期管理，支持从宿主机安全地控制和监控客户机系统状态。

qemu-guest-agent 生命周期管理
Architecture

双进程设计架构

TenBox 采用双进程设计：管理进程负责 UI 展示，为每个虚拟机单独启动一个运行时进程。两者通过平台专属 IPC 通道通信，实现进程隔离和稳定性保障。

  • 🖥️

    tenbox-manager / TenBox.app

    持有 UI 界面，管理虚拟机列表，处理剪贴板、音频、共享文件夹和系统更新

  • ⟺

    IPC 通道

    Windows 使用 Named Pipe，macOS 使用 Unix Domain Socket 进行跨进程通信

  • ⚙️

    tenbox-vm-runtime（每个 VM 一个）

    运行 hypervisor 后端、客户机机器模型、VirtIO 设备、网络栈，完全独立于管理进程

tenbox-vm-runtime CLI
# 直接通过 CLI 启动虚拟机（通常由管理器调用）

$ build/tenbox-vm-runtime \
  --kernel build/Image \
  --initrd build/initramfs.cpio.gz \
  --disk build/rootfs.qcow2 \
  --memory 4096 \
  --cpus 4 \
  --net \
  --forward 2222:22 \
  --share workspace:/home/user/work

[ OK ] TenBox VM Runtime started
[ OK ] WHVP backend initialized
[ OK ] VirtIO devices ready: blk, net, gpu, snd, fs
[ OK ] NAT network: 10.0.2.15/24 via 10.0.2.2
[ OK ] Port forward: host:2222 → guest:22
Platforms

双平台原生支持

针对 Windows 和 macOS Apple Silicon 分别优化，充分发挥各平台的原生虚拟化能力

Windows
Windows 10/11 · x86_64
  • 虚拟化后端 WHVP
  • GUI 框架 Win32 Manager
  • IPC 通道 Named Pipe
  • 音频后端 WASAPI
  • 客户机架构 x86_64
  • 构建工具 CMake + Ninja
  • 编译器 MSVC / VS2022+
macOS Apple Silicon
macOS 13+ · arm64
  • 虚拟化后端 Hypervisor Framework
  • GUI 框架 SwiftUI / AppKit
  • IPC 通道 Unix Domain Socket
  • 音频后端 CoreAudio
  • 客户机架构 aarch64
  • 构建脚本 build-macos.sh
  • Swift 版本 Swift 5.9+ / Xcode 15+
Quick Start

构建与安装指南

根据你的操作系统选择对应的构建方式

1

系统要求

确保已启用 Windows Hypervisor Platform，并安装 Visual Studio 2022+（含 C++20 支持）和 CMake 3.21+。

PowerShell 
# 启用 Windows Hypervisor Platform
Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform
2

克隆仓库

bash 
git clone https://github.com/78/tenbox.git
cd tenbox
3

构建项目

bash 
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build

构建产物在 build/ 目录：tenbox-manager.exe（GUI 管理器）和 tenbox-vm-runtime.exe（VM 运行时）

4

启动管理器

bash 
build/tenbox-manager.exe
1

系统要求

需要 macOS 13+ 的 Apple Silicon 设备，安装 Xcode 15+（含 Swift 5.9+），CMake 3.21+，以及 Docker（用于构建客户机镜像）。

2

克隆并构建

bash 
git clone https://github.com/78/tenbox.git
cd tenbox
./scripts/build-macos.sh --release

构建产物：TenBox.app、tenbox-vm-runtime 和更新包 TenBox_<version>_<arch>.zip

3

启动应用

bash 
open build/TenBox.app
1

构建 x86_64 镜像（Windows 宿主机）

bash 
# 构建内核、initramfs 和含 Chromium 的根文件系统
./scripts/docker/build.sh x86_64 kernel
./scripts/docker/build.sh x86_64 initramfs
./scripts/docker/build.sh x86_64 rootfs-chromium
2

构建 arm64 镜像（macOS Apple Silicon 宿主机）

bash 
./scripts/docker/build.sh arm64 kernel
./scripts/docker/build.sh arm64 initramfs
./scripts/docker/build.sh arm64 rootfs-chromium
3

管理构建进度（支持断点续建）

bash 
# 查看构建进度
./scripts/docker/build.sh x86_64 rootfs-chromium --status

# 列出所有构建步骤
./scripts/docker/build.sh x86_64 rootfs-chromium --list-steps

# 强制完整重新构建
./scripts/docker/build.sh x86_64 rootfs-chromium --force
CLI Reference

VM Runtime 命令行参数

运行时进程通常由管理器自动调用，也可手动直接运行

参数 说明 默认值
--kernel <path> Linux 内核镜像路径（vmlinuz 或 Image）必填 —
--initrd <path> initramfs 路径 —
--disk <path> raw 或 qcow2 格式磁盘镜像路径 —
--cmdline <str> 内核命令行参数 —
--memory <MB> 虚拟机内存大小（MB） 256
--cpus <N> 虚拟 CPU 数量（最大 128） 1
--net 启用 virtio-net NAT 网络 禁用
--forward H:G 将宿主机端口 H 转发到虚拟机端口 G（可重复使用） —
--share TAG:PATH[:ro] 通过 virtiofs 共享宿主机目录（可重复使用，支持 :ro 只读） —
--interactive on|off 启用串口控制台 I/O on
--vm-id <id> VM 实例标识符 default
--control-endpoint 管理器通信 IPC 端点（Windows: Named Pipe，macOS: Unix socket 路径） —
Networking

用户态 NAT 网络栈

TenBox 内置基于 lwIP 的用户态 NAT 网络实现，无需宿主机 root 权限。虚拟机通过 DHCP 自动获取 IP，可访问外部网络并接收端口转发。

  • 内置 DHCP 服务器，自动分配 IP 地址
  • TCP 出站通过 lwIP TCP 栈代理到宿主机 socket
  • UDP 直接由宿主机网络层中继（DNS、NTP 等）
  • ICMP 通过 raw socket 中继（需要相应权限）
  • 可配置端口转发，将虚拟机服务暴露到宿主机
NAT 网络地址规划
地址 角色
10.0.2.2 网关（宿主机）
10.0.2.15 虚拟机 IP（DHCP 分配）
8.8.8.8 DNS 服务器
TCP 通过 lwIP TCP 栈代理到宿主机 socket
UDP 直接由宿主机网络层中继
ICMP 通过 raw socket 中继（需权限）
FWD 端口转发，如 host:2222 → guest:22
Guest Defaults

预构建客户机镜像配置

由 scripts 中的 make-rootfs-chromium.sh 脚本构建，基于 Debian Bookworm，预装常用工具

操作系统
Debian Bookworm（稳定版），XFCE 4 桌面环境，LightDM 显示管理器
默认账户
root 密码 tenbox，普通用户 openclaw，密码同用户名
磁盘配置
20 GB qcow2 格式磁盘，可通过 ROOTFS_SIZE 变量自定义大小
主机名
默认主机名 tenbox-vm，可在构建时通过环境变量覆盖
预装软件
Google Chrome、Node.js 22、SPICE vdagent（剪贴板）、qemu-guest-agent（生命周期管理）
可定制项
ROOT_PASSWORD、USER_NAME、USER_PASSWORD 均可通过环境变量在构建时覆盖
ENV 可配置
Dependencies

核心依赖库

由构建系统自动拉取，无需手动安装

zlib
qcow2 zlib 压缩簇解压缩，madler/zlib
自动获取
zstd
qcow2 zstd 压缩簇解压缩，facebook/zstd
自动获取
lwIP
NAT 网络使用的轻量级 TCP/IP 协议栈，lwip-tcpip/lwip
自动获取
nlohmann/json
VM 配置清单（vm.json）的序列化与反序列化
自动获取
Sparkle
macOS 应用自动更新框架，仅 manager-macos 使用，sparkle-project/Sparkle
自动获取