Installation · Quickstarts · Agent skill · Guides and reference
Voom is a CLI for running and managing Linux and MacOS virtual machines.
Voom does not run a persistent daemon and does not expose user-facing configuration files; instead all VM-related operations are managed via the CLI.
Voom supports MacOS hosts (via vfkit) and Linux hosts (via QEMU/KVM):
- Linux hosts support running Linux guests
- MacOS hosts support running Linux and MacOS guests
Voom provides support for manual port forwarding (TCP and UDP) on MacOS and Linux guests.
For Linux guests on either supported host OS, Voom also supports:
- Host directory shares.
- Automatic TCP port forwarding, with per-VM port offsets to avoid collisions.
- HTTP proxy attachments, enabling external brokers (such as Agent Vault and iron-proxy) to supply credentials without storing them in the guest.
On Linux hosts, Voom additionally supports:
- PCI passthrough on x86_64, for accessing a GPU or other PCI Express devices from the guest.
- USB passthrough, for accessing USB devices from the guest.
MacOS guests are not yet as full-featured as Linux guests.
Download a prebuilt archive from GitHub releases or install with Nix:
nix profile install github:mjrusso/voomSee the installation guide for host requirements, release setup, and Nix integration.
Install Voom, then choose a guest OS:
- Run a Linux guest: download and import a cloud image, start a VM, verify it, and configure shares and forwarding.
- Run a MacOS guest: prepare an installed image bundle, start a VM, verify it, and use the graphical console.
Voom ships agent instructions as part of the binary. To print the skill file,
run voom skill.
Installation is not required (just tell your agent to run voom skill). You
can optionally install the skill; for example:
mkdir -p ~/.agents/skills/voom
voom --skill > ~/.agents/skills/voom/SKILL.md
chmod 0644 ~/.agents/skills/voom/SKILL.mdVoom runs guests with the same CPU architecture as the host; it does not emulate other architectures. Windows hosts and VM execution on Intel Macs are unsupported.
| Host | Guest | Driver | Imported image |
|---|---|---|---|
| Linux x86_64 | x86_64 Linux | QEMU/KVM | qcow2 disk |
| Linux aarch64 | aarch64 Linux | QEMU/KVM | qcow2 disk |
| Apple Silicon MacOS | aarch64 Linux | vfkit | raw disk |
| Apple Silicon MacOS 27+ with a graphical login | aarch64 MacOS 27+ | vfkit | Installed MacOS bundle |
All supported combinations provide image import, VM creation, start, stop, restart, removal, clone, reset, persistent storage, ordinary guest networking, SSH, remote command execution, and guest verification.
| Feature | Linux guest on Linux | Linux guest on MacOS | MacOS guest on MacOS³ |
|---|---|---|---|
| Host directory shares | Yes¹ | Yes¹ | No |
| Manual TCP/UDP application forwards | Yes⁴ | Yes⁴ | Yes⁴ |
| Automatic TCP forwards and listener reports | Yes¹ | Yes¹ | No |
| Explicit HTTP proxy attachments | Yes¹ | Yes¹ | No |
| Serial console log | Yes² | Yes² | No |
| Graphical console | No | No | Yes |
| Disk growth | Yes | Yes | No |
| Snapshots and suspend/resume | No | No | No |
nixos switch |
NixOS only¹ | NixOS only¹ | No |
| USB passthrough | Yes | No | No |
| PCI/GPU passthrough | x86_64 only | No | No |
¹ Requires the corresponding Linux guest capabilities and services.
² voom console follows the serial log; it is not an interactive terminal. The
guest must be configured to write serial output.
³ MacOS guests use SSH for file transfer and remote commands. They do not use Voom's reserved control share or a guest agent.
⁴ Manual port forwarding does not require guest services.
These examples work for both Linux and MacOS guests. Replace dev with your VM
name.
List your VMs, then inspect one for its status, resource allocation, and SSH connection details:
voom list
voom info devStop a VM when you have finished using it:
voom stop devVoom requests guest shutdown, then terminates remaining VM processes if
needed. The guest disk is preserved. Run voom start dev to start it again,
or voom restart dev to stop and start it in one command.
Stop the source VM, then copy it into a new VM named dev-copy:
voom stop dev
voom clone dev dev-copy
voom start dev-copyThe clone has its own disk containing the source's current guest state, including installed software, user accounts, credentials, and SSH host keys. It keeps the source's CPU and memory allocation but gets its own Voom ID, SSH port, and NIC MAC address. MacOS clones also get a new Apple machine identifier.
For Linux and MacOS guests, manual forwards are not copied. For Linux guests, host directory shares, automatic-forwarding settings, USB/PCI assignments, and proxy attachments are also not copied; however, the clone command prints commands that you can manually invoke to recreate shares, forwards, and device assignments. A proxy attachment needs a separate backend for the clone; see proxy attachments.
Stop the VM before changing its allocation. This example sets 8 vCPUs and 8192 MiB of RAM:
voom stop dev
voom resources cpus dev 8
voom resources memory dev 8192MiB
voom start devMacOS allocations must meet the recorded resource minimums. For expanding a Linux guest disk, see disk growth.
By default, Voom assigns each VM the first available host SSH port in the
2222–2299 range and saves that port with the VM. Use --ssh-port at creation
or voom config ssh-port while stopped to choose another port. SSH binds to
host loopback by default.
Use the generated OpenSSH configuration with standard SSH tools. Replace dev
with your VM name; its SSH alias is voom-dev:
voom ssh-config dev > ./voom-dev.ssh
ssh -F ./voom-dev.ssh voom-dev
scp -F ./voom-dev.ssh ./example.txt voom-dev:The VM must be running and accepting SSH connections. The scp example also
uses SFTP, which must be enabled in the guest.
Regenerate the file after changing the VM's name, SSH port, user, or identity.
See the SSH reference for key handling
and networking details.
Remove a VM when it is no longer needed:
voom remove devRemoval asks for confirmation; use --force to skip it. Removing a VM deletes
its storage, not its imported source image. VM disks are independent copies;
see image ownership and removal.
To rebuild an existing VM from an image, see reset instructions for Linux or MacOS.
- Installation: release builds, Nix, and host requirements.
- Linux guests: getting started, verification, custom images, sharing, forwarding, USB, and PCI/GPU passthrough.
- MacOS guests: getting started, verification, installed bundles, graphical sessions, Apple identity, and resource limits.
- Diagnostics and recovery: host checks, logs, verification failures, and runtime cleanup.
- HTTP proxy attachments: external credential brokers, guest configuration, security boundaries, and recovery.
- Reference: command overview, directories, helper selection, storage, events, command effects, aliases, and shell completion.
- Command reference: flags and arguments for every command.
Use voom --help to list commands and voom <command> --help for a
command's usage and options.
For development setup, source builds, checks, generated docs, package boundaries, and the release process, see CONTRIBUTING.md.
Voom is released under the terms of the MIT License.
See Third-party licenses for bundled components and the locations of their license notices.
Copyright (c) 2026, Michael Russo.