Overview
What nspawn is, what it is not, and how images, machines, the hub and systemd fit together.
Documentation
How to install nspawn, pull images from the hub, run machines and apps, wire their network, build your own images and configure the tool.
nspawn manages systemd-nspawn machines: images come from an OCI registry (the hub, Docker Hub or any other), are stored as shared layers and are started, inspected and stopped through the D-Bus APIs of systemd-machined and systemd. The work is done by a service on the system bus and the command line is its client. This documentation describes nspawn 3.1.0.
If you are new, start with the overview and then get started. The command reference lists every command and option.
Getting started
Requirements, installation, a first machine pulled from the hub and an app from Docker Hub.
Images and the hub
Image references, the hub and Docker Hub, search and credentials, what pull does, the storage backends, boot and app detection, more machines from one image, and where everything lives on disk.
Machines
Starting, running and stopping machines, how boot and app images differ, volumes, restart policies and limits, healthchecks, dependencies, GPUs, secrets, the commands for machines, and making them again elsewhere.
Networking
The nspawn0 bridge, networks of your own, published ports, DNS and machine names, how apps get their network, firewalls, veth, host, none, container:NAME, and physical interfaces.
Compose
docker compose files and commands, run by nspawn compose on nspawn’s machines.
Building images
Building an image from a Dockerfile with nspawn’s own builder, or with mkosi, through nspawn build, and uploading it to the hub or another registry with push.
The Docker API
The Docker Engine API on a socket of the host and in each machine that mounts /var/run/docker.sock, for the docker command, CI runners, reverse proxies and dashboards, and auto-update of the machines whose tag points to a newer image.
Configuration
The configuration file, environment variables and global flags, what wins when they disagree, and what is remembered per machine.
Command reference
Every command and option of nspawn 3.1.0.
FAQ
Short answers to the questions that come up most.
Contributing
Where the code lives, how to build and test it, and how to send changes.