Skip to content

build.md

Latest commit

 

History

History
202 lines (153 loc) · 6.13 KB

build.md

File metadata and controls

202 lines (153 loc) · 6.13 KB

Build from source

Prerequisites

Windows

  • Windows 10/11 with Windows Hypervisor Platform enabled
  • Visual Studio 2022+ with C++20 support
  • CMake 3.21+
  • WSL2 or a Linux environment (for building disk images)

macOS

  • macOS 13+ on Apple Silicon (arm64) or Intel (x86_64)
  • Xcode 15+ or Xcode Command Line Tools with Swift 5.9+
  • CMake 3.21+
  • Docker (recommended for building guest images)

Linux

  • A Linux host with /dev/kvm available (kvm group on most distros)
  • x86_64 or arm64 (validated on Debian 11+, Ubuntu 20.04+, Raspberry Pi 5)
  • GCC 12+ / Clang 15+ with C++20 support
  • CMake 3.21+ and Ninja
  • The following libraries (install via apt or equivalent):
    • pkg-config
    • libavcodec-dev libavutil-dev libswresample-dev (FFmpeg)
    • libopus-dev
    • libssl-dev
    • libcurl4-openssl-dev
    • libyuv-dev
    • libdatachannel-dev — or let CMake fetch it automatically with -DTENBOX_FETCH_LIBDATACHANNEL=ON (default)
  • Docker (recommended for building guest images)

Note: there is no native Linux GUI manager. On Linux the build produces tenboxd, tenbox, and tenbox-vm-runtime.

Build

Windows

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

Artifacts in build/:

Executable Description
tenbox-manager.exe GUI manager — the main entry point
tenbox-vm-runtime.exe VM runtime process — launched by the manager

macOS

./scripts/build-macos.sh --release

Artifacts in build/:

Artifact Description
TenBox.app Native macOS manager application bundle
tenbox-vm-runtime VM runtime process bundled into the app
TenBox_<version>_<arch>.zip Sparkle update ZIP generated by the build script

Linux

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

Artifacts in build/:

Executable Description
tenboxd Host daemon — VM lifecycle, cloud tunnel, remote desktop
tenbox CLI client
tenbox-vm-runtime KVM-backed VM runtime — one process per running VM

Static release build

Production debs are built inside packaging/build-base/Dockerfile.bullseye, which bakes in static FFmpeg/libx264/libopus/libyuv/libcurl/OpenSSL under /opt/tenbox-deps. To reproduce locally:

cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release \
    -DTENBOX_STATIC_FFMPEG=ON \
    -DTENBOX_STATIC_RUNTIME=ON
cmake --build build

For the full deb packaging flow see packaging/debian/build-deb.sh.

Prepare VM images

Use the Docker wrapper to build images (requires Docker). Several rootfs flavors are available — chromium, openclaw, qwenpaw, and hermes:

# x86_64 images
./scripts/docker/build.sh x86_64 kernel
./scripts/docker/build.sh x86_64 initramfs
./scripts/docker/build.sh x86_64 rootfs-chromium   # or rootfs-openclaw / rootfs-qwenpaw / rootfs-hermes

# arm64 images (for macOS Apple Silicon or arm64 Linux)
./scripts/docker/build.sh arm64 kernel
./scripts/docker/build.sh arm64 initramfs
./scripts/docker/build.sh arm64 rootfs-chromium    # or rootfs-openclaw / rootfs-qwenpaw / rootfs-hermes

The rootfs scripts support incremental builds with a checkpoint system:

./scripts/docker/build.sh x86_64 rootfs-chromium --status       # Show build progress
./scripts/docker/build.sh x86_64 rootfs-chromium --list-steps   # List all build steps
./scripts/docker/build.sh x86_64 rootfs-chromium --force        # Force full rebuild

Match the architecture to the host: use x86_64 images on Windows and Intel macOS / Linux PCs, and arm64 images on Apple Silicon macOS and arm64 Linux boards.

Run

Windows

build/tenbox-manager.exe

macOS

open build/TenBox.app

Linux (via tenboxd daemon)

# Start the daemon (dev mode — no sudo, uses $XDG_RUNTIME_DIR socket)
./build/tenboxd --data-dir /tmp/tenbox-dev

# In another terminal: check KVM support and create/start a VM
tenbox doctor
tenbox vm create --name my-vm \
    --kernel build/Image \
    --initrd build/initramfs-x86_64.cpio.gz \
    --disk build/rootfs.qcow2 \
    --memory 1024 --cpus 2
tenbox vm start <id>
tenbox vm console <id>

Linux (direct runtime, dev/debug only)

The runtime can also be launched directly without the daemon:

build/tenbox-vm-runtime \
    --kernel build/Image \
    --initrd build/initramfs-x86_64.cpio.gz \
    --disk build/rootfs.qcow2 \
    --net

Guest image defaults

Guest images built with the rootfs-chromium (and other) scripts:

Setting Default Override
Root password tenbox ROOT_PASSWORD env var
User account tenbox / tenbox USER_NAME / USER_PASSWORD env var
Hostname tenbox-vm —
Desktop XFCE 4 (LightDM) —
Disk size 100 GB qcow2 ROOTFS_SIZE variable
Distro Debian Trixie —
Pre-installed Chromium, SPICE vdagent, qemu-guest-agent —

Dependencies

Fetched automatically by the build system (CMakeLists.txt / src/daemon/CMakeLists.txt):

Library Use
zlib qcow2 zlib compressed cluster decompression
zstd qcow2 zstd compressed cluster decompression
lwIP Lightweight TCP/IP stack for NAT networking
nlohmann/json VM manifest (vm.json) serialization
libuv Cross-platform event loop (high-res timers)
libdatachannel WebRTC DataChannels for remote desktop (Linux daemon)
Sparkle macOS app update framework
WinSparkle Windows app update framework
FFmpeg (libavcodec/libavutil/libswresample) H.264 video encoding for remote desktop (Linux daemon)
libopus Opus audio encoding for remote desktop (Linux daemon)
libyuv BGRA→YUV420P pixel conversion fast path (Linux daemon)
libcurl + OpenSSL Cloud tunnel TLS, LLM proxy forwarding, apt self-update (Linux daemon)