One Source of Truth: NixOS Configuration from NetBox

The goal

Our client organization runs a large server fleet. Network engineers document all network devices, interfaces, VLANs, IP addresses, and services in NetBox, and existing tooling turns those changes into Ansible scripts for the fleet.

A part of this organization started adopting NixOS, and it had to fit into that existing process. For that to last, NixOS had to become a normal part of how the fleet is run, not a special case beside it. This story shows how NixOS fit into their existing network process and removed extra work.

Integration into established processes

NetBox and NixOS don’t play well together by default. Every NixOS machine had to be onboarded twice: First, all network-related machine configuration is entered into a NetBox database. Then, the same information is encoded again into a new NixOS configuration.

Such duplication is laborious and prone to error and drift, especially across tens or hundreds of servers, so each new machine costs more to add and slows adoption. Most network engineers are not NixOS engineers, so a different team often ends up handling the second entry.

Machines running legacy Linux distributions, with existing tooling, had none of these problems. So every new NixOS machine was more work than the established alternative, and the main payoff of this integration was removing that extra cost and making adoption easier. NixOS didn’t lack technical advantage because of reproducibility or declarativity; it lacked a place in the established processes the organization already relied on.

Missing parts

The first question was not how to generate configuration, but which team owned the data. In this organization, network engineers do, and they should not need to learn Nix to design networks. So the NixOS side has to adapt to that boundary. The client’s network engineers would continue using NetBox, and the NixOS infrastructure should follow automatically.

Before building anything, we looked at existing solutions: NLnet even funded the project NixBox, but it went stale in ~2024. It is also Nix-first and writes back to NetBox, which is the opposite of what this organization wanted/needed.

At least three of our other customer organizations built similar tooling for internal use. We asked if they could share or open-source the code to avoid duplicate effort. None of them could, for legal and other reasons.

Integration

The NetBox-NixOS-config generator we built is small on its own, but its value comes from how it fits customer processes. What mattered more was how it could integrate into customer processes.

It runs as a small server that reads from NetBox through its native GraphQL interface and acts like a normal Nix flake repository (i.e., it does not generate Nix files; it generates Nix expressions as a flake per HTTP request). Any NixOS configuration in git can take it as a flake input and consume the generated modules. NetBox stays the single source of truth because information is never written back.

This draws a clear line between the teams:

• NetBox provides host names, domains, interface configuration, VLANs, addresses, firewall ports, etc. from documented services.
• The client’s Nix code keeps everything NetBox doesn’t store: disks, partitioning, boot loader, users, secrets, software.

Each team keeps working with its own tools and responsibilities. Network engineers keep structuring shared settings by site, role, and platform in NetBox. In contrast, NixOS engineers keep composing machines with NixOS modules, and the two tool-native merge mechanisms fit together (NetBox’s weights, NixOS’s module system types). You can switch off or override any generated part.

The client’s production version is written in Rust. It adds immutable, versioned URLs and per-server modules, and covers more of the NetBox data model: prefixes, routes, VRFs, tunnels.

Result

The client now configures their NixOS machines declaratively from the same NetBox data as the rest of the network, so the process stays consistent, and the added work disappears. New NixOS servers are entered into the NetBox database, then their generated NixOS modules are combined with common server modules for deployment.

Interfaces, VLANs, addresses, hostnames, and firewall ports are generated, not hand-maintained. Audit documentation can come from NetBox, and proving it matches the live network takes less work because documentation and configuration can’t drift apart.

This removes the obstacle that made every new NixOS machine more expensive, so further NixOS adoption can follow the organization’s established process.

Open sourcing

Three organizations had already built this tool for themselves and couldn’t share it afterward. This was outside the original request, but we brought that observation to the client and made the case for releasing theirs:

• It is supporting infrastructure, not intellectual property or secret knowledge.
• Outside users and collaborators find different bugs and implement different features that everyone can reuse for free.
• Any Nix engineer can maintain code in the open, reducing the client’s dependence on individual contractors, including us.

The client decided not to become the fourth organization with a private solution. It’s currently being released as open source, with the idea presented publicly at NixCon 2026.

Value proposition

• A new NixOS machine takes one entry, made by the team that already owns the data, so the added work disappears.
• Audit documentation can’t drift from the live configuration.
• Network engineers don’t have to learn Nix, and NixOS engineers don’t have to re-enter network data.
• NixOS now fits the organization’s normal process instead of competing with it, removing the old adoption penalty and making the payoff obvious.
• The client’s tool will no longer be something it has to maintain on its own.

What began as duplicated network data ended with NixOS as a regular part of the organization, and with a tool others can build on, making the core payoff clear and concrete.