Skip to the content.

Getting started with AltVM

This guide takes you from a fresh clone to running Linux and macOS virtual machines on your Apple silicon Mac, with shared folders, snapshots and SSH.

Contents: Install · First Linux VM · Use the VM · Shared folders · Snapshots · macOS VM · App and window · Next steps · Troubleshooting

1. Install

You need:

git clone https://github.com/GagnDeep/altvm.git
cd altvm
./scripts/build.sh                          # → dist/AltVM.app and dist/avm, signed with the virtualization entitlement
sudo ln -sf "$PWD/dist/avm" /usr/local/bin/avm
cp -R dist/AltVM.app /Applications/          # optional: the native app
avm host                                     # shows what this Mac can run (cores, RAM, limits)

The avm binary must keep its code signature, because Virtualization.framework requires the com.apple.security.virtualization entitlement. If you rebuild with swift build, re-sign it:

codesign -f -s - --entitlements Resources/avm.entitlements .build/debug/avm

2. Create your first Linux VM

avm catalog                                  # list available images
avm create dev --catalog debian-13 --start

AltVM downloads the official Debian cloud image, verifies its SHA-512 checksum and converts it to a sparse disk. It then boots it with cloud-init, which creates your macOS username with your ~/.ssh/*.pub keys and installs the guest agent. All of this takes about 10 seconds after the first download.

Other images:

Catalog id What you get
debian-13 Debian 13 “trixie”, unattended (cloud image)
debian-12 Debian 12 “bookworm”, unattended (cloud image)
ubuntu-24.04 Ubuntu 24.04 LTS Server, unattended (cloud image)
ubuntu-24.04-desktop Ubuntu 24.04 LTS Desktop installer ISO
debian-13-installer Debian 13 netinst installer ISO
macos The latest macOS supported by your Mac

Size the VM yourself, or pick a workload profile:

avm create build --catalog ubuntu-24.04 --cpus 6 --memory 12G --disk 128 --start
avm create web   --catalog debian-13 --profile server --start

Profiles (productivity, development, design, gaming, server, travel) are sized from your Mac’s real core and RAM counts, and always leave the host at least 25% of its RAM.

3. Use the VM

avm list                                     # all VMs, state, resources
avm exec dev -- uname -a                     # run a command through the guest agent (no network or SSH needed)
echo hi | avm exec dev -i -- cat             # -i forwards stdin
avm ssh dev                                  # regular SSH session as your user
avm ip dev                                   # the VM's IP address
avm info dev                                 # details and live status
avm stop dev                                 # graceful shutdown (agent → ACPI → force after a timeout)

Run x86-64 Linux binaries with Rosetta:

avm rosetta install                          # once per Mac, if Rosetta isn't installed yet
avm exec dev -- ./some-x86_64-binary         # registered automatically in catalog VMs

4. Share folders with your Mac

Catalog VMs mount your shared folders at /mnt/mac over virtio-fs:

avm set dev share+=code:~/code               # share ~/code as /mnt/mac/code (applies on next boot)
avm set dev share-=code                      # remove it
avm create dev2 --catalog debian-13 --no-share   # create with no shared folders at all

5. Snapshots, clones and suspend

avm snapshot create dev clean                # live snapshot including RAM if the VM is running
avm snapshot tree dev
avm snapshot restore dev clean
avm clone dev dev-experiment                 # instant APFS copy-on-write clone, new identity
avm suspend dev                              # save RAM to disk and quit
avm start dev                                # resume in about 0.65 s, with the guest clock resynced

Disposable and isolated modes:

avm create scratch --catalog debian-13 --disposable --start   # every boot starts clean
avm create lab     --catalog debian-13 --isolated --start     # no NAT, shares, clipboard, mic or USB

6. Create a macOS VM

avm macos-latest                             # which macOS version your Mac supports
avm create mac --macos --start               # downloads the IPSW (about 15–25 GB) from Apple, installs and provisions it
avm start mac --gui                          # open it in a window

macOS guests get Apple’s paravirtualized Metal GPU, a Mac keyboard and trackpad, and Retina displays. Apple’s macOS license allows up to two additional macOS instances per Mac.

Saved states of macOS VMs are sealed by your Mac’s Secure Enclave, so resume a suspended macOS VM while your Mac is unlocked. To throw the saved state away and cold boot instead, use avm start mac --discard-state.

7. Use the app or a VM window

Next steps

Troubleshooting

Symptom Fix
The process doesn't have the "com.apple.security.virtualization" entitlement Re-sign avm (see Install) or use dist/avm from scripts/build.sh.
… is already running in another process The VM is already open somewhere else (CLI, app or API). Use avm stop <vm> or control it from there.
Resume says the session is protected by the Secure Enclave Unlock your Mac and retry, or run avm start <vm> --discard-state.
avm exec hangs waiting for input Only use -i when you pipe stdin into the command.
A guest file system was damaged after a power cut Run avm repair <vm> to force a fsck on the next boot.
The display is black during the boot menu That’s expected: firmware-stage graphics are not captured. The OS display appears once the guest boots.