Build and run the solver

Task-oriented recipes for driving the solver. If you have never run Kuberina before, start with the tutorial instead — this page assumes you know what a blueprint is.

Compile the solver

make solver-build

For an optimised binary, the run targets already pass --release. If you want to build one directly:

cd solver && cargo build --release

Run against your own cluster

Point the solver at your own topology and workload files:

cd solver
cargo run --release -- plan \
  --infra /path/to/your_infra.yaml \
  --workloads /path/to/your_workloads.yaml

The blueprint is written to solver/kuberina_solution.yaml relative to the working directory.

Use the bundled solver/testdata/homelab_infra.yaml and solver/testdata/homelab_workloads.yaml as the schema reference for your own files.

Leave capacity headroom

Packing to nominal capacity leaves nothing for spikes, kernel overhead or the daemonsets you forgot about. Scale every node’s capacity down before solving:

cargo run --release -- plan \
  --infra testdata/irina_infra.yaml \
  --workloads testdata/irina_workloads.yaml \
  --pareto 80

The plan is still reported against true capacities — the cap applies only during solving.

Validate a blueprint independently

The Python inspector re-checks the solution against the inputs and renders a heatmap, without trusting the solver’s own reporting:

make research-inspect

To validate a solution other than the default paths, call the script directly:

uv run --with pyyaml python research/inspector.py \
  --infra solver/testdata/irina_infra.yaml \
  --workloads solver/testdata/irina_workloads.yaml \
  --solution solver/kuberina_solution.yaml \
  --output kuberina_dashboard.html

Open the resulting kuberina_dashboard.html in a browser.

Regenerate the benchmark data

The hyperscale dataset is generated, not committed as fixed input:

make research-generate-testdata

Run the full validation pipeline

Generate data, solve, inspect, and run the formal mathematical proof in one command:

make research-full-pipeline

This is the target to run when you have changed the solver and want to confirm you have not broken the result the paper reports.

Run the test suite

make solver-test

Lint before opening a pull request

make solver-lint

This runs cargo clippy -- -D warnings and cargo fmt --check together, so it fails on anything CI would reject. To fix formatting rather than just check it:

make solver-fmt

Make target reference — every target, with what it expands to.
CLI reference — the plan subcommand in detail.