VNG(1)

📦
version 1.42 · 6 versions
, in arch rolling

💅 vng(1) — the virtme-ng era

okay so bestie. welcome to vng(1), aka the virtme-ng manual, and no cap this thing is a whole vibe. it's giving "run your kernel in a little virtual snowglobe made of your actual live system" 🦋 and honestly? iconic.

🌸 NAME

vng — quickly run kernels inside a virtualized snapshot of your live system. literally that's the whole pitch. 🔥

✨ SYNOPSIS

okay so here's the full invocation, copied EXACTLY because we do not mess with syntax in this house:

vng [-h] [--version] [--run [RUN] | --build | --clean | --dump DUMP |
--mcp] [--dry-run] [--no-virtme-ng-init] [--empty-passwords] [--pin
[PIN]] [--gdb] [--snaps] [--debug] [--kconfig] [--skip-modules]
[--commit COMMIT] [--config CONFIG] [--configitem CONFIGITEM] [--busybox
PATH_TO_BUSYBOX] [--qemu QEMU] [--name NAME] [--user USER] [--shell
BINARY] [--root ROOT | --root-disk IMAGE] [--root-dev DEVICE] [--root-
fstype FSTYPE] [--root-release ROOT_RELEASE] [--rw] [--no-root-posix-
acl] [--force-9p] [--disable-microvm] [--disable-kvm] [--disable-
monitor] [--cwd CWD] [--rodir RODIR] [--rwdir RWDIR] [--overlay-rwdir
OVERLAY_RWDIR] [--cpus CPUS] [--memory MEMORY] [--numa
MEM[,cpus=FIRST_CPU1[-LAST_CPU1]][,cpus=FIRST_CPU2[-LAST_CPU2]]...]
[--numa-distance SRC,DST=VAL] [--balloon] [--network NETWORK] [--no-
dhcp] [--net-mac-address NET_MAC_ADDRESS] [--disk PATH] [--exec EXEC]
[--append APPEND] [--force-initramfs] [--sound] [--graphics] [--fb]
[--verbose] [--quiet] [--qemu-opts QEMU_OPTS] [--jobs N] [--build-host
BUILD_HOST] [--build-host-exec-prefix BUILD_HOST_EXEC_PREFIX] [--build-
host-vmlinux] [--arch ARCH] [--cross-compile CROSS_COMPILE] [--force]
[--nvgpu [GPU PCI Address]] [--vfio-pci PCI_ADDRESS] [--console [PORT]]
[--console-client [PORT]] [--ssh [PORT]] [--ssh-client [PORT]] [--ssh-
tcp] [--remote-cmd COMMAND] [--systemd] [envs ...]

yeah it's a lot. it's a lot lot. but we're gonna go through every single one together, hand in hand, like besties do 🫶

🎀 DESCRIPTION

Build and run kernels inside a virtualized snapshot of your live system

that's it. that's the product. you get a tiny VM that's a snapshot of your actual system and you shove a kernel into it. slay.

oh and also:

  • envs — additional Makefile variables 💜

💅 OPTIONS

