macVMs

macVMs is a lightweight CLI tool for managing QEMU virtual machines on Apple Silicon Macs.

It focuses on simplicity and reproducibility, making it easy to create and manage fully emulated x86 and x86_64 virtual machines without manually writing QEMU commands.

Why macVMs?

Some time ago I was doing some CTF (capture the flag) Cybersecurity competitions, but I couldn't tackle the software related challenges because of my MacBook and the ARM architecture.

I decided to build my very own wrapper over QEMU to create lightweight, emulated virtual machines similar to what WSL 2.0 offers, and so, macVMs was born.

Features

macVMs is designed to be portable and easy to use:

• Interactive VM creation
• Configurable RAM, CPU and disk size
• Headless serial-console installation
• Shared folders via 9p
• Built-in networking presets
• Per-VM QEMU configuration overrides
• Optional SSH-based workflow

Requirements

• macOS
• Python 3.9+
• QEMU
• Basic VM / operating system installation knowledge

---

Quick Start

1. Launch macVMs.
2. Create a new VM.
3. Select an operating system.
4. Complete the installation.
5. Start the VM.
6. Configure SSH (optional).
7. Connect to the VM.

The entire workflow can be completed from the interactive menu without manually invoking QEMU.

Creating a VM

During creation you will be prompted for:

• VM name
• Operating system
• RAM size
• CPU count
• Disk size
• Optional shared folder

Both Debian and Ubuntu are configured to boot directly into a serial-console installer suitable for headless environments.

Recommended Guest Configuration

For lightweight virtual machines:

• Install only standard system utilities.
• Avoid desktop environments unless required.

This produces a small VM that boots directly into a shell.

Remote Access (SSH)

By default, macVMs forwards:

localhost:2222 -> guest:22

Install OpenSSH inside the guest:

sudo apt update
sudo apt install -y openssh-server
sudo systemctl enable --now ssh

Set a root password:

sudo passwd root

Enable root login:

sudo tee -a /etc/ssh/sshd_config >/dev/null <<EOF
PermitRootLogin yes
PasswordAuthentication yes
EOF

sudo systemctl restart ssh

Connect from the host:

ssh -p 2222 root@localhost

Setup the macvms command in the host:

./scripts/install-macvms.sh

Shared Folders

When enabled, a host directory is exposed to the guest using QEMU 9p. This allows for your file to be also accessed through the VM.

Create a mount point:

sudo mkdir /mnt/shared

Mount the share:

sudo mount -t 9p -o trans=virtio shared /mnt/shared

To make a persistent mount:

echo 'shared /mnt/shared 9p trans=virtio,version=9p2000.L,rw 0 0' | sudo tee -a /etc/fstab
sudo mount -a

Networking

macVMs supports three networking modes:

user

Default mode.

network=user

Provides NAT networking and automatic SSH forwarding.

vmnet-shared

network=vmnet-shared

Provides a macOS-managed shared network.

vmnet-bridged

network=vmnet-bridged
ifname=en0

Places the guest directly on the physical network.

Advanced Configuration

Each VM contains a dedicated configuration file:

~/macVMs/vms/<vm-name>/qemu.conf

This config file is very technical and not user-friendly.

Supported options:

network=user|vmnet-shared|vmnet-bridged
ifname=en0
nic_model=virtio-net-pci
hostfwd=tcp::2222-:22
extra_args=<qemu args>
qemu_args=<qemu args>

Example:

network=user
hostfwd=tcp::2222-:22

Example:

network=vmnet-bridged
ifname=en0
nic_model=virtio-net-pci

Building the Application

Create a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

Build the application:

./build.sh

The resulting disk image will be available at:

dist/macVMs.dmg

You can then move the application into the macOS Applications directory.

---

Notes

• Uses QEMU full emulation
• Hardware virtualization is not enabled
• Performance is MUCH lower than native virtualization

---

Scope

macVMs is intended for small, testing environments and lightweight Linux instances. It's not intended to be a full-featured virutalization platform.

---

License

Made by xEcho1337

Licensed under Apache License 2.0.