Prerequisites¶

Before installing Clincus, verify that your system meets the requirements below.

System Requirements¶

Requirement	Minimum	Notes
Operating system	Linux	Ubuntu 22.04+, Debian 12+, Fedora 38+, Arch, Alpine
Kernel	5.15+	Required for UID-shifting (idmapped mounts)
RAM	4 GiB	8 GiB recommended for running multiple sessions
Disk	10 GiB free	The container image is ~3–4 GiB compressed
Architecture	amd64 or arm64

macOS

Clincus runs on macOS via Colima or Lima. See the macOS section below.

Install Incus¶

Clincus requires Incus, the community fork of LXD.

Ubuntu / Debian¶

# Add the Zabbly repository (recommended)
curl -fsSL https://pkgs.zabbly.com/key.asc | sudo gpg --dearmor -o /etc/apt/keyrings/zabbly.gpg
echo "deb [signed-by=/etc/apt/keyrings/zabbly.gpg] https://pkgs.zabbly.com/incus/stable $(lsb_release -sc) main" \
  | sudo tee /etc/apt/sources.list.d/zabbly-incus-stable.list
sudo apt update && sudo apt install incus

Fedora / RHEL¶

sudo dnf install incus

Arch Linux¶

sudo pacman -S incus

Alpine Linux¶

sudo apk add incus

Initialize Incus¶

After installation, run the interactive setup:

sudo incus admin init

For a quick non-interactive setup (suitable for development):

sudo incus admin init --minimal

Add your user to the incus-admin group so you can manage containers without sudo:

sudo usermod -aG incus-admin $USER
newgrp incus-admin   # apply without logging out

Group membership

The group change takes effect in new shell sessions. Run newgrp incus-admin or log out and back in before proceeding.

Verify Incus Works¶

incus list

Expected output (empty list, no errors):

+------+-------+------+------+------+-----------+
| NAME | STATE | IPV4 | IPV6 | TYPE | SNAPSHOTS |
+------+-------+------+------+------+-----------+

If you see a permission error, ensure you are in the incus-admin group (see above).

macOS via Colima / Lima¶

Clincus can run on macOS by using a Linux VM that has Incus installed.

With Colima¶

# Install Colima
brew install colima

# Start a VM (uses QEMU under the hood)
colima start --vm-type qemu

# SSH into the VM and install Incus
colima ssh
# (inside VM) follow Ubuntu/Debian steps above

With Lima¶

# Install Lima
brew install lima

# Create a VM using an Ubuntu template
limactl create --name=incus template://ubuntu
limactl start incus

# Shell into the VM
limactl shell incus
# (inside VM) follow Ubuntu/Debian steps above

UID shifting on macOS VMs

Colima and Lima use virtiofs or 9p for file sharing, which may not support idmapped mounts. Set disable_shift = true in ~/.config/clincus/config.toml if you see mount errors:

[incus]
disable_shift = true