RackPeek: YAML-backed home lab documentation with a CLI and a web UI

What RackPeek is for, and who it is not for

The problem RackPeek addresses is the gap between a spreadsheet and a full CMDB. A home lab accumulates a switch, a couple of hypervisors, some containers, a NAS, a VLAN plan and a handful of services, and none of that lives anywhere authoritative. NetBox solves this at the data-centre scale, with a database, a REST API and a permission model. RackPeek goes the other way. The README describes it as a "webui & CLI tool for documenting and managing home lab and small-scale IT infrastructure" that tracks "hardware, services, networks, and their relationships" without "enterprise bloat or proprietary lock-in". The project states its scope is intentionally narrow, and lists "Opinionated" among its core values, with the explicit note that it is "optimized for home labs and self-hosted environments, not enterprise CMDBs or corporate documentation workflows". That is a real boundary, not marketing. If your inventory is maintained by several people, or if a change process has to leave an audit trail, this is the wrong shape of tool. If one person owns the rack and wants the inventory in version control, it fits.

How the state is stored and what the two interfaces share

The README is explicit that "RackPeek stores its state in YAML", and the Docker section shows the layout as a config directory containing a single config.yaml. Both the CLI and the web UI read that file. The repository layout backs this up: RackPeek.Domain, RackPeek.Web, RackPeek.Web.Viewer and the CLI project RackPeek sit as separate top-level entries in the solution, with Shared.Rcl alongside them, which suggests the domain model is shared between the web and command-line front ends rather than duplicated. There is also a schemas/ directory at the top level, which is where you would look to confirm the exact shape of the file before you hand-write entries. The practical consequence is that the YAML file is the source of truth and the interfaces are views onto it. You can edit the file in your editor of choice, commit it to git, diff it after a hardware change, or generate it from a script. The trade-off is that there is no database enforcing referential integrity: if you rename a device in the YAML, nothing stops a service entry elsewhere in the file from still pointing at the old name.

Installing RackPeek with Docker and reaching the web UI

The README gives Docker as the primary path. The named-volume form creates a volume first, then runs the published image aptacode/rackpeek:latest with port 8080 mapped and the volume mounted at /app/config, which is where config.yaml lives.

docker volume create rackpeek-config
docker run -d \
  --name rackpeek \
  -p 8080:8080 \
  -v rackpeek-config:/app/config \
  aptacode/rackpeek:latest

After that the container should be listening on port 8080, and the web UI is reachable at http://localhost:8080. If you would rather keep the YAML somewhere you can open directly, the README gives a bind-mount variant that maps a local ./config directory to /app/config instead of using a named volume. That version is the one to choose if you intend to edit config.yaml by hand or commit it to a repository.

docker run -d \
  --name rackpeek \
  -p 8080:8080 \
  -v $(pwd)/config:/app/config \
  aptacode/rackpeek:latest

The README also publishes a compose file. Note the healthcheck, which curls http://localhost:8080/health, so that path is a real endpoint you can point your own monitoring at.

version: "3.9"

services:
  rackpeek:
    image: aptacode/rackpeek:latest
    container_name: rackpeek
    ports:
      - "8080:8080"
    volumes:
      - rackpeek-config:/app/config
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      start_period: 15s
      retries: 3

volumes:
  rackpeek-config:

For the command line there is a separate path. The justfile defines a build-cli recipe that publishes RackPeek/RackPeek.csproj as a self-contained single-file binary for a target runtime such as linux-x64. That recipe is a development command in the project's own justfile, so treat it as the documented way the maintainers produce the CLI binary rather than as an install instruction for end users. The README points to an Installation Guide and a CLI Commands Reference on the project site for the supported route, and those pages are where the exact subcommands live. The README does not reproduce the CLI syntax inline, so do not guess at flags from the Docker examples above.

Where RackPeek gets in the way

The single-file YAML store is the design decision everything else follows from, and it is also the main limitation. Concurrent edits are not reconciled: if two people open the web UI and the file at the same time, the last write wins, and the README describes no locking or merge behaviour. The project also states there is no telemetry, no ads and no tracking, which is good for privacy and means there is no usage data flowing back to tell the maintainers which parts are used. Discovery is the other thing to check before you commit. The repository description says RackPeek is a tool to "discover, manage, and document" infrastructure, but the README body is about documenting and managing; it does not describe a network scanning or SNMP discovery mechanism, so do not assume the tool will populate itself from your network. The route from an existing inventory is manual entry or a script that writes YAML. And the Ansible Inventory Generator Guide implies the flow runs outward, from RackPeek to Ansible, rather than inward. If you want a tool that polls your switches and keeps itself current, this is not it.

RackPeek against NetBox and against a plain spreadsheet

NetBox is the obvious comparison and the difference is architectural. NetBox is a Django application backed by PostgreSQL, with a REST API, a permission model and a plugin ecosystem, and it is designed for teams operating real data centres. RackPeek has no database, no API described in the README, and no user model; its state is a YAML file you can read in a text editor. The consequence is that NetBox will answer questions RackPeek cannot, such as who changed a rack assignment last Tuesday, and RackPeek will start in a minute where NetBox needs a deployment. Choosing RackPeek means accepting that the file is the interface. Against a spreadsheet, the difference is that RackPeek gives the same data a schema, a browser view and a CLI, and keeps it in a format that diffs cleanly in git. The Ansible Inventory Generator Guide is the part that turns documentation into something operational: it suggests RackPeek can emit inventory for Ansible, so the YAML you maintain for humans also drives configuration management.

Licence, maintenance and what an upgrade costs you

RackPeek is licensed AGPL-3.0. That is a copyleft licence with a network clause: if you modify the software and let users interact with it over a network, the AGPL requires you to offer them the corresponding source. Running the published Docker image unmodified for your own lab does not trigger that, and the README's core values section stresses that you own your data and can inspect, migrate or reuse it. The licence question to think about is what happens if you fork RackPeek and expose your fork to other people; that is a decision for you and, if it matters commercially, a lawyer. On maintenance, the last push to the default branch was on 2026-06-13, which is the same date as the RackPeek 2.0.0 release. The release history shows 1.3.1 in April 2026, 1.4.0 in May 2026 and 2.0.0 in June 2026, so the cadence over that window was roughly monthly. The README links a Versioning page, which is the place to check how breaking changes to the YAML schema are handled. That matters more here than in a database-backed tool: because your inventory is a hand-editable file, a schema change in a major version can require you to rewrite config.yaml, and the 2.0.0 jump is exactly the kind of release where you should read the versioning notes before pulling a new image. Pin the image tag rather than tracking latest if the file is precious.

Editorial conclusion

RackPeek fits home labs and small self-hosted setups where the inventory is small enough to keep in one YAML file and the operator is comfortable editing that file directly. It is the wrong tool if you need multi-user workflows, audit trails, or an API that other systems write into, since the README describes no telemetry and no such integration surface. Before adopting it, check the CLI Commands Reference and the Ansible Inventory Generator Guide linked from the README, and confirm that the config.yaml layout in your chosen version matches the schema you intend to commit to git.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. Timmoth/RackPeek on GitHub