BitBuilder Hypervisor

Visit the Website & Documentation →

---

Overview

BitBuilder Hypervisor is a next-generation hypervisor system that leverages the full power of systemd's virtualization and containerization capabilities to provide secure, isolated multi-tenant environments. Each tenant's configuration is version-controlled in Git repositories, enabling true infrastructure-as-code workflows with automatic provisioning and updates at boot time.

---

Key Features

Feature	Description	Benefits
Git-Ops Native	All configurations stored in Git repositories, pulled at boot time	Version control, atomic deployments, rollback capability
Multi-Tenant Isolation	Complete separation between tenants using systemd's security features	Zero trust architecture, cryptographic boundaries
Immutable Host OS	Read-only host system with all changes applied through git-controlled overlays	Eliminates configuration drift, enhanced security
Declarative Configuration	Everything defined as code, no manual configuration required	Infrastructure as Code, automated provisioning
Zero-Trust Architecture	Each tenant runs in completely isolated environments	Hardware-backed security, namespace isolation
Dynamic Provisioning	Automatic tenant setup and teardown based on git repository state	Scalable operations, automated lifecycle management

---

Core Technologies

Systemd Components

Component	Purpose	Features
systemd-boot	UEFI boot manager for secure boot chain	Secure boot, UKI support, boot management
systemd-import-generator	Automatic EFI image download and boot management	DDI support, automatic updates, verification
systemd-vmspawn	Lightweight VM spawning for tenant isolation	Hardware virtualization, resource isolation
systemd-nspawn	Container spawning for application isolation	Namespace isolation, security boundaries
systemd-networkd	Network configuration and isolation	Software-defined networking, tenant isolation
systemd-homed	User home directory management with encryption	Encrypted homes, hardware-backed auth
Portable Services	Self-contained service images	Application portability, dependency isolation
sysext/confext	System and configuration extensions via overlayfs	Layered filesystems, immutable updates
Varlink	IPC protocol for service communication	Type-safe IPC, service discovery

Linux Userspace API Specifications

BitBuilder Hypervisor implements and adheres to the Linux Userspace API Specifications:

Specification	Purpose	Implementation
Configuration Files Specification	Standardized locations for configuration management	/etc, /usr/lib, /run hierarchy
Discoverable Partitions Specification (DPS)	Auto-discovery of partition semantics	GPT partition type GUIDs
Discoverable Disk Image (DDI)	Self-describing system images	Unified disk images with metadata
Extension Image	Layered extensions to base images	Overlay filesystem extensions
├── sysext	System Extension Images overlaid on /usr/ and /opt/	Runtime system extensions
└── confext	Configuration Extension Images overlaid on /etc/	Runtime configuration extensions
Unified Kernel Image (UKI)	Combined kernel, initrd, and boot configuration	Single-file bootable images
Boot Loader Specification (BLS)	Standardized boot configuration	systemd-boot integration

---

Architecture Highlights

Component	Description	Technology
Immutable Host	The host OS boots from an immutable image downloaded via systemd-import-generator	DDI images, systemd-import
Tenant Isolation	Each tenant runs in isolated systemd-vmspawn/nspawn instances	Hardware virtualization, namespaces
Git-Based Configuration	All tenant configurations pulled from dedicated Git repositories	Git-ops, declarative config
Dynamic Mount Generation	Custom systemd generators create tenant-specific mount points	systemd generators, overlay mounts
Layered Extensions	System capabilities extended through sysext/confext layers	Extension images, overlayfs

---

Tenant Management

Each tenant in the BitBuilder Hypervisor follows a complete lifecycle management approach:

graph LR
    A[Git Repository] --> B[Discovery]
    B --> C[Provisioning]
    C --> D[VM/Container]
    D --> E[Updates]
    E --> A

    style A fill:#e3f2fd
    style B fill:#f3e5f5
    style C fill:#e8f5e8
    style D fill:#fff3e0
    style E fill:#fce4ec

Loading

Tenant Lifecycle

