macOS or Linux, x86-64 or arm64. Paste it into a terminal.
It installs uv if you do not have it, installs norboten 0.2.0, and opens it on a setup screen that installs QEMU and starts your first lab. Read the script first — it is under 200 lines and says what it does at the top.
Settings go on sh, after the pipe: NORBOTEN_VERSION=0.2.0 pins a version, NORBOTEN_EXTRAS=pdf adds PDF export of journals, NORBOTEN_YES=1 does not ask, and NORBOTEN_NO_LAUNCH=1 does not open norboten.
Pre-1.0, and it changes machine state. Norboten downloads golden images and runs QEMU virtual machines on your computer; a lab then deliberately breaks the machine it created, so run it on a computer whose time you can afford to lose and never on a production host. The API, the database and the lab format still change without migrations, and none of it has had a security review (!). Issues and labs are welcome.
| Item | Why |
|---|---|
| macOS or Linux | Lima's Windows driver has neither the disk snapshots nor the serial console the labs rely on; use WSL2 with nested virtualization |
| hardware virtualization | HVF or KVM; without it a VM boots in minutes instead of seconds |
| QEMU ≥ 8.2 | runs the lab VMs |
| about 4 GB free memory | one lab VM at a time is typical |
| up to 1.2 GiB disk per image | Alpine 110 MiB, Ubuntu 26.04 663 MiB (932 with the devops tools, 1141 with the automation ones), Rocky 10 814 MiB — plus a lab's own disk while it runs |
| Docker or Podman | only for the container labs; everything else runs without one |
Lima is not a prerequisite: norboten downloads and pins its own copy, checks its checksum, and keeps it in ~/.norboten. No directory of yours is ever mounted into a lab VM.
✓ platform macos on aarch64
✓ virtualization hardware acceleration (hvf)
✓ qemu QEMU 11.1.1 (/opt/homebrew/bin/qemu-system-aarch64)
✓ lima Lima 2.2.0 (pinned, private copy)
✓ ssh OpenSSH client
✓ memory 24.0 GiB RAM
✓ disk 50.3 GiB free
✓ containers docker (for the container labs)
READYIt runs as norboten opens; 8 (System) shows how to fix each item on your platform and d runs it again.
norboten opens one full-screen interface. The sections run along the top — 1 Home, 2 Labs, 3 Theory, 4 Journals, 5 Play, 6 Ratings, 7 You, 8 System — and the arrows walk between them. On the right, doctor's verdict and your lab sessions stay in view; the footer lists the keys that work where the cursor is, and ? lists all of them.
2 opens the catalogue: every lab with its track, level, time, your status and whether it is rated, and the briefing of the one under the cursor beside it. f narrows it to one track. Start with hello, a five-minute lab on Alpine, and press Enter. From a release without a checkout beside it, a lab you do not have yet comes down with u (pull), by its id.
s downloads the base image if it is not cached, boots a VM, takes a clean snapshot and then applies the faults. The first lab on a clean machine takes about 27 s, Lima's own download and the 110 MiB Alpine image included; an Ubuntu lab whose image is cached starts in 21.8 s. Both are measured. The status panel shows the VM, the image, the clock and the hints you have used.
The briefing tells you the symptoms and what will be graded, never the cause. o hands the terminal to a shell on the VM — the interface steps aside, and exit brings it back. w shows the checks turning green live as you work; h gives the next hint for a check, each one more specific, with the journal section or manual page it points at (l opens it); t asks the tutor, which never sees the solution. A machine that no longer boots is reached with k, the serial console.
c grades the machine, reboots it and grades it again; a check passes only if it passed both times. The Checks tab shows each check before and after the reboot, with a message written for someone who has just failed it. A fix that did not survive the boot shows up as exactly that.
r puts the machine back to its clean snapshot with the faults re-applied, in about ten seconds, as often as you like. After a pass (or S, surrender), m reviews how you got there, v shows the reference solution, j opens the lab's journal — the mechanism, one failure walked through, the wrong turns people take — and y the lab's theory questions. Esc goes back to the catalogue; the VM keeps running until z stops it.
The whole walk-through is in Getting started, every key in the TUI reference.
norboten updateOr u on System (8) when it says a newer release is out. Lab VMs, images and sessions stay.
norboten uninstallDeletes the lab VMs, ~/.norboten — images, sessions, recordings, sign-in — and the program, after asking. --keep-data keeps the directory; X on System does the same from the TUI.
Start with doctor: it runs as norboten opens and again on d, and 8 (System) lists every line with the fix for your platform. A ✓ is fine, a ! is a warning that only some labs care about, and a ✗ stops labs from running until it is fixed — the verdict under the list says READY or NOT READY. The problems below are the ones that come up, each with what you see, how to confirm it and the fix.
Confirm: ls ~/.local/bin/norboten. Fix: the script adds uv's tool directory to your shell's startup file, which only a new terminal reads; open one, or run export PATH="$HOME/.local/bin:$PATH".
Confirm: qemu-system-aarch64 --version (qemu-system-x86_64 on Intel and AMD). Fix: doctor prints the command for your package manager — brew install qemu, apt-get, dnf, pacman, zypper or apk — and i on the setup screen runs it after asking. On Rocky, RHEL or Alma QEMU is installed as /usr/libexec/qemu-kvm; tell norboten with export QEMU_SYSTEM_X86_64=/usr/libexec/qemu-kvm.
Confirm: on Linux, ls -l /dev/kvm and id -nG. Fix: /dev/kvm has to exist and your account has to be in the kvm group (sudo usermod -aG kvm $USER, then log in again — i offers it). Inside a cloud VM the provider must enable nested virtualization. Without acceleration a VM boots in minutes instead of seconds, so doctor treats it as a failure.
Confirm: the lima line on System, and ls ~/.norboten/lima. Fix: Lima is not a prerequisite — norboten downloads its pinned copy (about 35 MB) and checks its checksum. Behind a proxy, set HTTPS_PROXY before starting norboten; p on the setup screen tries again with a progress bar.
Confirm: echo $HOME — a long home directory, or NORBOTEN_HOME pointed somewhere deep. Fix: a UNIX socket path is capped at 104 bytes and Lima keeps its sockets under norboten's home, so give it a short one: export NORBOTEN_HOME=/tmp/norboten (or any short path), in your shell's startup file.
Confirm: docker info — when Docker Desktop is installed but stopped it does not fail, it hangs. norboten gives it ten seconds and then says no runtime is running. Fix: start Docker Desktop (or podman machine start) and press d. Only the container labs need it; every VM lab runs without one.
Confirm: the numbers on the doctor line: RAM under 8 GiB, or under 10 GiB free. Fix: an RHCSA lab needs about 2 GiB of free memory and a Rocky image about 5 GiB of disk; with less, prefer the Linux track (Alpine and Ubuntu). x on System removes a cached image you no longer need.
What you see: the lab's log says the download failed, or downloaded image has digest …, expected …. Fix: nothing half-downloaded is ever used — the file is checked against the digest in the image registry before it is installed, and a mismatch is deleted. Press s again (or p on the image on System) and it downloads from the start.
Confirm: System lists the cached images with their versions. Fix: a cached image is reused as long as it is there. Select it on System, x removes it and p pulls the current one; D on the lab destroys the VM built from the old one.
What you see: every check fails with The machine is not reachable over the network — it may be stuck during boot, and the serial console's last lines as evidence. Fix: that is often the lab working as intended — or your fix breaking the boot. k attaches to the serial console to see where it stopped, and b presses reset and lands you in the bootloader.
What you see: https://api.norboten.org is not reachable (ConnectError) on Ratings or You, or the API answered HTTP …. Confirm: curl -s https://api.norboten.org/readyz. Fix: labs, theory and journals never need the server, so everything else keeps working offline. For a server of your own, NORBOTEN_API points norboten at it.
What you see: the sign-in dialog (a) reports an error from the server. Fix: an account is only needed for rated labs, the boards and streaming; everything else works signed out. If the server says sign-in is not configured, it is a self-hosted server without its sign-in keys (see Self-hosting). A token that has expired simply asks you to sign in again.
r on the lab puts the machine back to the clean snapshot with the faults re-applied, in about ten seconds. D destroys the VM entirely; the next s builds a new one. norboten uninstall --keep-data removes only the program.