IncusOS Hypervisor: Running Incus on Bare Metal

If you’ve been running Proxmox or ESXi in your homelab, you’ve probably wondered if there’s a lighter, more focused alternative. Enter IncusOS—a purpose-built hypervisor operating system designed specifically for running Incus containers and virtual machines on bare metal servers.

What is IncusOS?

IncusOS is a minimal, immutable operating system based on Debian 13 that boots directly into an Incus environment. Unlike traditional Linux distributions where you install and configure Incus manually, IncusOS IS the platform—the hypervisor and the OS are one integrated unit.

Why IncusOS Exists

Running Incus on different Linux distributions creates inconsistency. Each distro has its own kernel versions, ZFS builds, networking stacks, and systemd configurations. When you run multiple hosts in a cluster, this drift becomes problematic.

IncusOS solves this by providing reproducible, consistent builds where every machine on the same version is identical—bit-for-bit. Think of it like a network switch firmware: you don’t manage the underlying OS, you just run it.

Key Features

Immutable Design

The root filesystem is read-only. There’s no package manager, no manual configuration. Updates are handled atomically through an A/B partition system:

1. New OS image downloads to the inactive partition
2. System reboots into the new version
3. If something fails, automatic rollback to the previous version

This is the same pattern used by ChromeOS, Talos, and MicroOS—proven technology for reliable updates.

Built-in Security

IncusOS doesn’t just support security features—it requires them:

• Full Disk Encryption: TPM-bound LUKS encryption protects your data at rest
• Secure Boot: Custom IncusOS certificates ensure only signed code runs
• TPM 2.0: Used for PCR measurements and encryption key binding
• Automatic Key Rotation: Yearly certificate rotation with 18-24 month overlap

The security model uses multiple TPM Platform Configuration Registers (PCRs):

• PCR 7: Secure Boot state verification
• PCR 11: Unified Kernel Image integrity
• PCR 15: Prevents TPM unlock replay attacks

Zero Maintenance

No apt update. No manual kernel upgrades. No configuration drift. IncusOS checks for updates automatically every few hours and handles everything. Your job is running workloads, not managing an operating system.

System Requirements

Component	Requirement
CPU	Modern Intel/AMD (x86_64_v3) or ARM (aarch64)
UEFI	Required, with Secure Boot support
TPM	TPM 2.0 module (hardware preferred)
RAM	Minimum 4GiB for system use
Storage	Minimum 50GiB
Network	At least one wired port

Degraded Security Mode

For homelab use, IncusOS can run in a degraded security state:

• Without Secure Boot (for broken UEFI implementations)
• With software TPM (for systems without hardware TPM)

You cannot run with both disabled—IncusOS requires at least one security layer.

Installation Process

Step 1: Generate Client Certificate

IncusOS uses certificate-based authentication. Generate a TLS certificate before downloading the ISO:

#!/bin/bash
set -e

mkdir -p incus-client-cert
cd incus-client-cert

openssl genpkey -algorithm RSA -out client.key -pkeyopt rsa_keygen_bits:4096

openssl req -new -x509 -key client.key -out client.crt -days 3650 \
  -subj "/CN=$(hostname)-incus-client"

cat client.crt client.key > client.pem

# Create browser certificate
openssl pkcs12 -export -out client.pfx -inkey client.key -in client.crt

Step 2: Download ISO

Visit the IncusOS Image Downloader, paste your client certificate (the .crt file content), and download the ISO. The download is approximately 3.5GB.

Step 3: Configure BIOS/UEFI

Before installing, configure your server’s BIOS:

Setting	Configuration
RAID Mode	Disable - Can interfere with IncusOS boot
TPM 2.0	Enable
Secure Boot	Enable “Setup Mode” for auto-enrollment, or manually load IncusOS keys
Boot Order	Set to boot from installation media

Step 4: Install

Boot from the ISO or USB drive. The installation is automated:

1. System boots into IncusOS installer
2. If using Setup Mode, keys are imported automatically
3. Installation completes
4. System reboots into IncusOS

Note: During installation, use a single disk. Adding multiple disks causes errors.

Step 5: Authenticate

Import the .pfx certificate into your browser:

Windows: Import into Current User > Personal > Certificates

macOS: Import into Keychain, set to “Always Trust”

Navigate to https://[incusos-ip]:8443 and select your certificate when prompted.

IncusOS vs Proxmox vs ESXi

IncusOS vs Proxmox VE

Aspect	IncusOS	Proxmox VE
Purpose	Minimal Incus hypervisor	Full virtualization platform
Base OS	Immutable Debian 13	Mutable Debian 12
Updates	Automatic, atomic	Manual via apt
Container Types	System + OCI	LXC containers
Web UI	Basic Incus interface	Rich management console
Learning Curve	Moderate	Easier
Resource Overhead	Minimal	Higher
Backup	External tools	Built-in
Clustering	Incus native	Integrated cluster

When to choose IncusOS: You want minimal overhead, already know Incus, or need edge deployments.

When to choose Proxmox: You’re new to virtualization, need a rich GUI, or want built-in backup solutions.