okay deep breath. there are SO many. we're doing all of them. grab a snack. 🍓

  • --version, -V — show the program's version number and exit. short, sweet, self-explanatory.
  • --dry-run — only show the commands without actually running them. it's giving "look but don't touch" 💀
  • --no-virtme-ng-init — fall back to the bash virtme-init (useful for debugging/development). the old reliable, for when you're poking at things.
  • --empty-passwords — use empty passwords for all users. yes, all of them. 🙈
  • --pin [PIN], -P [PIN] — pin each QEMU vCPU thread to a distinct host CPU. if you give it no arguments, all host CPUs are used. if you give it an argument, it has to be a list/range of CPUs (e.g., 0,1,3-5,9). NOTE: only a single virtme-ng guest can be pinned at a time — pinning multiple virtme-ng guests is not supported yet. so like… one at a time, bestie 😭
  • --gdb — attach a debugging session to a running instance that was started with --debug. debugging bestie hours.
  • --snaps — allow executing snaps inside virtme-ng. 📦
  • --debug — start the instance with debugging enabled: lets you generate crash dumps, attach a debugging session with GDB, etc. main character debugging energy 🔥
  • --kconfig, -k — only override the kernel .config without building/running anything. just the config. nothing else. periodt.
  • --skip-modules, -S — run a really fast build by skipping external modules (no external modules support). zoom zoom ⚡
  • --commit COMMIT, -c COMMIT — use a kernel identified by a specific commit id, tag or branch. pick your fave.
  • --config CONFIG, --custom CONFIG, -f CONFIG — use one (or more) kernel .config snippet files, or - for stdin. 🧚
  • --configitem CONFIGITEM — add a CONFIG_ITEM=val, after --config <fragments>; these override previous config settings. so they win the argument.
  • --busybox PATH_TO_BUSYBOX — use the specified busybox binary.
  • --qemu QEMU — use the specified QEMU binary.
  • --name NAME — set guest hostname and qemu -name flag. name your child 🎀
  • --user USER — change user inside the guest (default is same user as the host).
  • --shell BINARY — override the default user shell.
  • --root ROOT — pass a specific chroot to use inside the virtualized kernel (useful with --arch).
  • --root-disk IMAGE — boot from a disk image attached over virtio-blk instead of exporting a host directory as the guest root (useful with --arch).
  • --root-dev DEVICE — the guest device holding the root filesystem of --root-disk, e.g. /dev/vda for the whole image, or /dev/vda3 for its third partition (default: /dev/vda). third partition girlies rise 🙌
  • --root-fstype FSTYPE — filesystem of --root-disk's root device, e.g. ext4, so its module can be loaded instead of requiring it built into the kernel.
  • --root-release ROOT_RELEASE — use a target Ubuntu release to create a new chroot (used with --root).
  • --rw — give the guest read-write access to its root filesystem. > WARNING: this can be dangerous for the host filesystem! like fr fr be careful 💀 no cap.
  • --no-root-posix-acl — disable POSIX ACL support for external root virtiofs exports (ignored with 9p, host root, or --root-disk).
  • --force-9p — use the legacy 9p filesystem as rootfs. vintage ✨
  • --disable-microvm — avoid using the "microvm" QEMU architecture (only on x86_64).
  • --disable-kvm — avoid using hardware virtualization / KVM.
  • --disable-monitor — disable the QEMU STDIO monitor.
  • --cwd CWD — change guest working directory (default is the current working directory when possible).
  • --rodir RODIR — supply a read-only directory to the guest. use --rodir=path or --rodir=guestpath=hostpath. 🔒
  • --rwdir RWDIR — supply a read/write directory to the guest. use --rwdir=path or --rwdir=guestpath=hostpath. 🔓
  • --overlay-rwdir OVERLAY_RWDIR — supply a directory that is r/w to the guest but read-only in the host. use --overlay-rwdir=path. best of both worlds, honestly obsessed 🦋
  • --cpus CPUS, --cpu CPUS, -p CPUS — set guest CPU count (qemu -smp flag), or 'host' to mirror the available host CPU topology and pin each vCPU.
  • --memory MEMORY, -m MEMORY — set guest memory size (qemu -m flag).
  • --numa — takes MEM[,cpus=FIRST_CPU1[-LAST_CPU1]][,cpus=FIRST_CPU2[-LAST_CPU2]]... — create a NUMA node in the guest. use this option multiple times to create more NUMA nodes. the total memory size assigned to NUMA nodes must match the guest memory size (specified with --memory/-m). this option implicitly disables the microvm architecture. so like, pick a lane.
  • --numa-distance SRC,DST=VAL — set a distance of VAL between NUMA node SRC_NODE and DST_NODE. use this option multiple times to define multiple distances between NUMA nodes. this option is only used together with --numa. (they're a package deal 💜)
  • --balloon — allow the host to ask the guest to release memory. polite host behavior tbh.
  • --network NETWORK, -n NETWORK — enable network access: user, bridge(=<br>), loop.
  • --no-dhcp — disable DHCP configuration for network interfaces.
  • --net-mac-address NET_MAC_ADDRESS — the MAC address to assign to the NIC interface, e.g. 52:54:00:12:34:56. the last octet will be incremented for the next network devices. cute little counter 🎀
  • --disk PATH, -D PATH — add a file as a virtio-scsi disk (can be used multiple times).
  • --exec EXEC, -e EXEC — execute a command inside the kernel and exit. in and out, ghost mode 👻
  • --append APPEND, -a APPEND — additional kernel boot options (can be used multiple times).
  • --force-initramfs — use an initramfs even if it's unnecessary.
  • --sound — enable audio device (if the architecture supports it). 🔊
  • --graphics, -g — show graphical output instead of using a console.
  • --fb — show graphical console, but do not start any graphics server (mutually exclusive with --graphics). they cannot both slay. 💅
  • --verbose, -v — increase console output verbosity. talk to me talk to me
  • --quiet, -q — override verbose mode (disable --verbose).
  • --qemu-opts QEMU_OPTS, -o QEMU_OPTS — additional arguments for QEMU (can be used multiple times) or bundled together: --qemu-opts='...'.
  • --jobs N, -j N — build kernel with N jobs (default: number of cores).
  • --build-host BUILD_HOST — perform the kernel build on a remote server (ssh access required).
  • --build-host-exec-prefix BUILD_HOST_EXEC_PREFIX — prepend a command (e.g., chroot) to the make command executed on the remote build host.
  • --build-host-vmlinux — copy vmlinux back from the build host. bring it home 🥺
  • --arch ARCH — generate and test a kernel for a specific architecture (default is the host architecture; if set, to be used with --root or --root-disk).
  • --cross-compile CROSS_COMPILE — set cross-compile prefix.
  • --force — force reset the git repository to the target branch or commit (warning: this may drop uncommitted changes), and force kernel config override. > like, this one will literally throw away your uncommitted changes. be SO careful. 😭
  • --nvgpu [GPU PCI Address] — add a passthrough NVIDIA GPU.
  • --vfio-pci PCI_ADDRESS — pass through a PCI device using vfio-pci (can be used multiple times), e.g. --vfio-pci 0000:ce:00.0.
  • --systemd — execute systemd as init (EXPERIMENTAL). experimental!! you've been warned 💀

⭐ ACTION

these are the "what are we even doing" flags:

  • --run [RUN], -r [RUN] — run a specified kernel. --run can accept one of the following arguments: 1) nothing (in this case it'll try to boot the same kernel running on the host), 2) a kernel binary (like ./arch/x86/boot/bzImage), 3) a directory (where it'll try to find a valid kernel binary file), 4) an upstream version, for example vng --run v6.6.17 (in this case vng will download a precompiled upstream kernel from the Ubuntu mainline repository). look at all those options, she's versatile 👑
  • --build, -b — build the kernel in the current directory (or remotely if used with --build-host).
  • --clean, -x — clean the kernel repository (local, or remote if used with --build-host).
  • --dump DUMP, -d DUMP — generate a memory dump of the running kernel (the instance needs to be started with --debug). memory dump, but make it forensic 🕵️
  • --mcp — start the MCP (Model Context Protocol) server for AI agent integration. ai bestie integration, we love to see it 🌈

