Running Incus Containers in Macpine

Overview

Incus is a modern system container and VM manager. While it doesn't run natively on macOS, macpine provides an excellent lightweight virtualization layer to run Incus, enabling you to manage containers on your Mac with near-native performance.

This guide will walk you through setting up an Incus server inside a macpine VM and connecting to it with the incus client on your host.

Prerequisites

1. Install QEMU and macpine:

   brew install qemu macpine

2. Install the Incus client:

   brew install incus

1. Launch the Incus VM

Create a macpine instance that will host the Incus server. We need to forward port 8443, which is the default port for the Incus remote API.

# We'll name the instance 'incus', forward SSH to port 223, and API to 8443
alpine launch --name incus --ssh 223 --port 8443

macpine will automatically select the correct architecture (aarch64/x86_64) based on your Mac.

2. Install the Incus Daemon

Next, execute a script inside the VM to install and configure the Incus daemon.

# Download the installation script inside the VM
alpine exec incus -- "hwclock -s; wget https://raw.githubusercontent.com/beringresearch/macpine/main/scripts/enable_incus.sh"

# Run the script to install Incus and its dependencies. This will reboot the VM.
alpine exec incus -- "ash enable_incus.sh"

After the script completes, the Incus daemon will be installed and configured to start on boot.

3. Initialize Incus

Now, initialize the Incus server inside the VM. We can accept all the default settings for a simple setup.

alpine exec incus "incus admin init --auto"

4. Configure the Incus Remote

To allow the incus client on your Mac to connect, we need to configure the server to listen on all interfaces and add a trust token for your client.

# Tell Incus to listen on 0.0.0.0:8443 inside the VM
alpine exec incus "incus config set core.https_address 0.0.0.0:8443"

# Generate a trust token for the client
alpine exec incus "incus config trust add mymac"

The second command will output a long token. Copy this token, as you will need it in the next step.

5. Add the Remote to your Mac's Incus Client

Finally, configure the incus client on your macOS host to connect to the server running in the VM.

# The server is available at 127.0.0.1 because we forwarded port 8443
incus remote add incus https://127.0.0.1:8443

When prompted, paste the trust token you copied from the previous step.

Now, switch to your new remote to make it the default:

incus remote switch incus

That's it! Your setup is complete.

Launching Your First Incus Container

You can now manage containers using the incus client on your Mac, and they will run inside the macpine VM.

# Launch a Debian Bullseye container
incus launch images:debian/bullseye debian

# List running containers
incus list

# Execute a shell inside the container
incus exec debian -- bash

Cleanup

When you're done, you can clean up the resources:

# Stop and delete the Incus container
incus stop debian
incus delete debian

# Stop and delete the macpine VM
alpine stop incus
alpine delete incus