# Proxmox-NixOS: An Experimental Proxmox VE Port for NixOS

> Proxmox-NixOS ports Proxmox VE to NixOS, with documented support for `x86_64-linux`, basic hypervisor administration, bridge configuration, and declarative VM bootstrap. The project explicitly advises against production use.

**SaumonNet/proxmox-nixos** — The Proxmox Hypervisor, on NixOS [maintainers=@camillemndn @julienmalka] 

- Repository: https://github.com/SaumonNet/proxmox-nixos
- Stars: 1,408 · Forks: 71
- Language: Nix
- License: AGPL-3.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/saumonnet-proxmox-nixos

## The NixOS Host Problem Addressed by Proxmox-NixOS

Proxmox-NixOS addresses a specific incompatibility between two administration models. Its README describes the project as a port of the Proxmox Hypervisor to NixOS. It is intended for operators who want Proxmox VE services and interfaces on a host managed through Nix configuration, rather than installing the conventional Proxmox host distribution.

The documented feature set covers basic hypervisor operations, including booting virtual machines and managing users. The README says these areas have been tested on real hardware. That claim does not extend to the entire Proxmox product. Clusters and high availability remain under development and testing, which makes them poor adoption targets without separate evaluation.

Platform support has an explicit boundary. Although the repository exports other architectures for convenience, only `x86_64-linux` is supported. Resolving an export on another architecture therefore does not mean Proxmox-NixOS can run there. Administrators evaluating ARM or other non-x86 systems must use a different host arrangement.

The project's maturity warning is more important than the feature list. The README calls Proxmox-NixOS experimental, advises against running it on production machines, and says users should be ready to fix issues themselves. The port can expose familiar Proxmox behavior through NixOS, but the repository does not document it as a production-certified replacement for upstream Proxmox VE.

## Module, Overlay, and nixmoxer Responsibilities

The host integration has three documented parts. Importing `proxmox-nixos.nixosModules.proxmox-ve` adds the project module. Setting `services.proxmox-ve.enable` to `true` enables the service, and `services.proxmox-ve.ipAddress` supplies the address entered into its configuration. Adding `proxmox-nixos.overlays.x86_64-linux` to `nixpkgs.overlays` exposes the ported packages to the NixOS build environment.

The repository layout separates concerns into `modules/`, `pkgs/`, and `tests/`. Within that layout, the host service and declarative VM interface are distinct modules. This separation matters because enabling the hypervisor does not automatically create every bridge or VM.

VM bootstrap uses the `virtualisation.proxmox` module to declare an ID, memory, CPU topology, disks, network devices, and an ISO. The `nixmoxer` utility reads those settings and uses the Proxmox API to create the VM and attach the installation media. With `autoInstall = true`, the utility generates an ISO that installs the declared configuration during VM setup.

The workflow ends after initial bootstrap. The README says a NixOS VM can then be rebuilt with tools such as `nixos-rebuild` or `colmena`. It also says later changes to the Proxmox bootstrap options are not applied by `nixmoxer`. That makes `nixmoxer` a creation utility, not a continuously reconciling controller for all `virtualisation.proxmox` fields.

For restricted API accounts, this division can be useful because a principal may receive permission to create and bootstrap one VM. The README does not document how later infrastructure changes are reconciled through the API, so operators should not assume that editing the module automatically updates an existing Proxmox VM.

## Installing proxmox-nixos through npins

The README documents npins as one method for adding the repository to a NixOS project. The command selects the `main` branch and records the resolved revision and archive hash in the generated source definition.

```bash
npins add github SaumonNet proxmox-nixos -b main
```

After the command completes, `sources.proxmox-nixos` can be imported from `./npins`. The following configuration fragment enables the service, assigns an IP address, adds the supported overlay, and imports the Proxmox VE module.

```nix
let
  sources = import ./npins;
  proxmox-nixos = import sources.proxmox-nixos;
in
{
  imports = [ proxmox-nixos.nixosModules.proxmox-ve ];
  services.proxmox-ve = {
    enable = true;
    ipAddress = "192.168.0.1";
  };
  nixpkgs.overlays = [ proxmox-nixos.overlays.x86_64-linux ];
}
```

The address `192.168.0.1` comes from the README example. It is not identified as a default, so it must be replaced with the address intended for the host.

For Flakes, the README uses `github:SaumonNet/proxmox-nixos` as the project input. It then imports `proxmox-nixos.nixosModules.proxmox-ve` and selects the overlay through `proxmox-nixos.overlays.${system}`. The example also declares `nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"`, but it warns against overriding the `nixpkgs-stable` input. The documented reason is strict: the only tested and supported pairing uses the upstream stable NixOS release.

The README provides no complete command for building or activating the first host, so the snippet is configuration guidance rather than a complete installation sequence. A binary cache is published at `https://cache.saumon.network/proxmox-nixos`, with public key `proxmox-nixos:D9RYSWpQQC/msZUWphOY2I5RLH5Dd6yQcaHIuug7dWM=`. The project says this cache avoids some power-intensive builds, but it does not provide a separate cache setup snippet.

## Creating the First VM through the Proxmox API

The first VM needs settings under `virtualisation.proxmox` in its NixOS configuration. The README example assigns `vmid = 101`, `memory = 4096`, four cores, two sockets, a `virtio` network device attached to `vmbr0`, and a 16GB SCSI volume stored at `local:16`. Its ISO field contains a derivation for the installation image.

