{"id":23655994,"url":"https://github.com/fpletz/nixos-nspawn","last_synced_at":"2026-03-11T14:38:06.568Z","repository":{"id":248967327,"uuid":"830321649","full_name":"fpletz/nixos-nspawn","owner":"fpletz","description":"Declarative NixOS nspawn containers","archived":false,"fork":false,"pushed_at":"2025-11-05T17:52:43.000Z","size":101,"stargazers_count":38,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-18T07:03:03.577Z","etag":null,"topics":["containers","flake","networkd","nixos","nspawn","systemd"],"latest_commit_sha":null,"homepage":"https://fpletz.github.io/nixos-nspawn/","language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fpletz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["fpletz"],"ko_fi":"fpletz","liberapay":"fpletz"}},"created_at":"2024-07-18T03:56:45.000Z","updated_at":"2025-11-12T21:36:14.000Z","dependencies_parsed_at":"2024-07-18T06:30:47.870Z","dependency_job_id":"ce388e81-850a-4f6a-8440-a460925d1426","html_url":"https://github.com/fpletz/nixos-nspawn","commit_stats":{"total_commits":15,"total_committers":1,"mean_commits":15.0,"dds":0.0,"last_synced_commit":"67787c6069d94f0e2420d88b8d755d3d7c32b5f0"},"previous_names":["fpletz/nixos-nspawn-ephemeral","fpletz/nixos-nspawn"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/fpletz/nixos-nspawn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fpletz%2Fnixos-nspawn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fpletz%2Fnixos-nspawn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fpletz%2Fnixos-nspawn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fpletz%2Fnixos-nspawn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fpletz","download_url":"https://codeload.github.com/fpletz/nixos-nspawn/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fpletz%2Fnixos-nspawn/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30384106,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T14:10:17.325Z","status":"ssl_error","status_checked_at":"2026-03-11T14:09:37.934Z","response_time":84,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["containers","flake","networkd","nixos","nspawn","systemd"],"created_at":"2024-12-28T20:17:39.018Z","updated_at":"2026-03-11T14:38:06.548Z","avatar_url":"https://github.com/fpletz.png","language":"Nix","funding_links":["https://github.com/sponsors/fpletz","https://ko-fi.com/fpletz","https://liberapay.com/fpletz"],"categories":[],"sub_categories":[],"readme":"# Declarative NixOS nspawn containers\n\nThis is a work in progress proof of concept for a simple alternative to NixOS containers\nwith an opinionated minimal feature set.\n\nThe idea is to provide a minimal layer around systemd's existing nspawn facilities\nand simple networking using networkd on both sides. In contrast to standard NixOS containers,\nthe containers are by design ephemeral. No state is being kept across restarts. Directories\ncan be bind mounted into the container if state is explicitly needed.\n\nImperative containers are not in scope of this project for now. At some point, a `nixos-nspawn`\nexecutable could be added that does only supports networkd based default networking. This would\nprovide a simple way to spin up containers imperatively and keep things simple without the need\nto retain any configuration state.\n\nThe goal is to upstream this to nixpkgs at some point. Either as a new module or a replacement\nfor NixOS containers.\n\n## Use cases\n\n* Run services in different network namespaces for custom routing\n* Run multiple instances of a NixOS service on the same machine\n* Provide more isolation by default than the systemd service hardening options between services on the same machine\n* To accelerate NixOS VM tests that don't need multiple virtual machines to mock multiple nodes\n\n## How it works\n\nThe project provides a NixOS module for a host machine that create nspawn units and uses\nsystemd's `systemd-nspawn@` service to launch the containers. Only the nix store is bind\nmounted into the container and the nix daemon from the host is not passed into the container. \nUser namespaces with dynamic UID/GID allocation are enabled by default.\n\n### Networking\n\nBy default, a veth link is created between the host and the container and set up with networkd's\ndefault DHCP-based configuration. Additionally, `LinkLocalAddressing` and `MDNS` is enabled by default.\nThe networkd network units can be overridden easily to configure custom networking instead.\n\n### Operation\n\nMost `machinectl` commands can be used to manage these declarative containers like `start`,\n`stop`,`shell` and other commands not involving images work as expected. Using the `-M`\nflag tools like `systemctl` or `journalctl` can access containers from the host.\n\n## Open Issues\n\n* the whole host nix store is being bind mounted into the container\n  * explore if only needed store paths could be bind mounted instead\n  * maybe create an option to make a separate nix daemon instance available in the container\n* explore how to pass credentials into the container and provide an interface\n\n## How to use this\n\nYou can consume this flake and use the provided NixOS modules. See the `simple-container` check\nin `checks/simple-container.nix` for an example. If you are not using flakes, the NixOS modules\nare located in `host.nix` and `container.nix`.\n\n### Example: Simple Container\n\nSimple container called `mycontainer` running a plain NixOS instance with `htop` installed:\n\n```nix\n# NixOS configuration of host machine\n{\n  # import the module on the host\n  imports = [\n    # with flakes\n    inputs.nixos-nspawn.nixosModules.default\n    # OR\n    # without flakes\n    \"${builtins.fetchTarball \"https://github.com/fpletz/nixos-nspawn/archive/main.tar.gz\"}/modules\"\n  ];\n\n  virtualisation.nspawn.containers = {\n    mycontainer.config = { pkgs,... }: {\n      environment.systemPackages = [ pkgs.htop ];\n    };\n  };\n}\n```\n\nYou can use `machinectl shell mycontainer` to access a root shell in the container and run `htop`.\n\n### Example: Reverse Proxy on the host for container\n\nThe following NixOS configuration creates a container host with an nginx configured to reverse proxy\nto a container named `backend` with another nginx instance.\n\n```nix\n{\n  # reverse proxy on the host\n  services.nginx = {\n    enable = true;\n    recommendedProxySettings = true;\n    virtualHosts.\"_\".locations.\"/\".proxyPass = \"http://backend\";\n  };\n\n  virtualisation.nspawn.containers = {\n    backend = {\n      config = {\n        networking.firewall.allowedTCPPorts = [ 80 ];\n        services.nginx = {\n          enable = true;\n          virtualHosts.\"backend\".locations.\"/\".return = ''200 \"hack the planet\"'';\n        };\n      };\n    };\n  };\n}\n```\n\n### Example: Custom network configuration\n\nStatic network configuration is also possible:\n\n```nix\n{\n  virtualisation.nspawn.containers = {\n    testcontainer = {\n      config = { };\n      network.veth.config = {\n        # networkd network unit configs for host and container side\n        host = {\n          networkConfig = {\n            DHCPServer = false;\n            Address = [\n              \"fc42::1/64\"\n              \"192.168.42.1/24\"\n            ];\n          };\n        };\n        container = {\n          networkConfig = {\n            DHCP = false;\n            Address = [\n              \"fc42::2/64\"\n              \"192.168.42.2/24\"\n            ];\n            Gateway = [\n              \"fc42::1\"\n              \"192.168.42.1\"\n            ];\n          };\n        };\n      };\n    };\n  };\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffpletz%2Fnixos-nspawn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffpletz%2Fnixos-nspawn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffpletz%2Fnixos-nspawn/lists"}