Goblinmine/homelab-diagram

What it does

homelab-diagram turns a YAML description of a homelab into a large network diagram in the visual style of diagrams posted on r/homelab. The picture shows the internet path through the ISP router and firewall to the core switch, every switch port with its VLAN tagging, cables whose line width encodes the negotiated link speed, device cards with model, IP, hostname and OS, Proxmox hosts with their VMs and containers, TrueNAS pools with disks and usage, and DMZ containers by CT ID README.

The main caution comes from the author: this is not a general-purpose tool. Content lives in inventory.yaml, but layout coordinates (where each box, port and cable sits) are hand-placed in build.py for one specific network. Reusing it means moving coordinates. See the example output for what the result looks like.

How it works

build.py draws an SVG with hand-placed coordinates, embeds icons, and converts the result to PNG with rsvg-convert. Some label widths are measured with Pillow so badges fit their text. By default the real domain is replaced with redacted.com and SSIDs are generic; --unredacted renders the real values from the inventory for private use.

Getting started

Requirements: Python 3 with PyYAML (Pillow optional but improves label widths), rsvg-convert from librsvg for PNG output, and the Fira Sans and Fira Code fonts available through fontconfig. On Arch/CachyOS: pacman -S python-yaml python-pillow librsvg ttf-fira-sans ttf-fira-code. On Debian/Ubuntu: apt install python3-yaml python3-pil librsvg2-bin fonts-firacode plus Fira Sans.

Then, from a clone:

python3 fetch_icons.py          # downloads service icons into icons/ (once)
python3 build.py                # → out/homelab.svg + out/homelab.png (redacted)
python3 build.py --unredacted   # → out/homelab-unredacted.svg + .png

Service icons are not stored in the repo; fetch_icons.py pulls them from homarr-labs/dashboard-icons. Only the author's own small glyphs (CPU, RAM, SSD and similar) are bundled.

Adapting it to your lab

1. Rewrite inventory.yaml: texts, IPs, ports, VLAN colors and container groups all come from there.
2. Render, then adjust layout coordinates in build.py for anything that does not fit; the README points to the variables fy, fh, ox, oy, bx, by, DY and MAD for the top section and server-card columns.
3. Add icons by dropping an SVG into icons/ and referencing its file name in the inventory.

There is also a CLAUDE.md written as context for an AI coding agent: it describes the code structure, which layout parts are hardcoded, and the render-and-check loop. Opening the repository in Claude Code and asking it to adapt the diagram to your network is the author's suggested workflow.

Constraints

• The layout is bespoke and hardcoded, so adapting it is code work, not configuration.
• PNG output needs librsvg and the specific Fira fonts; fontconfig must find them.
• The code and bundled glyphs are MIT-licensed (LICENSE), service icons come from a separate project and belong to their projects, and the fonts are under the SIL Open Font License (Fira).
• The README states the code was written by AI in Claude Code, with about 60 rounds of review and iteration described.

HotRepo's take

homelab-diagram first appears on HotRepo's new-project list for 2026-11-08 with 100 stars and 4 forks, all recorded in one growth window from 2026-11-07 to 2026-11-08. There is no GitHub all-language daily rank and only a single snapshot, so the data can confirm early attention but says nothing about a trend. What is more useful for a reader is the author's honesty: a niche, hand-tuned script that produced a diagram people liked enough to ask about, with the coordinate work left visible rather than hidden behind an abstraction. As a starting point for someone willing to edit build.py, that is a reasonable proposition; as an install-and-go diagramming tool, it is not one.