Step	Process	Details
1	Dedicated Git Repository	Each tenant has its own configuration repository
2	Automatic Provisioning	Boot-time provisioning via setup-tenant@<tenantname>.service
3	Isolated Execution	Runs in systemd-vmspawn or systemd-nspawn instances
4	Custom Extensions	Can have tenant-specific sysext/confext layers
5	Network Isolation	Complete network isolation via systemd-networkd
6	Automatic Updates	Updates automatically when Git repository changes

---

Boot Process

sequenceDiagram
    participant UEFI as UEFI Boot
    participant Boot as systemd-boot
    participant Import as systemd-import-gen
    participant Host as Host OS
    participant Git as Git Sync
    participant Discovery as Tenant Discovery
    participant Provision as Tenant Provisioning

    UEFI->>Boot: Load boot configuration
    Boot->>Import: Download and verify EFI image
    Import->>Host: Start immutable host OS
    Host->>Git: Pull system configurations
    Git->>Discovery: Scan for tenant configs
    Discovery->>Provision: For each tenant:
    Note over Provision: • Clone/pull tenant repo<br/>• Mount tenant directories<br/>• Apply sysext/confext layers<br/>• Start VM/container<br/>• Execute provisioning units

Loading

Boot Sequence Details

Phase	Component	Action	Result
1	UEFI Boot	systemd-boot loads the boot configuration	Secure boot validation
2	Image Import	systemd-import-generator downloads and verifies the host EFI image	DDI image verification
3	Host Boot	Immutable host OS starts with minimal services	Base system ready
4	Git Sync	System-level configurations pulled from Git repositories	Configuration sync
5	Tenant Discovery	Scan for tenant configurations in Git	Tenant enumeration
6	Tenant Provisioning	For each discovered tenant: provision resources	Multi-tenant setup

---

Configuration Structure

Host Filesystem Hierarchy

/
├── /boot/                              # Boot partition (read-only)
│   └── efi/                            # EFI System Partition
├── /etc/                               # Host configuration (overlayfs from confext)
│   ├── systemd/
│   │   ├── system/                     # System units
│   │   │   ├── tenant@.service         # Tenant instantiation template
│   │   │   ├── tenant-infra@.service   # Infrastructure manager template
│   │   │   └── tenant-network@.service # Network manager template
│   │   ├── network/                    # Network configuration templates
│   │   └── system-generators/          # Custom systemd generators
│   │       ├── tenant-generator        # Discovers and instantiates tenants
│   │       └── mount-generator         # Generates mount units for tenants
│   └── voa/                            # Verification of OS Artifacts
│       └── bitbuilder/image/default/openpgp/
├── /usr/                               # Vendor OS (read-only, overlayfs from sysext)
│   ├── lib/
│   │   ├── extensions/                 # System-wide extension images
│   │   │   ├── base-tools.sysext.raw
│   │   │   ├── monitoring.sysext.raw
│   │   │   └── security.confext.raw
│   │   ├── systemd/
│   │   │   ├── system/                 # Vendor systemd units
│   │   │   └── network/                # Vendor network templates
│   │   └── bitbuilder/
│   │       ├── templates/              # Tenant template repositories
│   │       │   ├── tenant-infra/
│   │       │   ├── tenant-machine/
│   │       │   ├── tenant-container/
│   │       │   └── tenant-homed/
│   │       └── generators/             # BitBuilder systemd generators
│   └── share/
│       └── voa/                        # Vendor verification keys
├── /var/                               # Persistent variable data
│   ├── lib/
│   │   ├── machines/                   # systemd-nspawn containers
│   │   ├── tenants/                    # Tenant persistent storage
│   │   │   └── <tenant-id>/
│   │   │       ├── infra/              # Infrastructure VM
│   │   │       │   ├── rootfs/         # Infrastructure manager root
│   │   │       │   └── config.git/     # Cloned infra config repo
│   │   │       ├── machines/           # Tenant VMs (systemd-vmspawn)
│   │   │       │   └── <machine-id>/
│   │   │       │       ├── disk.raw    # VM disk image
│   │   │       │       └── config/     # Machine-specific config
│   │   │       ├── containers/         # Tenant containers (systemd-nspawn)
│   │   │       │   └── <container-id>/
│   │   │       │       └── rootfs/     # Container root filesystem
│   │   │       ├── extensions/         # Tenant-specific extensions
│   │   │       │   ├── sysext/         # System extensions
│   │   │       │   └── confext/        # Configuration extensions
│   │   │       ├── network/            # Network namespace configs
│   │   │       └── homed/              # User home directories
│   │   └── extensions.mutable/         # Mutable overlay configuration
│   │       ├── etc/                    # -> /var/lib/tenants/<id>/overlay/etc
│   │       └── usr/                    # -> /var/lib/tenants/<id>/overlay/usr
│   └── cache/
│       └── tenants/                    # Cached tenant images
└── /run/                               # Runtime data (tmpfs)
    ├── systemd/
    │   └── generator/                  # Generated units at boot
    └── tenants/                        # Runtime tenant data

