nidus

Try a Kubernetes-adjacent OSS tool against a disposable, pre-seeded cluster — one command. No cluster to stand up, no fake data to invent so the tool's UI means something.

The problem

Evaluating something like Headlamp or k9s starts with twenty minutes that have nothing to do with the tool: create a cluster, then put something in it worth looking at. An empty cluster makes every inspector look identical, and it makes all of them look useless.

nidus run headlamp does the whole thing — throwaway cluster, realistic seeded resources, the tool built from source and launched against them. nidus stop and it is all gone, cluster included.

Install

curl -fsSL https://raw.githubusercontent.com/xonas1101/nidus/main/install.sh | sh

linux and darwin, amd64 and arm64. The binary goes to /usr/local/bin when that is writable and ~/.local/bin otherwise — it never asks for sudo.

nidus drives git, k3d, and kubectl rather than bundling them, so those need to be on your PATH. The installer says which are missing.

Use it

$ nidus list
headlamp  Headlamp  A web UI for Kubernetes that shows cluster state without a terminal
k9s       k9s       A terminal UI for navigating a Kubernetes cluster by keystroke

$ nidus run headlamp
==> cluster nidus-headlamp
==> seeding manifests/headlamp
==> building Headlamp in ~/.cache/nidus/build/headlamp
==> launching ./backend/headlamp-server
==> ready: http://localhost:4466

Ctrl-C stops the tool and removes the cluster. If the run is killed outright and cannot clean up after itself, nidus stop from any terminal finishes the job.

Command	What it does
`nidus run <project>`	Cluster, seed, build, launch — then tear it all down on the way out
`nidus status`	What is running right now, and whether the run that started it is still alive
`nidus stop`	Stop the tool and remove the cluster, including after a run that was killed
`nidus list`	The projects this build can run
`nidus validate <project\|path>`	Check a manifest without starting anything
`nidus init <name>`	Scaffold a starter manifest for a new project

The seed data is the point

A cluster with nothing in it tells you nothing about a tool built to inspect clusters. Every project ships a seed set designed for what that tool is actually used for — and the broken resources are as deliberate as the healthy ones:

a Deployment stuck in CrashLoopBackOff, with a multi-line traceback in its logs
an image that will never pull, so there is no container to have logs at all
a Pod that cannot be scheduled, sitting against a FailedScheduling event

nidus waits for those states before launching the tool. A crash-looping pod that has not started crash-looping yet leaves the tool showing a healthy cluster, which is the one thing seed data exists to avoid.

Add your own tool

A project is one trial.yaml plus the Kubernetes resources to seed alongside it. nidus init writes both, valid as emitted:

$ nidus init mytool --kind web
wrote manifests/mytool/trial.yaml
wrote manifests/mytool/seed/00-example.yaml

$ nidus validate mytool
ok  manifests/mytool/trial.yaml

The manifest describes the whole trial:

Section	What it says
`source`	Repo to clone and the tag or sha to pin it to
`requires`	Toolchain the build needs, checked before anything slow starts
`cluster`	Kubernetes version and how many worker nodes
`seed`	Resources to apply, and the states they must reach — broken ones included
`build`	Named steps run from the clone root
`launch`	How to start it: `kind: web` for a server nidus polls and opens, `kind: terminal` for a TUI it hands the terminal to

The two bundled manifests are worth reading first: headlamp (web) and k9s (terminal).

Badge for maintainers

If your project can be tried this way, say so in your README. This is what it looks like:

[![Try with nidus](https://img.shields.io/badge/try%20with-nidus-0f6b5c)](https://xonas1101.github.io/nidus/)

A badge is a claim that the thing works. Add it once there is a manifest for your project in manifests/ and nidus run <yours> comes up clean.