macpine

Lightweight Alpine VMs on MacOS

Create and manage lightweight Alpine VMs on MacOS with:

:repeat: Seamless port forwarding

:card_index_dividers: Automatic file sharing

:roller_coaster: Bridged networking

:rocket: aarch64 and x86_64 emulation

Motivation

The goal of this project is to enable MacOS users to:

1. Easily spin up and manage lightweight Alpine Linux environments.
2. Use tiny VMs to take advantage of containerisation technologies, including Incus, LXD and Docker.
3. Build and test software on x86_64 and aarch64 systems.

Installation

macpine is intended for use on modern macOS. Support for older versions of macOS and other OSes may vary.

Install from Homebrew (recommended)

brew install macpine # installs `alpine` command and `qemu` dependency automatically

Get the latest binary

Download the latest binary release for your system and add it to your $PATH by moving it to e.g. /usr/local/bin/:

arch="$([ `uname -m` = 'x86_64' ] && echo 'amd64' || echo 'arm64')" # detect architecture
wget "https://github.com/beringresearch/macpine/releases/latest/download/alpine_darwin_$arch"
mv "alpine_darwin_$arch" alpine
sudo chmod +x alpine
sudo mv alpine /usr/local/bin/
#export PATH="$PATH:/usr/local/bin"

Macpine depends on QEMU >= 7.22.0:

brew install qemu

See Requirements below for a known QEMU regression and optional passwordless vmnet setup.

Install from MacPorts

You can also install macpine via MacPorts:

sudo port install macpine

Install from source

Building from source requires a working go compiler, and running requires qemu:

brew install go qemu
git clone https://github.com/beringresearch/macpine
cd macpine
make            # compiles the project into a local bin/ directory
make install    # installs binaries to /usr/local/bin
                # PREFIX=/some/other/path make install installs to /some/other/path

Requirements

• macOS (Apple Silicon or Intel) and QEMU >= 7.22.0, installed automatically by brew install macpine or manually via brew install qemu.
• Known issue: QEMU 11.1.1 has a regression that can hang aarch64 instances on boot when using vmnet networking (see Troubleshooting). If you hit this, pin QEMU to 10.0.3 until it's fixed upstream.
• Instances with bridged (vmnet) networking require sudo for alpine start/stop/ssh/exec, unless socket_vmnet is installed and running.

Optional: bridged networking without sudo

By default, vmnet networking (a real, LAN-reachable IP for the instance) requires root, because QEMU calls macOS's Vmnet.framework directly. Installing socket_vmnet removes that requirement: it does the one privileged step once, in the background, and macpine talks to it over a Unix socket instead.

brew install socket_vmnet
sudo brew services start socket_vmnet   # one-time; runs persistently in the background

macpine detects a running socket_vmnet daemon automatically. If it isn't found, macpine transparently falls back to QEMU's native vmnet-shared networking (requiring sudo, as before).

Getting Started

To create and start a new instance:

alpine launch                       # launches with default parameters
alpine launch -a aarch64            # create an aarch64 instance
alpine launch -d 10G -c 4 -m 2048   # create an instance with a 10GB disk, 4 cpus, and 2GB of RAM

alpine launch -h                    # view all configuration options and defaults

Access instance via ssh:

alpine launch -s 22         # launch an instance and expose SSH port to host port 22
alpine ssh instance-name    # attach shell to instance (replace `instance-name` as appropriate)

Expose additional instance ports to host:

# launch an instance, expose SSH to host port 2022 and forward host ports 8888 and 5432 to instance ports 8888 and 5432
alpine launch -s 2022 -p 8888,5432

# launch an instance, expose SSH to host port 8022, forward host port 8081 to instance port 8082, and forward
# host port 8083 to instance port 8083
alpine launch -s 8022 -p 8081:8082,8083

# launch an instance, expose SSH to host port 9022, forward host port 9091 UDP to instance port 9091 UDP,
# and forward host port 9092 UDP to instance port 9093 UDP
alpine launch -s 9023 -p 9091u,9092:9093u

Instances can be easily packaged for backup or sharing as .tar.gz files:

alpine list

NAME                 STATUS      SSH    PORTS   ARCH      PID     TAGS
cheerful-result      Running     2022           aarch64   26568
glittering-swing     Running     3022           x86_64    57206   emulation,intel

alpine publish cheerful-result

This will create a file cheerful-result.tar.gz which can be imported as:

#alpine delete cheerful-result
alpine import cheerful-result.tar.gz

See all the docs for more information:

• advanced port forwarding and securing instance SSH
• editing instance configurations
• running incus within instances
• running LXD within instances
• hardening instances
• auto-starting instances at login
• general troubleshooting

Command Reference

…

Multiple instances in a command: some commands (delete, edit, info, pause, publish, restart, resume, start, stop) accept multiple instance names and will repeat the operation over each unique named instance once.

Tags: using alpine tag, instances can be tagged; tags can be used in multi-instance commands (see above) e.g. alpine start +foobar will start all instances which have had been tagged foobar with alpine tag instance-name foobar. Note that the tag launchctl-autostart is used for auto-starting instances at login.

Shell autocompletion: shell command completion files (installed automatically with brew install macpine) can be generated with alpine completion [bash|zsh|fish|powershell]. See alpine completion -h or the completion documentation for more information.