Problems
I run dozens of Incus containers across multiple development and homelab projects. Over time, I lost track of:
- Which?: Which container belonged to which project
- What?: What each one was for
- How?: How they were configured
- Where?: Where documentation lived
Documentation was scattered — some in notes, some in READMEs, some nowhere. I’d forget why a container existed, or accidentally break one used by another project. This chaos led to duplicated work, confusion, and wasted time.
Objective
To create a lightweight, Git-integrated system that brings clarity to Incus-based development labs by:
- Structuring projects with self-documenting nodes
- Automating setup and teardown
- Making dependencies explicit
- Ensuring every container carries its purpose
No enforcement — just gentle structure.
Design Decision
- Git as source of truth: Each lab is a repo with docs, manifests, and history.
- Convention over control: No strict rules, but helpful scaffolding.
- Bidirectional dependency tracking: Labs declare what they need; infrastructure knows who uses it.
- Dry-run safe: All destructive commands support
--dry-run. - Extensible hooks: Designed for future plugins and automation.
Features
node add/rm
Add/remove Incus container
requires add/rm
Add/remove required external Incus container
up/down
Up/down entire or selective nodes
dry-run
Dry run capability side effect ops
Automatic Docs
Entire labs within a Git repo, with manifest.yaml and README.md for each node
ssh config
Auto update host .ssh config when node started/stopped
ssh host keys
Auto generate ssh host keys on first boot
Future Plans
- labkit status – Show running state, IPs, dependencies
- labkit doctor – Diagnose missing templates, config issues
- Web dashboard – Visual overview of all labs
- Integration with reverse proxy (auto-Caddyfile generation)
- Support for VMs alongside containers
- Template versioning and inheritance
- CI/CD mode: ephemeral labs for testing
labkit isn’t about replacing tools — it’s about making them easier to use together.
Getting Started
In your labs collection directory:
I'm currently setting-up a lab for tutorials. When it completes, I would add here as additional reference. [Coming soon!]
Project Status
LabKit is currently being used in my homelabs, in several servers; Yes, home-scale :)
Get Involved
LabKit is open-source and welcomes contributions!