Browse the docs

Start

Creating VMs

Pick a guest, pick where it installs from, and Hangar does the rest.

Recipes

I want… Run
macOS with my own account hangar create mac --os macos --user dev
macOS with Homebrew (or Xcode) ready hangar create mac --os macos --image base (or --image xcode)
macOS from an IPSW hangar create mac --os macos --ipsw ~/Downloads/UniversalMac_Restore.ipsw --user dev
Debian or Ubuntu, ready in seconds hangar create deb --os linux --image debian (or --image ubuntu; user admin, password admin)
Linux from a cloud image hangar create deb --os linux --user dev --disk-image https://cloud.debian.org/images/cloud/trixie/latest/debian-13-generic-arm64.qcow2
Linux from an installer ISO hangar create deb --os linux --iso ~/Downloads/debian-13-arm64-netinst.iso, then hangar run deb
Windows 11 hangar create win --os windows --iso ~/Downloads/Win11_arm64.iso --user admin
A copy of a VM hangar clone deb deb2
A VM from your team's image hangar create ci --os linux --image ghcr.io/acme/ci:1.0
A VM from a template hangar create go --template go-dev.hangarvm (see Templates)

You're asked for a password, or give it on standard input with --password-stdin. Set the size with --cpu, --memory and --disk (GB). Disks only use the space they need.

Guests and defaults

Guest Installs from CPU Memory Disk
macOS Hangar's image (--image vanilla by default, base or xcode), or an IPSW (--ipsw: a file, an https URL or latest from Apple) 4 8 GB 80 GB
Linux An ISO (--iso), a cloud image (--disk-image, file or https URL), or an image in a registry (--image) 2 4 GB 20 GB
Windows 11 on Arm The official Arm64 ISO (--iso), installed unattended, or an image in a registry (--image) 4 8 GB 64 GB

Accounts

macOS, Windows and Linux cloud images create --user on their first start. For cloud images Hangar writes a small cloud-init disk that holds only a hash of the password; add --ssh-key ~/.ssh/id_ed25519.pub to sign in with your key. Hangar's base and xcode images come with their own account, so --user doesn't go with them.

A macOS account logs in automatically and has Remote Login (SSH) on; --no-auto-login and --no-ssh leave either off.

Cloud images can be raw or qcow2, like Debian's and Ubuntu's.

Hangar's macOS images

Image What's inside
vanilla The latest macOS as Apple installs it, never started, so your account is created on its first start. New macOS VMs use it unless you pick an IPSW.
base Adds the Command Line Tools, Homebrew and Hangar's agent.
xcode Adds Xcode with the iOS platform to base.

base and xcode have the administrator admin with the password admin, which logs in automatically and uses sudo without a password. Remote Login (SSH) is on, the time zone is GMT, and the VM never sleeps or locks its screen. Change the password in the VM's System Settings.

Each image builds on the one before, and parts a VM already has from another image are copied from your Mac instead of downloaded. They live at ghcr.io/baseguard/hangar-macos:vanilla, :base and :xcode. Hangar pins the tag to a digest once, checks every byte against the digests in that manifest, and never opens a downloaded disk on your Mac.

Hangar's Debian and Ubuntu

New Virtual Machine › Linux, or hangar create <vm> --os linux --image debian (or ubuntu), downloads the latest Debian 13 or Ubuntu 26.04 LTS cloud image once from its publisher and checks it against the checksum list published next to it (integrity, not authenticity). The VM gets Hangar's agent and the administrator admin with the password admin.

Your own cloud-init

--cloud-init user-data.yaml adds your #cloud-config (packages, files, commands) or a #! script next to Hangar's account. Leave out --user to set up every account yourself.

Windows

Hangar reads the Windows ISO on this Mac to build the installation media, so use the official ISO from Microsoft; the media the installer writes back is never mounted here.

Windows VMs come with Remote Desktop on; --no-remote-desktop, or the switch in the app, keeps it off.

Images from a registry or a file

--image ghcr.io/acme/ci:1.0 creates a VM from an image your team pushed with hangar export, and --image ~/ci-linux.tar from one saved to a file (see Snapshots and images). In the app, that's New Virtual Machine › From an Image. Sign in first with hangar login if the image is private. For a registry without HTTPS, add --insecure; the image's parts are still checked against its digest.

Downloads

macOS images, IPSWs, ISOs and cloud images are downloaded once over https and cached in ~/.hangar/cache. The newest installed macOS is kept too, so the next macOS VM is a copy that's ready in seconds.

See and delete them in Settings › Downloads, or delete the ones you haven't used for a while:

hangar prune --older-than 30

ISOs later

Attach or detach an ISO for a macOS or Linux VM in the Virtual Machine menu or with hangar set <vm> --iso; macOS mounts it like a disk. A VM that Hangar started in a window without an ISO can change it while it runs.

Windows can't read ISOs here, as it needs a CD drive and VMs on a Mac don't have one.