Nspawn 3.0 brings Docker API compatibility to systemd-nspawn containers

The Nspawn project has released version 3.0, a significant update that adds a Docker-compatible Engine API for managing systemd-nspawn containers. Published on November 7, 2026, this release allows developers and system administrators to use familiar Docker tooling, such as the docker command-line interface and GitLab Runner, to interact with nspawn machines. This move bridges the gap between lightweight systemd-based isolation and the extensive ecosystem of Docker-compatible orchestration tools.

What happened

Nspawn 3.0 introduces a new API socket located at /run/nspawn/api.sock on the host system. Unlike previous versions where the socket inside a machine was read-only, this update enables full management capabilities when mounted read-write. Users can now create, start, execute commands in, and remove containers, as well as pull images and manage volumes and networks through the API. The service is designed to be compatible with existing Docker clients, allowing teams to leverage their current workflows without migrating to a different container runtime entirely.

The release also includes immediate follow-up updates in versions 3.1.0 and 3.2.0. Version 3.1.0 adds support for dynamic device access via --device-cgroup-rule, which is useful for hardware tasks like flashing USB devices. Version 3.2.0 standardizes how machine and image names are resolved across commands, ensuring consistency whether users reference an image by its local name or its full reference. These rapid iterations address early feedback and refine the user experience for those adopting the new API.

Key details

• API Socket Access: The host socket /run/nspawn/api.sock supports read-write operations for full container lifecycle management, while read-only mounts restrict actions to logging and inspection.
• Breaking Changes: Records that are pulled or built but never run are now classified as images rather than containers, affecting how they appear in list and prune commands.
• Error Reporting: Failed methods now return specific error names under org.nspawn.Error, such as NotAuthorized, NoSuchMachine, and InUse, providing clearer debugging information.
• Environment Variables: Variables can now hold line breaks, and unset variables passed with -e VAR are omitted rather than causing errors, improving compatibility with complex configurations.
• Logging Improvements: The update prevents log loss due to journald rate limits by setting a microsecond interval with a high burst capacity, ensuring all output lines are captured.
• Known Gaps: Certain Docker features like swarm mode, plugins, and image builds via the API are not supported and return 501 errors; users must use nspawn build instead.

Background

Systemd-nspawn is a lightweight containerization technology built into the systemd init system, often used for running isolated services or testing environments without the overhead of full virtual machines. Historically, managing nspawn containers required specific command-line tools or custom scripts, which created friction for teams accustomed to the Docker ecosystem. Docker’s Engine API has become a de facto standard for container orchestration, supported by a vast array of third-party tools, CI/CD pipelines, and monitoring solutions.

By implementing a Docker-compatible API, Nspawn 3.0 allows these existing tools to communicate with nspawn machines as if they were Docker containers. This compatibility layer does not replace the native nspawn command but offers an alternative interface for automation and integration. It enables organizations to retain the security and simplicity of systemd-based containers while utilizing the rich tooling landscape developed around Docker.

Why it matters

For teams running self-hosted software, this release significantly reduces the operational burden of maintaining custom container management scripts. Engineers can now use standard Docker commands to inspect logs, manage volumes, and deploy services within nspawn environments. This is particularly valuable for CI/CD pipelines, such as those using GitLab Runner, which can now target nspawn machines directly using their Docker executor. This compatibility simplifies migration paths for projects that want to leverage systemd’s isolation features without abandoning their existing automation infrastructure.

However, the introduction of read-write API access requires careful security consideration. Since root inside a machine with a read-write mounted socket can control other machines and view environment variables, proper configuration is critical. Teams must ensure that only trusted services have write access to the API socket, while read-only mounts should be used for monitoring tools like Traefik or Dozzle. Understanding these permissions is essential to maintain the security boundaries that make nspawn an attractive option for self-hosting.

What you can do

• Evaluate Compatibility: Test your existing Docker-based tools and scripts against the Nspawn 3.0 API to identify any unsupported features, such as swarm mode or image builds.
• Secure API Access: Configure socket mounts carefully, using read-only permissions for monitoring tools and restricting read-write access to trusted management services only.
• Update CI Pipelines: If using GitLab Runner or similar tools, configure them to use the Nspawn API socket to leverage systemd-nspawn for job execution.
• Review Logging Settings: Verify that your logging infrastructure can handle the increased volume of logs now captured without journald rate limiting.
• Check Version Requirements: Ensure your host system meets the requirements for Nspawn 3.0 and consider upgrading to 3.2.0 for improved name resolution consistency.
• Monitor Known Gaps: Avoid relying on unsupported Docker API features like plugin management or container exports, and use native nspawn commands for these tasks instead.