nixos-container

Manage lightweight NixOS containers

TLDR

List running containers

$ sudo nixos-container list

Create a NixOS container with a specific configuration file

$ sudo nixos-container create [container_name] --config-file [nix_config_file_path]

Start, stop, terminate, or destroy a specific container

$ sudo nixos-container [start|stop|terminate|destroy|status] [container_name]

Run a command in a running container

$ sudo nixos-container run [container_name] -- [command] [command_arguments]

Update a container configuration

$ sudo $EDITOR /var/lib/container/[container_name]/etc/nixos/configuration.nix && sudo nixos-container update [container_name]

Enter an interactive shell session on an already-running container

$ sudo nixos-container root-login [container_name]

create
    Creates a new container named name. Requires a configuration file at `/etc/nixos/containers/.nix`.

start
    Starts the container named name.

stop
    Stops the container named name.

destroy
    Destroys the container named name, removing its file system.

status
    Shows the status of the container named name (running or stopped).

login
    Opens a shell inside the container named name.

run ...
    Runs a command inside the container named name.

info
    Shows information about the container named name from its configuration.

--help
    Displays help information.

--version
    Displays version information.

DESCRIPTION

The `nixos-container` command provides a convenient way to manage lightweight system containers in NixOS. It simplifies the creation, starting, stopping, and deletion of containers, leveraging NixOS's declarative configuration system for reproducible container environments. Containers are created with a minimal environment, using a NixOS configuration to define their specific needs (e.g., packages, services, users). This allows for isolated and reproducible testing or deployment of applications. Configuration files are written in the Nix language and placed in `/etc/nixos/containers/.nix`.

The command interacts directly with the `systemd-nspawn` tool to create and manage the container's lifecycle and allows easy interaction with the containers' shells. NixOS containers can be used to create isolated testing environments, development sandboxes, or to run services in an isolated manner.

CAVEATS

Requires root privileges to create, start, stop, and destroy containers.
The NixOS configuration in `/etc/nixos/containers/.nix` must be valid for container operations to succeed.

CONTAINER CONFIGURATION

The NixOS configuration file defines the container's environment. This includes the packages to install, the services to run, users, network settings and other aspects. The configuration must be written in the Nix expression language.

NETWORKING

By default, containers are isolated from the host network. You can configure networking within the container's NixOS configuration, enabling access to the host network or creating virtual networks.

HISTORY

The `nixos-container` command was developed as part of the NixOS project to provide a streamlined and declarative way to manage system containers. It leverages NixOS's configuration management capabilities to ensure that containers are reproducible and easily manageable. Over time, the command has been refined and extended to support various containerization use cases within the NixOS ecosystem.