IncusOS vs VMware ESXi

Aspect	IncusOS	ESXi
Licensing	Free, open source	Free tier limited, vSphere paid
Container Support	Native (system + OCI)	Requires additional tools
Hardware Support	Modern x86_64/ARM	HCL-restricted
Management	Incus CLI + basic UI	vCenter (paid feature)
Updates	Free, automatic	Free tier manual, paid automated
Security	FDE + Secure Boot + TPM	Secure Boot only

When to choose IncusOS: You want free full features, container-native workloads, or modern security defaults.

When to choose ESXi: You’re in an enterprise environment, need vSphere features, or have approved hardware.

Storage and Networking

Storage Options

IncusOS inherits Incus’s storage flexibility:

Driver	Best For	Notes
ZFS	Recommended default	Copy-on-write, snapshots
Btrfs	Alternative COW	Less mature ZFS alternative
LVM	Traditional volumes	Thin provisioning available
Ceph	Distributed storage	For clusters
dir	Simple directory	Least features

Storage volumes are organized into types:

• container/virtual-machine: Root disks (auto-created)
• image: Unpacked images for fast launches
• custom: Persistent user volumes
• block: VM attachments only
• iso: ISO images for VM boot

Networking

IncusOS provides managed networks out of the box:

Network Type	Use Case
Bridge	Single host, public cloud (default)
OVN	Private cloud, software-defined
macvlan	Direct network interface
physical	Passthrough, uplink for OVN

Recommendation: Use the default bridge network for homelab setups. Use OVN when building a private cloud with multiple isolated networks.

Running Your First Workload

Create a Container

# Launch a container from the image catalog
incus launch images:debian/12 my-container

# Check status
incus list

# Get a shell
incus exec my-container -- bash

Create a Virtual Machine

# Launch a VM
incus launch images:ubuntu/24.04 my-vm --vm

# Configure resources
incus config set my-vm limits.cpu 2
incus config set my-vm limits.memory 4GiB

Use an OCI Container

IncusOS supports OCI (Docker) images natively:

# Run a Docker container
incus launch docker:nginx web-server

Homelab Use Cases

1. Edge Nodes and Remote Locations

Minimal overhead, atomic updates, and automatic rollback make IncusOS ideal for edge deployments where you can’t visit on-site for maintenance.

2. Development Environments

Quick snapshots and instant rollback let you experiment freely:

incus snapshot create my-container clean-state
# ... experiment ...
incus snapshot restore my-container clean-state

3. CI/CD Runners

Lightweight containers for GitLab runners, Jenkins agents, or GitHub Actions self-hosted runners with minimal host overhead.

4. Media Servers

Run Plex, Jellyfin, or Home Assistant in containers with direct hardware pass-through for transcoding.

5. Kubernetes Nodes

Deploy Talos or K3s inside IncusOS VMs for a nested Kubernetes setup with full VM isolation.

Pros and Cons Summary

Advantages

• Minimal Overhead: Purpose-built OS with no bloat
• Security by Default: FDE, Secure Boot, and TPM required
• Zero Maintenance: Automatic updates, no package management
• Consistent Clusters: Bit-for-bit identical builds
• Free and Open Source: No licensing tiers or feature gates
• Native Container Support: System containers, VMs, and OCI images

Limitations

• Hardware Requirements: Must have TPM 2.0 and UEFI Secure Boot
• No Package Manager: All workloads run through Incus
• Single Disk Install: Multi-disk setups require post-install configuration
• Newer Project: Smaller community than Proxmox/ESXi
• Basic Web UI: Less polished than Proxmox interface
• TLS Authentication: Certificate management adds complexity

Getting Started Checklist

• Verify hardware supports TPM 2.0 and UEFI Secure Boot
• Generate client TLS certificate (.crt + .key + .pfx)
• Download ISO from IncusOS Image Downloader
• Configure BIOS: disable RAID, enable TPM, set Secure Boot to Setup mode
• Create bootable USB or VM with ISO
• Boot and install (automated process)
• Import certificate into browser
• Access web UI at https://[ip]:8443
• Launch your first container or VM

Conclusion

IncusOS represents a philosophical shift in hypervisor management. Instead of managing a Linux distribution AND a hypervisor, you get a unified, immutable platform that treats the OS as an appliance. For homelab operators tired of system maintenance interrupting their workloads, this is compelling.

The trade-off is clear: you gain simplicity, security, and consistency, but lose the flexibility of a general-purpose Linux system. If your workloads fit the container/VM model—and most homelab workloads do—IncusOS is a refreshing alternative to managing yet another Linux server.

Compare that to Proxmox, which runs a full Debian underneath, requires manual updates, and includes backup tools at the cost of higher overhead. Or ESXi, which gives you enterprise features behind a paywall. IncusOS sits in a sweet spot for users who want their hypervisor to disappear into the background.

If you’re ready to try a hypervisor that manages itself, IncusOS might be exactly what your homelab needs.

---

For more information, visit the official IncusOS documentation or check out the GitHub repository.