🦋 REMOTE CONSOLE

the long-distance relationship section 💌

  • --console [PORT] — enable a server to communicate later from the host using '--console-client'. by default, a simple console will be offered using a VSOCK connection, and 'socat' for the proxy.
  • --console-client [PORT] — connect to a VM launched with the '--console' option for a remote control.
  • --ssh [PORT] — enable an SSH server to communicate later from the host to using '--ssh-client'.
  • --ssh-client [PORT] — connect to a VM launched with the '--ssh' option for a remote control.
  • --ssh-tcp — use TCP for the SSH connection to the guest.
  • --remote-cmd COMMAND — to start in the VM a different command than the default one (--server), or to launch this command instead of a prompt (--client).

💬 COMMENTS 💬

okay bestie, gather round, because this is the whole why of virtme-ng and it's honestly iconic ✨

virtme-ng is a tool that lets you easily and quickly recompile and test a Linux kernel, starting straight from the source code. Like, you don't have to do the whole sad little ritual. You can recompile the kernel in a few minutes (rather than hours, yes HOURS 😭), and then the kernel just... starts itself. Automatically. In a virtualized environment that is an exact copy-on-write copy of your live system 💅

which means — and this is the slay part — any changes you make to that virtualized environment do not affect the host system. none. zero. the host is untouched and unbothered, main character energy only 👑

so how does this little magic trick work? 🪄

a minimal config is produced (with the bare minimum support needed to test the kernel inside qemu), then the kernel you selected is automatically built and started inside qemu, using the filesystem of the host as a copy-on-write snapshot. 🦋

which means you can literally destroy the entire filesystem, crash the kernel, do your worst — none of it touches the host. go feral fr fr 💀🔥

NOTE: kernels produced with virtme-ng are lacking lots of features, on purpose, to reduce the build time to the absolute minimum while still giving you a usable kernel that can run your tests and experiments. so like... it's a vibe, not a full-featured distro kernel, iykyk 🙈

and for the lore keepers 🎀: virtme-ng is based on virtme, written by Andy Lutomirski <luto@kernel.org>. credit where credit is due, periodt.

👑 AUTHOR 👑

virtme-ng is written by Andrea Righi <arighi@nvidia.com> 💖

based on virtme by Andy Lutomirski <luto@kernel.org> 🫶

🎀 DISTRIBUTION 🎀

the latest version of virtme-ng may be downloaded from:

https://github.com/arighi/virtme-ng

go get it bestie, it's giving essential tooling 🌈⭐

and that's the whole page!! 🎉 this was virtme-ng version 1.42, dated 2026-10-13, living its best life as VNG(1) in section 1 of the manual 💜 now go recompile a kernel in a few minutes and think of me 💅✨🧚

📦 where this page comes from