The utility also accepts `nixmoxer.conf` with `host`, `user`, `password`, and `verify_ssl` keys. The README uses `host=192.168.0.3:8006`, `user=root`, a password placeholder, and `verify_ssl=0`. The password must be replaced. Disabling SSL verification, as the example does, changes the connection's trust behavior and should be reviewed rather than copied automatically.

A destination node must be specified through either `virtualisation.proxmox.node` or the `--node` option. If both are set, the command-line selection takes precedence. The documented invocation is:

```bash
nix run github:SaumonNet/proxmox-nixos#nixmoxer -- [--node NODE] myvm
```

The bracketed section shows optional syntax rather than literal input. When a node is available through the flake configuration, the command can be invoked without that optional segment. The utility then creates the VM on the selected Proxmox node and attaches the specified ISO.

The repository has no GitHub releases, so the documented `nix run` expression targets the GitHub flake source rather than a named release artifact. It should not be assumed to perform ongoing VM reconciliation. The README directs users back to ordinary NixOS rebuild tools after the first installation.

## Bridge Configuration and Persistence Boundaries

Proxmox bridge configuration is split between the module and NixOS networking. Adding a name to `services.proxmox-ve.bridges` makes that operating-system bridge visible in the Proxmox web interface. According to the README, this option does not create the bridge or otherwise configure OS networking. A second configuration layer must establish the bridge before attached VMs can use it.

With scripted networking, the README associates `vmbr0` with `ens18` through `networking.bridges.vmbr0.interfaces`. It assigns `networking.interfaces.vmbr0.useDHCP = lib.mkDefault true`, which requests DHCP through the bridge. The `systemd-networkd` example instead defines matching and bridge networkd objects, creates `vmbr0`, enables IPv4 DHCP, accepts IPv6 router advertisements, and requires the bridge to reach an online state.

The declarative VM example attaches its network device to `bridge = "vmbr0"`. These names must agree across the VM, `services.proxmox-ve.bridges`, and the actual NixOS network configuration. A Proxmox-visible bridge that does not exist at the OS level is not enough. Neither the bridge option nor the examples replace a complete firewall, VLAN, routing, or DNS design.

Hosts using impermanence face another explicit requirement. The README says `/var/lib/pve-cluster` must remain persistent to retain Proxmox configuration across reboots. The documented assignment adds that directory to `environment.persistence."/persistent".directories`. Without persistence, reboot behavior can discard configuration stored below the ephemeral root even though the service is declared declaratively.

## Experimental Limits, Upstream Alternative, and Upgrade Cost

The central limitation is stated in the README: Proxmox-NixOS is experimental, should not run on production machines, and may require users to repair their own issues. Basic VM booting and user management are documented as tested, but clusters and high availability are still under development and testing. That uneven coverage means operators should select individual workflows for evaluation rather than assume parity with upstream Proxmox.

A real alternative is the upstream Proxmox Hypervisor. Proxmox-NixOS follows the Proxmox VE model inside NixOS and adds a Nix module for declarative initial VM settings. The `nixmoxer` utility then creates that VM through the API. A team that does not need Proxmox VE hosted by NixOS can avoid the experimental port and its bridge, persistence, and stable-NixOS integration requirements.

The repository uses the `AGPL-3.0` license. That states the project's declared license, but this article does not interpret its obligations for a particular deployment.

The repository is not archived, and its last push was on 2026-10-13. That recent push does not resolve the project's experimental warning. There are also no GitHub releases, so the repository offers no documented release cadence for estimating upgrades. The README does not describe rollback, schema migration, or a tested upgrade sequence. Before an upgrade, verify the stable NixOS pairing first, then test VM boot, API bootstrap, bridge persistence, and cluster configuration retention on an isolated host.

## Conclusion

Adopt Proxmox-NixOS for evaluation on `x86_64-linux`, particularly when Proxmox VE must run within a declarative NixOS host. Do not treat it as a documented production choice unless the organization accepts experimental software and assumes responsibility for repairs. Before deployment, verify compatibility with the upstream stable NixOS release, test basic VM and user-management workflows in isolation, and confirm that `/var/lib/pve-cluster` and every VM bridge are configured correctly.

## FAQ

### Can Proxmox-NixOS be used in production?

The README explicitly advises against running Proxmox-NixOS on production machines. It calls the project experimental and says users should be prepared to fix issues themselves.

### Which CPU architectures does Proxmox-NixOS support?

Proxmox-NixOS supports `x86_64-linux` only. The project exports other architectures for convenience, but the README does not claim support for them.

### How does nixmoxer create the first Proxmox VM?

`nixmoxer` reads settings from the `virtualisation.proxmox` module and uses the Proxmox API to create the VM and attach its ISO. It is intended for initial bootstrap rather than continuous reconciliation.

### Are Proxmox clusters and high availability supported?

The README lists clusters and high availability as areas that remain under development and testing. They are not part of the documented basic feature set.

### Which Proxmox configuration directory must remain persistent?

The README requires `/var/lib/pve-cluster` to be persistent when the host uses impermanence. This preserves that Proxmox configuration across reboots.

## Sources

- [Issues](https://github.com/SaumonNet/proxmox-nixos/issues)
- [License: AGPL-3.0](https://github.com/SaumonNet/proxmox-nixos/blob/main/LICENSE)
- [README](https://github.com/SaumonNet/proxmox-nixos/blob/main/README.md)
- [SaumonNet/proxmox-nixos on GitHub](https://github.com/SaumonNet/proxmox-nixos)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/saumonnet-proxmox-nixos