Visit the Website & Documentation →
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.
| 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 |
| 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 |
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 |
| 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 |
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
| 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 |
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
| 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 |
/
├── /boot/ # Boot partition (read-only)
│ └── efi/ # EFI System Partition
├── /etc/ # Host configuration (overlayfs from confext)
│ ├── systemd/
│ │ ├── system/ # System units
│ │ │ ├── [email protected] # Tenant instantiation template
│ │ │ ├── [email protected] # Infrastructure manager template
│ │ │ └── [email protected] # 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 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 |
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
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
│ ├── [email protected] # Tenant instantiation template
│ ├── [email protected] # Infrastructure manager template
│ └── [email protected] # 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 listtenant-<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 scriptBitBuilder 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.
| 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 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 |
# 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| 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 |
| Document | Description | Audience |
|---|---|---|
| Technical Design | Detailed design documentation | Architects, Developers |
| Architecture | System architecture overview | Technical Leaders, Ops |
This project is currently under active development. The architecture is designed and documented, with reference implementations being built. Contributions and feedback are welcome.
This project is licensed under the MIT License - see the LICENSE file for details.
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.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: See the website for full documentation