Nspawn has added a writable Docker-compatible API, letting Docker clients manage its systemd-nspawn containers through a host socket. In a November 7 announcement, maintainer Eduard Tolosa describes support for GitLab Runner's Docker executor and a change existing users should check before upgrading: container-mounted API sockets that previously allowed only reads can now accept changes.
The feature belongs to Nspawn 3.0.0, the container-management project built around systemd-nspawn. The announcement already covers follow-up versions 3.1.0 and 3.2.0. This is a reading of the project's announcement and version-matched release notes. We haven't run Nspawn or tested client compatibility.
Docker clients get a different backend
The 3.0.0 release notes describe container creation, execution and removal through the API, alongside image pulls and volume and network management. The host endpoint is /run/nspawn/api.sock. Packages ship its systemd socket unit turned off, so installing the package alone doesn't enable this endpoint.
Tolosa's example configuration points GitLab Runner's Docker executor at that socket. The Docker command-line client can also use it through the DOCKER_HOST environment variable. For someone already operating Nspawn machines, the practical attraction is reusing software that speaks the Docker API to manage them.
That compatibility has a defined boundary. The release notes say image builds, loads, imports, tags, pushes and commits are unsupported through the API, along with container renames and exports. Those requests return HTTP 501. Tolosa says docker build against the socket doesn't work, while nspawn build does. A CI job that merely runs a prepared image therefore asks less of this API than a pipeline that also builds and pushes images.
Existing socket mounts gain authority
The breaking-change notice says a machine mounting /var/run/docker.sock, /run/docker.sock or /run/nspawn/api.sock read-write can now create and remove containers, execute commands inside them and manage images. Operators carrying an older proxy or dashboard configuration forward need to inspect how that socket is mounted.
A mount using :ro still permits reads, log following and kills, according to the release notes. Other changes return HTTP 403. The inclusion of kills matters: the project's restricted socket mode still allows that operation. Its recommendation is to use :ro for a reverse proxy or dashboard that only needs to read.
Host access has a separate permission check. The announcement says every user can connect to the socket, but polkit controls the operations they may perform. Reads and waits require org.nspawn.inspect; logs and changes require org.nspawn.manage. Tolosa warns that granting org.nspawn.manage gives a user root authority on the host because a machine can run commands as root and mount any host path.
Check the whole CI job
The documented gaps also include copying files to or from a stopped container's volumes: those volumes are mounted only while it runs. Together with the missing image-build API, that gives operators specific checks for a trial migration: follow a job through image preparation, execution and artifact collection, rather than stopping once a container starts.
The 3.2.0 release is already available, with further changes to how commands resolve image and machine names. For anyone evaluating the API now, the next useful evidence is a complete run of their own client workflow on a pinned version, including its socket permissions. The release documents enough compatibility to try that migration, but leaves several Docker operations explicitly unsupported.