nix-topology
Generate infrastructure and network diagrams as SVGs directly from NixOS configurations.
What is nix-topology?
nix-topology is a NixOS tool that automatically generates infrastructure and network diagrams from your NixOS configurations. It solves the problem of maintaining manual diagrams by extracting data directly from your system definitions and rendering it into visual SVGs. The tool creates both physical connection diagrams and network-centric views to document your infrastructure.
NixOS users and administrators managing multi-host setups, homelabs, or infrastructure who want automated, code-derived documentation. It's particularly useful for those using NixOS configurations across multiple nodes.
Developers choose nix-topology because it eliminates manual diagramming work, ensures diagrams stay synchronized with actual configurations, and provides a declarative way to document infrastructure. Its deep integration with NixOS allows automatic extraction of network and service information that would otherwise require manual tracking.
Overview
🍁 Generate infrastructure and network diagrams directly from your NixOS configurations
Use Cases
Best For
- Automatically documenting NixOS-based homelab infrastructure
- Generating network diagrams for multi-node NixOS deployments
- Visualizing microvm.nix guest relationships and connections
- Creating up-to-date infrastructure documentation from configuration code
- Documenting physical and logical network connections in NixOS environments
- Adding external devices like switches and routers to infrastructure diagrams
Not Ideal For
- Teams managing heterogeneous infrastructures with many non-NixOS devices
- Projects requiring fast, iterative diagram updates due to slow render times
- Users not already committed to NixOS and Nix flakes for system configuration
Pros & Cons
Pros
Leverages NixOS configurations to pull interface data from systemd-networkd, services, microvm.nix guests, and more, reducing manual input as highlighted in the README.
Generates both physical connection diagrams and network-centric views from the same configuration, providing comprehensive infrastructure insights without extra work.
Automatically propagates assigned networks through defined connections, ensuring logical consistency in diagrams and reducing configuration errors.
Allows manual addition of switches, routers, and printers via the global module system, extending diagram usefulness beyond NixOS hosts.
Cons
Lacks support for common tools like Podman, Docker, and nftables, as admitted in the TODO list, limiting automation for mixed or container-heavy setups.
Requires integrating overlays, modules, and global topology definitions with Nix flakes, which can be daunting for users unfamiliar with NixOS's module system.
Render times can be slow for large configurations, and the tool struggles with handling bigger PNGs, as noted in the README's installation section.
Frequently Asked Questions
Related Projects
Home ManagerManage a user environment using Nix [maintainer=@khaneliman, @rycee]
nix-darwinManage your macOS using Nix
NixOS hardwareA collection of NixOS modules covering hardware quirks.
NixOS-WSLNixOS on WSL [maintainer=@nzbr]
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.