---

Security Model

Core Security Principles

Security Layer	Technology	Implementation	Benefit
Immutable Infrastructure	DDI, overlayfs	Host OS cannot be modified at runtime	Eliminates configuration drift
Git-Only Changes	Git-ops workflow	All modifications through Git commits	Audit trail, rollback capability
Tenant Isolation	systemd security	Complete separation using multiple boundaries	Defense in depth
Encrypted Storage	systemd-homed, LUKS	Optional encryption for tenant data	Data protection at rest
Secure Boot	UEFI, TPM	Full secure boot chain support	Boot integrity verification

Multi-Layer Isolation

graph TB
    subgraph "Tenant A"
        VM1[VM Instance]
        NS1[Container]
    end

    subgraph "Tenant B"
        VM2[VM Instance]
        NS2[Container]
    end

    subgraph "Security Boundaries"
        PID[PID Namespaces]
        NET[Network Isolation]
        MOUNT[Mount Namespaces]
        USER[User Namespaces]
        CGROUP[Resource Limits]
        CAP[Capabilities]
        MAC[SELinux/AppArmor]
    end

    VM1 --- PID
    VM2 --- PID
    NS1 --- NET
    NS2 --- NET
    VM1 --- MOUNT
    VM2 --- USER
    NS1 --- CGROUP
    NS2 --- CAP
    VM1 --- MAC

Loading

---

Git Repository Structure

System Repository

bitbuilder-system/
├── .gitops/
│   └── config.yaml                    # Git-ops configuration
├── generators/                        # Custom systemd generators
│   ├── tenant-generator               # Tenant discovery and instantiation
│   └── mount-generator                # Extension mount generation
├── units/                             # System service units
│   ├── tenant@.service                # Tenant instantiation template
│   ├── tenant-infra@.service          # Infrastructure manager template
│   └── tenant-network@.service        # Network setup template
├── network/                           # Network configuration templates
│   ├── 10-tenant-bridge.netdev
│   ├── 10-tenant-bridge.network
│   ├── 20-wg-tenant.netdev
│   ├── 20-wg-tenant.network
│   ├── 30-vxlan-tenant.netdev
│   └── 30-vxlan-tenant.network
├── extensions/                        # System-wide extensions
│   ├── base-tools.sysext.raw
│   ├── monitoring.sysext.raw
│   └── security.confext.raw
└── tenants/                           # Tenant registry
    └── registry.json                  # Active tenants list

Tenant Configuration Repository

tenant-<name>/
├── metadata.json                     # Tenant metadata and requirements
├── infrastructure/                   # Infrastructure manager config
│   ├── config.yaml                   # Infra manager configuration
│   └── resource-limits.yaml          # Resource quotas
├── network/                          # Network configuration
│   ├── topology.yaml                 # Network topology definition
│   ├── wireguard/                    # VPN configurations
│   └── firewall/                     # Firewall rules
├── machines/                         # VM definitions
│   └── <machine-name>/
│       ├── config.yaml               # VM configuration
│       └── cloud-init/               # Cloud-init data
├── containers/                       # Container definitions
│   └── <container-name>/
│       ├── config.yaml               # Container configuration
│       └── rootfs-overlay/           # Filesystem overlays
├── extensions/                       # Tenant-specific extensions
│   ├── sysext/                       # System extensions
│   │   └── *.sysext.raw
│   └── confext/                      # Configuration extensions
│       └── *.confext.raw
├── services/                         # Portable service definitions
│   └── *.portable.raw
├── users/                            # User definitions
│   └── <username>/
│       └── homed-config.json         # systemd-homed configuration
└── scripts/
    ├── pre-provision.sh              # Pre-provisioning script
    ├── post-provision.sh             # Post-provisioning script
    └── health-check.sh               # Health monitoring script

