NVKR from your first artifact to the NVKE demo

Preview: NVKR is available as a preview. Commands, input schemas and behavior can change between releases, and we do not recommend NVKR for production use. See Preview status and known limitations.

NVKR takes a description of what you want to ship and turns it into a build you can inspect and run. It connects the resulting files, images, and charts to their exact inputs and evidence. NVKE consumes those artifacts to install and run the product.

Start with one small executable on your laptop. See how its inputs become an artifact, change its version, then use the same workflow for NVKE. Start with how NVKR works, then run each command as you go.

How NVKR works

The public lifecycle is Definition → Run → Release:

Define what to produce. Declare named outputs and select the catalog components that produce them.
Review and run the work. NVKR resolves the pinned inputs into a Plan. A Run executes that work and records the artifacts, evidence, and failures for each required output.
Publish and consume. A Release connects selected artifacts and evidence through one pinned reference. Consumers verify its supported claims against their own policy.

You supply three inputs:

Input	Question it answers	In the first example
Catalog and pins	How is each component produced, and from which exact inputs?	Build a greeting script from a pinned Git commit in a pinned Alpine container.
Definition	What must this Run produce?	One executable output named `hello`.
Environment	Where and how will the work run?	Use local Docker.

A component supplies a recipe, an output names a required deliverable, and an artifact is the actual file or image produced. The Plan is generated from your inputs; you do not write it yourself. The first example ends with a local artifact. CI, signing, and Releases come later.

Build the CLI

Use an existing NVKR checkout, or clone one:

git clone https://github.com/dsx-ai-factory/nvkr.git
cd nvkr

You need Git 2.38 or later, Make, and the exact Go version recorded in .go-version. Run the remaining commands from the repository root in the same terminal.

cat .go-version
GOTOOLCHAIN=local make build
bin/nvkr --version

Building may download Go modules. If Make reports a version mismatch, put the Go version shown by cat .go-version on your PATH; see Development for setup.

Build and use your first artifact

Start Docker and make sure python3 is on your PATH. No NVKE source checkout or registry credentials are needed. The first run may pull its pinned Alpine image; later runs can use Docker’s cache. If Docker is not available, skip to preview the NVKE outputs.

Keep both versions of the example beneath one fresh workspace:

mkdir -p .nvkr
NVKR_QUICKSTART_DIR=$(mktemp -d "$PWD/.nvkr/quickstart.XXXXXX")
bash demos/demo-local.sh --out "$NVKR_QUICKSTART_DIR/hello-v1"

The script creates a tiny local Git repository, locks its source version, and prints the nvkr commands it runs. Add --pause for a guided stop before each stage. Expect:

1 / 4  Pin the source
2 / 4  Choose the output and see the plan
3 / 4  Run it
4 / 4  Check the result and use it
  Run: complete | output: hello | lane: unqualified-local-execution
  Artifact bytes match the recorded SBOM subject.
Hello, team! This is hello v1.0.0, built by NVKR.

That greeting comes from the artifact Docker built. Its target is linux/amd64, so Docker on Apple Silicon needs Linux AMD64 emulation. The result is a portable shell script that also runs on your host.

Connect the inputs to the result

The example Definition selects one output:

outputs:
  - name: hello
    components: [hello]
    platform: linux/amd64
    format: executable

The catalog supplies the build command: substitute the pinned version into the greeting script and make it executable. NVKR derives the remaining work. Inspect the saved Plan and run the artifact again:

bin/nvkr run plan --plan "$NVKR_QUICKSTART_DIR/hello-v1/plan.json"
"$NVKR_QUICKSTART_DIR/hello-v1/.nvkr/runs/demo/hello/out/hello/hello" world

Look for one required output in the Plan and Hello, world! in the greeting. Under hello-v1, keep these records together:

File	What it tells you
`catalog/pins.lock.yaml`	The exact source commit selected for the build.
`plan.json`	The intended inputs, operations, and Build Digest.
`.nvkr/runs/demo/lifecycle.json`	What the Run actually observed and whether it completed.
`logs/run.log`	The full execution log, including failures.

The demo checks that the artifact’s bytes match its recorded SBOM subject. This is unqualified local execution: nothing is signed or published, and the composition SBOM is not a dependency scan. The example guide maps the remaining files.

Change one input and compare

Build the second source version into another fresh directory:

