VmChamp

Simple and fast creation of throwaway VMs on your local machine. Connect via SSH seconds.

� Table of Contents

• ✨ Features
• 🤔 Why?
• 🚀 Usage
• 🔑 How it works
  • Default VM User & SSH Access
  • QEMU User Session
  • Add Shell Completion
• 🛠️ Installation
• 🏗️ Build

✨ Features

• Quickly create and SSH into throwaway VMs.
• Fast boot times using minimal cloud images.
• On-demand downloads for Debian, Ubuntu, Arch, Fedora, CentOS, Rocky and Alma cloud images.
• Automatically injects your ~/.ssh/*.pub keys into the VM's authorized_keys. for passwordless ssh access.
• Shell completion
• Utilizes KVM, QEMU, and libvirt in the user session (qemu:///session) — no root required.

🤔 Why?

VmChamp creates local VMs in seconds and provides SSH access.

Bypassing a lengthy manual VM setup process. Especially useful when Containers do not suffice.

🚀 Usage

RUN:

vmchamp run mytestvm
# or for more options
vmchamp run mytestvm --os debian11 --mem 512MiB --disk 20GiB

Defaults: OS = Debian13 · Memory = 512MiB · Disk = 8GiB · CPUs = 1 · User = user

Plain numbers for --mem and --disk are interpreted as GiB (e.g. --disk 20 → 20 GiB, --mem 0.5 → 0.5 GiB).

vmchamp run mytestvm --os debian11 --mem 0.512 --disk 20

Which leads to output:

️👉 Creating VM: mytestvm
💻 Using OS: Debian11
📔 Memory size: 512 MiB
💽 Disk size: 20 GiB

...output omitted...

⣷ Waiting for network...

...output omitted...

user@testvm:~$

🔑 How it works

Default VM User & SSH Access

Every VM is provisioned via cloud-init (IsoImager.cs) with:

• A user named user (override with --user).
• All *.pub files found in your ~/.ssh/ directory are copied into the VM's authorized_keys — SSH works immediately without a password.
• The user has passwordless sudo (ALL=(ALL) NOPASSWD:ALL).

No SSH password is set by default. See the FAQ for how to set one if needed.

QEMU User Session

VmChamp runs VMs in the QEMU/KVM user session (qemu:///session) — no root required.

To list your VMs from the terminal:

virsh --connect qemu:///session list --all

To view them in Virtual Machine Manager: File → Add Connection → QEMU/KVM user session.

Add Shell completion

Add the following to your .bashrc or .zshrc file

# For BASH
source <(vmchamp --completion bash)

# For ZSH
source <(vmchamp --completion zsh)

🛠️ Installation

TESTED on: Ubuntu 22.04; Debian 12

For details see Installation Guide

🔧 Prerequisites:

• Your machine supports virtualization with KVM

# Installing requirements
sudo apt update
sudo apt install qemu-kvm libvirt-daemon-system

# Download latest VmChamp:
wget -qO- https://api.github.com/repos/mzwoelfer/VmChamp/releases/latest | grep "browser_download_url" | cut -d '"' -f 4 | wget -i - -O vmchamp

# Install VmChamp rootless
chmod +x vmchamp
mkdir -p ~/.local/bin
mv vmchamp ~/.local/bin/

export PATH="$PATH:$HOME/.local/bin"

vmchamp run testvm

🏗️ Build

To build VmChamp run:

./build.sh <version> <output dir>
# ./build.sh 1.2.3 ~/build/

Output dir defaults to ./build/.