Audience: anyone on Windows or macOS who wants to play labs without installing anything, and anyone who prefers a throwaway machine to their own. No knowledge of virtualization is assumed: this page goes from the download to the first lab, step by step.
The appliance is a Debian 13 virtual machine with dsoxlab, Ansible, Terraform and a desktop already in place. You import it, you start it, you play.
The appliance running in VirtualBox, a few minutes after import: dsoxlab doctor on the desktop, 86 labs discovered, and the only choice left to make —
the hypervisor — named together with the command that settles it.
On Linux it is the wrong answer, and this page says so plainly: downloading
half a gigabyte to avoid uv tool install dsoxlab makes no sense. It exists for
the systems where that command is not an option.
| Minimum | Comfortable | |
|---|---|---|
| Memory | 4 GB free for the VM | 8 GB, required for vm labs |
| Disk | 25 GB free | 70 GB, if you work through several catalogs |
| CPU | 2 cores | 4 cores |
| Software | VirtualBox (free) | — |
| Network | a connection, for the first boot | — |
The first boot downloads about 1.5 GB (dsoxlab, the hypervisors, the desktop). That is deliberate: nothing is pinned in the image, so nothing in it is stale.
Go to https://www.virtualbox.org/wiki/Downloads and take the package for your system:
- Windows: Windows hosts. Double-click, follow the wizard, and accept the network driver installation when Windows asks.
- macOS Intel: macOS / Intel hosts. After installing, macOS may block the extension: open System Settings → Privacy & Security and click Allow for Oracle.
- Linux: your package manager, or the package on that page.
The Extension Pack it offers is not needed here.
The images are attached to the project's Releases, on every published version. Which means: take the latest, there is nothing to check.
| File | For | Tested |
|---|---|---|
dsoxlab-appliance-<version>.ova |
VirtualBox — Windows, Linux, Intel Mac | yes: import, boot, desktop |
the same .ova |
VMware Workstation and Fusion | not directly; the OVF validates against the DMTF schema and declares what VMware expects |
dsoxlab-appliance-<version>.qcow2 |
QEMU/KVM, libvirt, Proxmox | yes |
SHA256SUMS |
checking what you downloaded | — |
<version> is the release number, exactly as the Releases page shows it
without its v: the file on release v0.2.3 is
dsoxlab-appliance-0.2.3.ova.
If you are starting out, take the .ova.
Check the digest before importing half a gigabyte from the internet.
Download SHA256SUMS next to the image, then:
# Windows, in PowerShell
Get-FileHash .\dsoxlab-appliance-<version>.ova -Algorithm SHA256# macOS and Linux
shasum -a 256 dsoxlab-appliance-<version>.ovaThe value printed must match the one SHA256SUMS gives for that file. If it
differs, the download is incomplete or tampered with: start it again.
Both images are x86-64. See Apple Silicon below.
Only the last two sets of images are kept. Older releases keep their page,
their changelog and their Python distributions, but their .ova and .qcow2
are removed — roughly 900 MB each, for images that pin no dsoxlab version and
install the latest at first boot. An old image offers nothing but its weight.
In VirtualBox: File → Import Appliance, pick the .ova file, then
Next. Double-clicking the .ova opens the same window.
The next screen lists what the machine advertises: 4 CPUs and 8192 MB of memory. Both can be changed right here, and this is the moment to do it:
- your machine has 8 GB of RAM in total: bring the VM down to 4096 MB.
shelllabs will work,vmlabs will not — anddsoxlab doctorwill say so rather than leave you guessing; - your machine has 16 GB or more: leave 8192 MB.
Click Finish. The import takes one to three minutes, while VirtualBox decompresses the disk.
Skip this if you only want shell labs.
Read this before ticking the box. Running KVM inside VirtualBox works poorly, and we are working on it. VirtualBox exposes partial nested virtualisation: enough for
/dev/kvmto appear and for libvirt to agree to start a machine, not enough for that machine to run correctly.What it looks like, measured on 2026-10-10 with VirtualBox 7:
dsoxlab provisioncreates all three machines in two seconds, then one of them burns a whole core at 100% without ever allocating its memory — 369 MB touched out of 2048 requested. Adding memory and CPUs changes nothing (tried up to 16 GB and 8 vCPUs), and the appliance eventually freezes.If you are after
vmlabs, prefer one of the two paths below. If you stay on VirtualBox,shelllabs work perfectly, and there are many of them: the whole Terraform catalog, and a good share of the others.
| What you want to play | The solid path |
|---|---|
vm labs, comfortably |
dsoxlab directly on your Linux machine — uv tool install dsoxlab, native KVM, no nesting at all. This is the tool's primary use case |
vm labs, from a virtual machine |
the appliance under KVM/QEMU rather than VirtualBox: the .qcow2 is made for it, and KVM-inside-KVM behaves far better |
shell labs |
VirtualBox is fine, and you can leave the box unticked |
A vm lab starts real machines inside the appliance. Your computer therefore
has to allow a virtual machine to launch others, which is set outside the
appliance, with it powered off.
In VirtualBox, select the machine, then Settings → System → Processor. Three settings matter on that tab, and two of them are easy to miss:
| Setting | Value | Why |
|---|---|---|
| Nested VT-x/AMD-V | ticked | without it, no vm lab starts at all |
| Number of CPUs | 4 | the image asks for it, but the import does not always carry it over |
| Processing Cap | 100% | one import left it at 1%: the machine is then not slow, it is unusable |
On the command line:
VBoxManage modifyvm "dsoxlab-appliance-<version>" --nested-hw-virt on
VBoxManage modifyvm "dsoxlab-appliance-<version>" --cpus 4 --cpuexecutioncap 100If the box is greyed out, there are two likely causes: on an Intel host, some
VirtualBox versions only expose the setting from the command line; and on
Windows, Hyper-V must be disabled, otherwise it keeps virtualisation to
itself. If nothing helps, your CPU or your BIOS does not expose it: shell
labs remain entirely playable.
Select the machine and click Start. Here is what you will see, in three acts, with nothing to type:
- a few seconds of white text on black — Debian booting;
- several minutes where the machine appears to sit at a login prompt. It is not idle: it is installing dsoxlab, the hypervisors and the desktop. Count five to fifteen minutes depending on your connection;
- the machine reboots on its own and shows the login screen.
That reboot is not a failure: group membership and the desktop only take effect at the next boot.
If something fails, the machine says so and starts over at the next boot: it never marks itself configured when it is not. The usual cause is no network in the virtual machine — check its adapter under Settings → Network, then restart it.
| user | student |
| password | dsoxlab |
You only need that password if you skipped the wizard's question: at the very first boot, before the login prompt, the machine asks you to choose another one. The build password is public, it is written in this repository.
If you did not answer, it is still dsoxlab and the appliance said so on
screen. Change it once logged in:
passwdUp to 0.3.3 this change was forced by the system at first login. That was a defect: LightDM's graphical greeter cannot carry that dialogue, and the session could not be opened at all without switching to a text console.
You land on an XFCE desktop. The terminal is in the bottom bar, second icon.
A full-screen terminal without any desktop stays available: that is how you repair a graphical session that refuses to open.
In VirtualBox, Ctrl+Alt+F3 does not work: your host system grabs it, and the virtual machine never sees a thing. You need the host key, shown at the bottom right of the window — Right Ctrl by default:
| go to a console | Right Ctrl+F3 |
| back to the desktop | Right Ctrl+F1 (sometimes F7) |
Many compact keyboards have no Right Ctrl key. The combination can be changed: File → Preferences → Input, Virtual Machines tab, Host Key Combination — click the field and press the key you want.
In the terminal:
dsoxlab demo # installs a one-lab demonstration catalog
cd ~/.local/share/dsoxlab/demo
dsoxlab course premiers-pas # the lesson
dsoxlab run premiers-pas # drops you into the lab's work directory
dsoxlab challenge premiers-pas # the mission
dsoxlab check premiers-pas # the tests, and the scoreThat demonstration lab needs no VM and no container: it proves the whole loop works before you invest in a full catalog.
Then install a real catalog:
dsoxlab catalog add https://github.com/stephrobert/linux-dsoxlab-training
dsoxlab doctor # what this machine can do, and what is missing
dsoxlab list-labs # the catalog's 86 labsdoctor will tell you whether a choice is still pending — the hypervisor, for
instance, when the catalog offers several:
dsoxlab use --provider kvm
dsoxlab start <lab-id> # context, prerequisites, infrastructure, session
dsoxlab start on a vm lab, inside the appliance: sixteen required checks
green, then Terraform bringing up the lab's three machines — VMs inside the
VM.
| Symptom | Most likely cause | What to do |
|---|---|---|
| The machine stays on a console, no desktop | the first boot did not complete | it starts over at the next boot: check the VM's network, then restart it |
| The login prompt appears and nothing seems to happen | the first configuration runs in the background | press Enter: the prompt shows the current step. Since 0.3.2 it says so by itself |
| The keyboard is QWERTY | images up to 0.3.1 | since 0.3.2 the image ships AZERTY. On an earlier image: sudo apt install console-setup keyboard-configuration && sudo dpkg-reconfigure keyboard-configuration |
| "Temporary failure in name resolution" | the VM has no network | Settings → Network, adapter 1 enabled, attached to NAT |
dsoxlab doctor reports missing nested virtualization |
it is enabled on your computer, not inside the VM | step 4, appliance powered off |
doctor says "RAM: … available for … declared" |
the VM is too small for this catalog | give it more memory, or play shell labs |
| The import fails on an OVF error | incomplete download | check the SHA256 digest again |
| VMware refuses the import: "SHA256 digest of file does not match manifest" | a defect in images up to 0.2.5 — see below | use 0.3.0 or later, or import with ovftool --skipManifestCheck |
| VMware says the OS identifier is not supported and maps it to "Other (32-bit)" | same versions | same fix; the guest is 64-bit either way, so the appliance still runs |
On the manifest digest, for images up to 0.2.5. A stream-optimized VMDK ends
at a marker its reader stops on; qemu-img left a zero-filled alignment tail
after that marker, and ovftool therefore hashed 64 512 fewer bytes than our
manifest declared. The disk was intact — only the two readings disagreed.
Measured on the published file, fixed in 0.3.0, and now checked at build time:
the build refuses to ship an image whose file digest is not also its stream
digest.
A report beats a workaround: dsoxlab support --issue fills in the diagnosis
and opens the issue in the right place.
The appliance does not run on an Apple Silicon Mac, and saying otherwise would waste your afternoon. Both images are x86-64; Parallels, VMware Fusion and UTM virtualize arm64 on these machines and do not emulate another architecture at a usable speed. UTM can emulate x86-64 through QEMU's interpreter, at roughly a tenth of native speed — enough to watch a boot, not to play a lab.
An arm64 image is the obvious answer, and it is planned rather than done, for two reasons worth knowing:
- GitHub's hosted arm64 runners do not expose
/dev/kvm, so the CI would have to build that image under emulation, for hours. - Nested virtualization on Apple Silicon only exists from the M3 with macOS
15 or later. So even with an arm64 image,
vmlabs would stay out of reach on most Macs; onlyshelllabs would run.
Until then, on an Apple Silicon Mac, install the tool:
uv tool install dsoxlab. Every shell lab works, which is the whole
Terraform catalog and a good part of the others.
Debian 13, minimal, plus what a lab workstation needs: git, curl, vim,
python3, man, Ansible, Terraform, and after the first boot dsoxlab, the
hypervisors and the desktop. Documentation and locales other than English and
French are excluded from the packages, which is most of what keeps the image
under half a gigabyte.
The recipe is in packer/, built by the CI on a GitHub-hosted
runner. It is reproducible: nothing is hand-made in the image.
vmlabs under VirtualBox: work in progress. KVM inside VirtualBox behaves badly — a machine burning a core without booting, then a freeze. It is not a matter of memory or CPUs. Until that improves,vmlabs want dsoxlab on a plain Linux machine, or the appliance under KVM/QEMU;shelllabs work everywhere. See step 4.- One user, one machine. The appliance is not a shared classroom server; a trainer serving several learners wants the trainer's page.
- The disk declares 64 GB, and it grows on your side. It is thin: the file you download stays under 500 MB, and space is taken from your host only as you go. So there is nothing to enlarge — the three-node Kubernetes cluster that 20 GB could not hold now fits — but plan for the free space: one catalog with its base images and its VMs approaches thirty gigabytes, two go past it.
- No automatic update.
uv tool upgrade dsoxlabupdates the tool inside an appliance you already run. Importing a newer image only brings you an updated system: dsoxlab itself is installed fresh at every machine's first boot.
The image ships a French AZERTY keyboard, because the training is French. The layout data is in the image: nothing to download, and it works from the console before any network.
For another layout, one command:
sudo dpkg-reconfigure keyboard-configuration # then: sudo setupconThe system locale stays English, deliberately: an error message gets
searched word for word in a search engine. It is the same reason dsoxlab's own
log is written in English. fr_FR.UTF-8 is generated in the image all the same,
so switching does not mean reinstalling:
sudo localectl set-locale LANG=fr_FR.UTF-8And for dsoxlab's own interface, independently of the system:
export DSOXLAB_LANG=fr # or enIt downloads about 1.5 GB and takes several minutes. It does not block login: the prompt appears while it works.
Three ways to know where it stands, from simplest to most precise:
- Press Enter at the login prompt. It shows the current step —
gettyre-reads/etc/issueat every prompt. journalctl -u dsoxlab-premier-demarrage -fto follow it live.ls -l /var/lib/dsoxlab-premier-demarrage.fait: that marker exists only after a complete success.
Three signs that it is done: the machine reboots by itself, it comes back
to a desktop rather than a console, and dsoxlab --version answers.
On failure, the login prompt names the steps that failed, and nothing is lost: everything starts again at the next boot.
At the very first boot, before the login prompt, the machine asks three questions on its own console:
Keyboard layout
* 1) French (AZERTY) 2) Belgian 3) Swiss French
4) Canadian French 5) US (QWERTY) 6) German (QWERTZ)
Your choice [1] (30 s):
Then the timezone and dsoxlab's interface language.
The menus are numbered on purpose: digits sit in the same place on every layout, so answering "2" works whatever keyboard the machine believes it has — which is exactly the problem being solved.
You may answer nothing. After 30 seconds the starred value is kept: AZERTY,
Europe/Paris, French. A boot with nobody watching is therefore never blocked,
and dsoxlab.oobe=0 on the kernel command line skips the wizard entirely.
It does not run twice: its marker is /var/lib/dsoxlab-assistant.fait. To run
it again deliberately, remove that file and reboot.