Template Repositories

BitBuilder provides standard templates for creating new tenants and resources:

Template	Purpose	Technology	Use Case
tenant-infra-template	Infrastructure manager VM template	systemd-vmspawn	Tenant orchestration
tenant-machine-template	VM instance template	systemd-vmspawn	Application VMs
tenant-container-template	Container template	systemd-nspawn	Containerized apps
tenant-homed-template	User home directory template	systemd-homed	User environments
sysext-template	System extension template	Extension images	System augmentation
confext-template	Configuration extension template	Extension images	Config management

See STACK.md for detailed template specifications and implementation details.

---

Advantages

Advantage	Description	Impact
Version Control	All infrastructure changes tracked in Git	Complete change history, diff capabilities
Rollback Capability	Easy reversion to previous configurations	Zero-downtime rollbacks, safety net
Audit Trail	Complete history of all changes	Compliance, security, accountability
Declarative Management	Define desired state, not procedures	Reduced complexity, predictable outcomes
Scalability	Add/remove tenants by updating Git repositories	Horizontal scaling, resource optimization
Consistency	Identical deployments from the same Git commits	Reproducible infrastructure, dev/prod parity
Testing	Test configurations in staging before production	Risk reduction, validation workflows

---

Use Cases

Use Case	Industry	Benefits	Technology Stack
Multi-Tenant Hosting	Cloud Providers	Secure isolation for multiple customers	systemd-vmspawn, networking
Development Environments	Software Development	Reproducible developer workspaces	systemd-nspawn, git-ops
Edge Computing	IoT, CDN	Lightweight virtualization for edge deployments	Minimal footprint, secure boot
CI/CD Infrastructure	DevOps	Dynamic test environments	Automated provisioning, git integration
Application Isolation	Security	Run untrusted workloads safely	Namespace isolation, capabilities
Compliance Environments	Finance, Healthcare	Auditable, immutable infrastructure	Immutable OS, audit trails

---

Quick Start

Creating Your First Tenant

# 1. Create a tenant repository structure
mkdir -p tenant-example/{infrastructure,network,machines,extensions}

# 2. Create metadata.json
cat > tenant-example/metadata.json <<EOF
{
  "tenant": {
    "id": "tenant-001",
    "name": "Example Tenant",
    "type": "vm",
    "enabled": true
  },
  "resources": {
    "cpu": 2,
    "memory": "4G",
    "storage": "50G"
  },
  "network": {
    "mode": "isolated-bridge",
    "interfaces": [
      {
        "name": "eth0",
        "type": "bridge",
        "bridge": "br-tenant001"
      }
    ]
  },
  "extensions": [],
  "services": [],
  "security": {
    "isolation": "namespace"
  }
}
EOF

# 3. Initialize Git and configure remote
cd tenant-example
git init && git add . && git commit -m "Add example tenant"
git remote add origin <YOUR_TENANT_REPO_URL>
git push -u origin main

# 4. The tenant will be automatically discovered and provisioned

---

Requirements

Hardware Requirements

Component	Minimum	Recommended	Purpose
UEFI Firmware	UEFI 2.0+	UEFI 2.8+ with Secure Boot	Boot integrity, hardware security
systemd Version	258+	260+	All virtualization features enabled
Git Client	2.30+	Latest stable	Repository operations, authentication
Network Connectivity	Basic	High-bandwidth	Git repository access, updates
Resources	8GB RAM, 100GB storage	32GB RAM, 1TB NVMe SSD	Tenant VMs/containers

---

Documentation

Document	Description	Audience
Technical Design	Detailed design documentation	Architects, Developers
Architecture	System architecture overview	Technical Leaders, Ops

---

Project Status

This project is currently under active development. The architecture is designed and documented, with reference implementations being built. Contributions and feedback are welcome.

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: See the website for full documentation