bash demos/demo-local.sh --version 1.1.0 --out "$NVKR_QUICKSTART_DIR/hello-v2"
bin/nvkr run diff \
  --before "$NVKR_QUICKSTART_DIR/hello-v1/plan.json" \
  --after "$NVKR_QUICKSTART_DIR/hello-v2/plan.json"

The greeting now starts with Welcome and reports v1.1.0. The source pin and Build Digest change. A Build Digest identifies the logical build inputs; the artifact digest identifies the bytes that execution produced. Each invocation requires a new output directory, so use fresh names when repeating these commands.

Preview the NVKE outputs

The same model scales from one greeting script to the NVKE CLI, a container image, and a Helm chart. This small NVKE Definition requests nvkectl, cwe, and nvke-helm; the chart uses the image’s digest. These preview commands need only the CLI you built above, with no Docker, registry, or NVKE source checkout:

bin/nvkr definition validate --definition docs/examples/nvke-tutorial/definition.yaml
bin/nvkr run plan \
  --definition docs/examples/nvke-tutorial/definition.yaml \
  --environment docs/examples/nvke-tutorial/environment-local.yaml
bin/nvkr run local \
  --definition docs/examples/nvke-tutorial/definition.yaml \
  --environment docs/examples/nvke-tutorial/environment-local.yaml \
  --attempt quickstart-preview --dry-run

Expect three required outputs in the Plan. The dry-run reports pending, static-unqualified, and zero observed outputs: it creates no artifacts or attempt workspace. NVKR has described the work; each named output still needs its own successful result.

The three-output walkthrough can build those artifacts and pull the CLI back from a local registry. Continue below to run the larger NVKE demo with a real workload cluster.

Extend the workflow into the NVKE demo

The NVKE demo adds a downstream step: NVKR builds the artifacts → NVKE consumes them → you use the running cluster. The native CLI runs on Ubuntu ARM64 with KVM or Apple Silicon macOS with HVF. NICoSim runs on that host and starts three real QEMU guests from the selected QCOW2: one Kubernetes site, one tenant control plane, and one tenant worker. Kind is temporary bootstrap infrastructure; the NVKE management stack runs in the site guest.

Follow the native demo setup guide for your platform’s prerequisites, source access, and full guest and build capacity requirements. Mac commands run directly in macOS. Both platforms use Docker for artifact builds and a private Lima containerd backend for temporary Kind bootstrap. Allow substantially more time, storage, and downloads than the greeting demo.

After installing those prerequisites, build both CLIs from this checkout with the Go version in .go-version on PATH:

GOTOOLCHAIN=local make build demo
bin/nvke-demo e2e --help

From the repository root, start a fresh build and deployment with NVIDIA OVN, then clean up:

bin/nvke-demo e2e --repo "$PWD" \
  --attempt quickstart-native-01 \
  --out "$PWD/.nvkr/quickstart-native-01-demo" \
  --jobs 2 --network ovn --walkthrough --cleanup

Source authorization must work on the execution host. If supplying local NVKE source objects, add --nvke-clone /absolute/path/to/nvke as described in the setup guide; the pinned commits must exist in that Git repository. For a rerun, choose unused values for both --attempt and --out. NVIDIA OVN is the default. The guide also describes the explicit matched upstream OVN alternative; the CLI does not silently switch suppliers.

The command stays in the foreground while it builds, bootstraps the site, creates the tenant, and checks two Ready tenant nodes plus workload/DNS. --walkthrough adds bounded site and tenant API, node, and all-namespace pod observations. Add --conformance to test the same fresh tenant and retain its original reports before cleanup. With --cleanup, natural tenant deletion and joined owned cleanup must finish before success; require the command’s exit zero.

For interactive inspection, omit --cleanup and leave the foreground terminal running. Use a second terminal with that invocation’s private tool and kubeconfig paths, as described in cluster access. Ctrl-C requests cleanup. New native invocations do not detach a session; the guide’s session controls apply only to existing legacy Kind-site sessions.

Cleanup retains Run records and logs. This remains a local diagnostic and does not produce a signed Release. See the setup guide’s current evidence and limitations before treating a run as accepted.

Take the same inputs to CI and Releases

Once the local flow is familiar, follow pipeline generation to generate and check GitHub Actions in a scratch directory. Keep output selection in the Definition and execution, publication, and signing settings in the Environment. Edit those inputs and regenerate the workflow.

For a published Release, follow browse and verify a Release. Browsing finds outputs and evidence; verification checks the supported claim against your accepted signer and policy. Use the concept reference when you need more detail on any step.