{"id":50728419,"url":"https://github.com/bouk/nixos-containers","last_synced_at":"2026-06-10T06:03:24.932Z","repository":{"id":343985644,"uuid":"1171503842","full_name":"bouk/nixos-containers","owner":"bouk","description":"Minimal NixOS Containers","archived":false,"fork":false,"pushed_at":"2026-03-30T08:05:58.000Z","size":7,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-30T10:09:55.928Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bouk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2026-03-03T09:55:54.000Z","updated_at":"2026-03-30T08:06:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bouk/nixos-containers","commit_stats":null,"previous_names":["bouk/nixos-containers"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bouk/nixos-containers","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bouk%2Fnixos-containers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bouk%2Fnixos-containers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bouk%2Fnixos-containers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bouk%2Fnixos-containers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bouk","download_url":"https://codeload.github.com/bouk/nixos-containers/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bouk%2Fnixos-containers/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34139191,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-06-10T06:03:24.267Z","updated_at":"2026-06-10T06:03:24.925Z","avatar_url":"https://github.com/bouk.png","language":"Nix","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nixos-containers\n\nImperatively deploy declarative NixOS containers via `systemd-nspawn`.\n\nContainers share the host's Nix store (read-only via bind mount) and have their system profile managed by the host at `/nix/var/nix/profiles/per-container/\u003cname\u003e/system`.\n\n## How it works\n\n- The **host module** (`bouk.containers`) creates `systemd-nspawn@.service` units and the required directory structure for each container.\n- The **guest module** sets up the system config for containerization and enables `systemd-networkd` and `systemd-resolved`.\n- The **`nixos-deploy-container`** script evaluates a container's system on your local machine, copies the derivation to the target host, builds it into a profile, and activates it.\n\nOn reload, the running container's switches to the new configuration without a full restart (equivalent to `nixos-rebuild switch`). A full restart only happens when the nspawn or service config changes.\n\n## Setup\n\n### 1. Add to your flake inputs\n\n```nix\ninputs = {\n  bouk-nixos-containers.url = \"github:bouk/nixos-containers\";\n};\n```\n\n### 2. Configure the host\n\nImport the host module in your host NixOS configuration and declare containers:\n\n```nix\n{ inputs, ... }:\n{\n  imports = [ inputs.bouk-nixos-containers.nixosModules.host ];\n\n  bouk.containers = {\n    mycontainer = {\n      # Optional: override the systemd service unit\n      serviceConfig = { };\n\n      # Optional: override the systemd.nspawn unit\n      nspawnConfig = {\n        networkConfig.VirtualEthernet = false; # Use host networking\n      };\n    };\n  };\n}\n```\n\nEach declared container gets:\n- A `systemd-nspawn@\u003cname\u003e` service started on boot\n- `/nix/var/nix/profiles/per-container/\u003cname\u003e/` for the system profile\n- `/var/lib/machines/\u003cname\u003e/` as the container root\n\n\u003e **Note:** Until [NixOS/nixpkgs#498177](https://github.com/NixOS/nixpkgs/pull/498177) is merged, you also need to allow DHCP on the virtual ethernet interfaces so containers can get an address (unless you're using host networking):\n\u003e\n\u003e ```nix\n\u003e networking.firewall.interfaces.\"ve-+\" = {\n\u003e   allowedUDPPorts = [ 67 ];\n\u003e };\n\u003e ```\n\n### 3. Configure the guest (container)\n\nImport the guest module in the container's NixOS configuration:\n\n```nix\n{ inputs, ... }:\n{\n  imports = [ inputs.bouk-nixos-containers.nixosModules.guest ];\n}\n```\n\nThe guest module:\n- Sets `boot.isNspawnContainer = true`\n- Disables Nix (the host manages the profile)\n- Enables `systemd-networkd` and `systemd-resolved`\n\n### 4. Add your container to `nixosConfigurations`\n\n```nix\nnixosConfigurations = {\n  mycontainer = nixpkgs.lib.nixosSystem {\n    system = \"x86_64-linux\";\n    modules = [\n      ./containers/mycontainer.nix\n    ];\n  };\n};\n```\n\n## Example\n\nThis example sets up a container named `mycontainer` that serves \"hello world!\" via nginx, with the host proxying to it.\n\n### Guest configuration (`containers/mycontainer.nix`)\n\n```nix\n{ inputs, ... }:\n{\n  imports = [ inputs.bouk-nixos-containers.nixosModules.guest ];\n\n  services.nginx = {\n    enable = true;\n    virtualHosts.\"mycontainer\" = {\n      locations.\"/\" = {\n        return = \"200 'hello world!'\";\n        extraConfig = \"add_header Content-Type text/plain;\";\n      };\n    };\n  };\n\n  networking.firewall.allowedTCPPorts = [ 80 ];\n}\n```\n\n### Host configuration\n\n```nix\n{ inputs, ... }:\n{\n  imports = [ inputs.bouk-nixos-containers.nixosModules.host ];\n\n  bouk.containers.mycontainer = { };\n\n  services.nginx = {\n    enable = true;\n    virtualHosts.\"example.com\" = {\n      locations.\"/\" = {\n        proxyPass = \"http://mycontainer\";\n      };\n    };\n  };\n}\n```\n\n## Deploying\n\nRun `nixos-deploy-container` from your flake directory:\n\n```\nnixos-deploy-container [-v] \u003cmachine\u003e \u003ctarget\u003e [container]\n```\n\n| Argument | Description |\n|---|---|\n| `machine` | The `nixosConfigurations` attribute name for the container |\n| `target` | SSH destination of the host machine (e.g. `root@myserver`) |\n| `container` | Container name on the host (defaults to `machine`) |\n\n**Example:**\n\n```bash\n# Deploy \"mycontainer\" config to the container named \"mycontainer\" on myserver\nnixos-deploy-container mycontainer root@myserver\n\n# Deploy \"mycontainer\" config to a differently-named container\nnixos-deploy-container mycontainer root@myserver mycontainer-prod\n```\n\nUse `-v` for verbose output.\n\n### Running without installing\n\n```bash\nnix run github:bouk/nixos-containers -- mycontainer root@myserver\n```\n\n### Get a shell in the container\n\n```bash\nssh -t root@myserver -- systemd-run -tPGM mycontainer -- /run/current-system/sw/bin/bash\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbouk%2Fnixos-containers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbouk%2Fnixos-containers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbouk%2Fnixos-containers/lists"}