QLab

Modular CLI tool for QEMU/KVM educational labs.

QLab makes it easy to create, share, and run hands-on virtualization labs. Each lab is a plugin that spins up one or more QEMU virtual machines, fully provisioned via cloud-init — so students learn by doing, with zero manual setup.

flowchart TD
    U(["👤 User"])
    R(["🗂️ Plugin Registry"])
    WS["📁 .qlab/ workspace"]
    VM["🖥️ QEMU/KVM VM (cloud-init)"]

    U -->|"① qlab init (once)"| WS
    U -->|"② qlab install"| R -->|"plugin cloned"| WS
    U -->|"③ qlab run"| WS -->|"boots"| VM
    U -->|"④ qlab shell"| VM

flowchart TD
    A(["qlab install nginx-lab"]) --> B["plugin cloned into .qlab/plugins/nginx-lab/"]
    B --> C(["qlab run nginx-lab"])
    C --> D["qcow2 overlay disk created"]
    D --> E["QEMU VM started"]
    E --> F["cloud-init: installs nginx, configures service"]
    F --> G{{"VM ready ✓ — SSH port auto-assigned"}}
    G --> H(["qlab shell nginx-lab"])
    H --> I["interactive SSH session — do the lab —"]
    I --> J(["qlab stop nginx-lab"])
    J --> K(["qlab uninstall nginx-lab"])

# Install QLab
curl -fsSL https://raw.githubusercontent.com/manzolo/qlab/main/install.sh | sudo bash

# Create and initialize a workspace
mkdir my-lab && cd my-lab
qlab init

# Install and run your first lab
qlab install hello-lab
qlab run hello-lab

# Connect to the VM
qlab shell hello-lab

Default VM credentials: labuser / labpass (SSH key login is automatic).

Install any plugin with qlab install <name> or browse them all with qlab list available.

Every plugin is a directory with three files:

my-plugin/
├── plugin.conf    # JSON metadata (name, version, description)
├── install.sh     # Optional: runs on install (dependency checks, setup)
└── run.sh         # Required: entry point (launches the VM)

Plugins source $QLAB_ROOT/lib/*.bash for core helpers (start_vm, create_overlay, allocate_port, etc.).

See doc/CREATE_PLUGIN_PROMPT.md for a step-by-step guide to building your own lab plugin.

Override RAM and disk size for any plugin at runtime:

# Run docker-lab with 4 GB RAM and 30 GB disk
QLAB_MEMORY=4096 QLAB_DISK_SIZE=30G qlab run docker-lab

Priority: environment variable → qlab.conf (DEFAULT_MEMORY) → plugin default.

QLab includes a menu-driven terminal interface — no commands to memorize:

qlab manager

Requires dialog (sudo apt install dialog). From the TUI you can initialize workspaces, browse and install plugins from the registry, start/stop VMs, open SSH shells, and tail logs.

One-liner (recommended):

curl -fsSL https://raw.githubusercontent.com/manzolo/qlab/main/install.sh | sudo bash

Without root, falls back to a user-local install (~/.local/bin):

curl -fsSL https://raw.githubusercontent.com/manzolo/qlab/main/install.sh | bash

From source:

git clone https://github.com/manzolo/qlab.git
cd qlab
sudo ./install.sh

Manual (no install):

git clone https://github.com/manzolo/qlab.git
cd qlab
sudo apt install qemu-kvm qemu-utils genisoimage git jq curl
export PATH="$PWD/bin:$PATH"

curl -fsSL https://raw.githubusercontent.com/manzolo/qlab/main/install.sh | sudo bash

The install script runs git pull --ff-only automatically if QLab is already installed.

License: MIT | Contributing | Changelog