Running LXD Containers in Macpine

Overview

LXD is a powerful system container manager. Like Incus, it does not run natively on macOS. macpine can run an LXD server in a lightweight VM, allowing you to manage LXD containers from your Mac.

This guide demonstrates setting up an LXD server in a macpine VM using bridged networking (vmnet-shared) for easier access.

Prerequisites

  1. Install QEMU and macpine: 

    brew install qemu macpine

  2. Install the LXC client: 

    brew install lxc

1. Launch the LXD VM

For LXD, we will use the --shared network mode. This gives the VM its own IP address on your network, avoiding the need for manual port forwarding for the LXD API. This command must be run with sudo.

sudo alpine launch --name lxd-vm --shared

2. Install and Configure LXD

Next, run a script inside the VM to install the LXD daemon and its dependencies. Then, initialize LXD with default settings.

# Download the setup script
alpine exec lxd-vm "wget https://raw.githubusercontent.com/beringresearch/macpine/refs/heads/main/scripts/enable_lxd.sh"

# Run the setup script. This will reboot the VM.
alpine exec lxd-vm "ash enable_lxd.sh"

# Initialize the LXD server
alpine exec lxd-vm "lxd init --auto"

3. Configure the LXD Remote

First, find the IP address of your VM:

alpine info lxd-vm
# Look for the 'IP:' field, e.g., 192.168.1.124

Now, use this IP address to configure the LXD server to listen for remote connections and set a trust password.

# Replace [machineip] with the IP you found above
alpine exec lxd-vm "lxc config set core.https_address [machineip]"

# Set a trust password (e.g., 'root' for this demo)
alpine exec lxd-vm "lxc config set core.trust_password root"

4. Add the Remote to your Mac's LXC Client

Finally, add the VM as a remote to your local lxc client.

# Replace [machineip] with the IP of your VM
lxc remote add macpine [machineip] --accept-certificate --password root

Note: If you destroy and recreate this setup, you might need to remove the old remote from your ~/.config/lxc/config.yml file due to new server certificates being generated.

Switch to the new remote to make it your default:

lxc remote switch macpine

Setup is complete!

Launching Your First LXD Container

Use the lxc client on your Mac to manage containers running inside the macpine VM.

# Launch an Ubuntu 24.04 container
lxc launch ubuntu:24.04 ubuntu

# List containers
lxc list

# Get a shell inside the container
lxc exec ubuntu -- bash

Cleanup

# Stop and delete the LXD container
lxc stop ubuntu
lxc delete ubuntu

# Stop and delete the macpine VM
alpine delete lxd-vm