Running TailOS in QEMU

Try TailOS on your Linux machine in under two minutes — no hardware, no toolchain. For installing TailOS on real Raspberry Pi 3 hardware, see install_rpi3.md.

Prerequisites

That's it. Everything else is bundled in the prebuilt images.

Run TailOS (one command)

curl -sSL (private repository) | bash

The launcher will:

1. Check that QEMU is installed.
2. Download tail.rfs (kernel) and tail_disk.img (data disk) into ~/.cache/tailos/ on first run. Later runs reuse the cache.
3. Boot TailOS in QEMU with the correct flags.

When you see /$, the system is ready. Exit QEMU with Ctrl-A, then X.

Try the Shell

/$ help
/$ pwd
/$ ls /usr/bin
/$ /usr/bin/pidls
/$ cd /usr/bin
/usr/bin$ exit

The prompt shows the current directory (it changes after cd). The shell also supports arrow-key history, per-process cwd, and background jobs with &.

Manual Launch (alternative)

If you prefer not to run a remote script, do it by hand:

# 1. Install QEMU
sudo apt-get install -y qemu-system-aarch64 qemu-utils

# 2. Download the images
wget https://tail-os.com/wp-content/uploads/2025/09/tail.rfs
wget https://tail-os.com/wp-content/uploads/2025/09/tail_disk.img

# 3. Boot
qemu-system-aarch64 \
    -M raspi3b \
    -kernel tail.rfs \
    -serial mon:stdio \
    -drive file=tail_disk.img,format=raw,if=sd

What's Inside the Images

tail.rfs is a custom ELF container that bundles the entire OS:

tail.rfs
├── startup_rpi3              Early boot (EL3 -> EL1, MMU, jump to kernel)
├── kernel                    Microkernel (process, thread, IPC, scheduler)
├── uart_pl011                UART + TTY server (user-space)
├── sd_rpi3                   SD card block driver (user-space)
├── fat_file_system_server    Mounts tail_disk.img as "/"
├── debug_server              GDB remote protocol stub
└── tsh                       Shell

tail_disk.img is a FAT32 disk image exposed to the guest as an SD card:

tail_disk.img
├── /usr/bin/ls       Directory listing utility
└── /usr/bin/pidls    Process listing utility

Boot Sequence

qemu-system-aarch64 -M raspi3b
  |
  v
QEMU loads tail.rfs at 0x80000 (raspi3b entry point)
  |
  v
TailOS startup (_start.S)
  |-- Switch EL3 -> EL1
  |-- Initialize MMU, caches
  |-- Jump to kernel
  v
TailOS kernel
  |-- Initialize process/thread/IPC/memory subsystems
  |-- Load user-space servers from RFS
  |-- Mount tail_disk.img as "/" via SD + FAT
  |-- Start tsh shell
  v
/$ _

Troubleshooting

qemu-system-aarch64: command not found: Install QEMU with sudo apt-get install -y qemu-system-aarch64 qemu-utils.

No output at all in the QEMU window: The launcher passes -serial mon:stdio for you. If you're running QEMU by hand, make sure that flag is present — otherwise UART output goes nowhere visible.

Want to force a fresh download: Clear the cache: rm -rf ~/.cache/tailos and re-run the launcher.

QEMU boots but hangs before /$: The FAT filesystem takes several seconds to initialize on first boot; give it up to a minute. If it never appears, re-download the images (the cached copy may be corrupted) with rm -rf ~/.cache/tailos.

Exiting: Inside QEMU, press Ctrl-A, then X to quit. Ctrl-A, then C drops into the QEMU monitor (type quit).

See Also

• install_rpi3.md — Installing on Raspberry Pi 3 hardware
• buildsystem.md — Building TailOS from source (contributors)