Nexus OS Docs

Appearance

Hello NPK ​

Build, prove, publish locally, and install a native NPK with the checked-in nexus and nip CLIs.

Status (2026-09-06). The CLI paths below point at the real artifacts (forge/nip/nip_bin, the precompiled forge/nexus-forge/nexus). The proof pipeline itself is in development — some sub-commands shown here are not yet wired in the checked-in binaries. See Foundry status for the current CLI truth.

This proof is the first local Forge package pipeline: nexus orchestrates the proof, nip builds and installs the deterministic package, and BKDL evidence is the package artifact sidecar.

Run the proof ​

bash
cd forge/nip
./build.sh
cd ../../..
NEXUS_ROOT="$PWD"

export HOME=/tmp/nexus-npk-proof-home
export XDG_DATA_HOME=/tmp/nexus-npk-proof-home/.local/share
export XDG_CONFIG_HOME=/tmp/nexus-npk-proof-home/.config
export XDG_CACHE_HOME=/tmp/nexus-npk-proof-home/.cache
export NEXUS_HOME=/tmp/nexus-npk-proof-home/.nexus
rm -rf "$HOME"
mkdir -p "$HOME/work"
cd "$HOME/work"

"$NEXUS_ROOT/forge/nip/nip_bin" init hello-npk
"$NEXUS_ROOT/forge/nexus-forge/nexus" forge npk-proof hello-npk
"$NEXUS_ROOT/forge/nexus-forge/nexus" bazaar validate --local
"$NEXUS_ROOT/forge/nexus-forge/nexus" bazaar verify-cids --local
"$NEXUS_ROOT/forge/nexus-forge/nexus" forge export-bundle hello-npk
"$NEXUS_ROOT/forge/nexus-forge/nexus" forge validate-bundle "$NEXUS_HOME"/bundles/npk/hello-npk/*/*.npk-bundle.tar.gz
"$NEXUS_ROOT/forge/nexus-forge/nexus" forge import-bundle "$NEXUS_HOME"/bundles/npk/hello-npk/*/*.npk-bundle.tar.gz
"$NEXUS_ROOT/forge/nexus-forge/nexus" bazaar install --local hello-npk
"$XDG_DATA_HOME/nip/Links/Executables/hello-npk"

Expected final output:

text
hello from hello-npk

What the commands do ​

  • nip init hello-npk creates package.kdl and src/main.sh.
  • nexus forge npk-proof hello-npk calls nip build, emits hello-npk.npk.bkdl.json, signs that BKDL evidence with a local Ed25519 key, embeds the public key PEM in the .sig sidecar, verifies the artifact, publishes the proof into $NEXUS_HOME/artifacts/npk, and writes a local Bazaar registry entry whose artifacts block points at the stored NPK, BKDL evidence, and signature sidecar.
  • nexus bazaar validate --local checks the local trust badge metadata.
  • nexus bazaar verify-cids --local recomputes the artifact-backed Variant-CID from the BKDL evidence inputs.
  • nexus forge export-bundle hello-npk writes a portable .npk-bundle.tar.gz with the stored NPK, BKDL evidence, signature sidecar, and bundle manifest.
  • nexus forge validate-bundle <bundle> verifies the bundle checksum, manifest digests, BKDL evidence, signature sidecar, and bundled NPK.
  • nexus forge validate-bundle-manifest <manifest> checks an extracted bundle manifest against the checked-in Forge bundle schema.
  • nexus forge import-bundle <bundle> checks bundle provenance, publisher identity, local trust roots, and revocation policy before copying the bundle into the local Forge store and publishing a local Bazaar entry for this machine.
  • nexus bazaar install --local hello-npk validates local trust, verifies the stored artifact, delegates installation to nip, and registers the package in the local JSON database.

Runtime proof image ​

After the local package proof exists, project the package evidence into a bootable Micro runtime proof image:

bash
"$NEXUS_ROOT/forge/nexus-forge/nexus" build --edition=micro --arch=x86_64 --local-proof
"$NEXUS_ROOT/forge/nexus-forge/nexus" runtime install-proof \
  --local hello-npk \
  --image "$NEXUS_HOME/artifacts/nexus-micro-x86_64.img" \
  --output "$HOME/work/nexus-micro-runtime-hello.img"
"$NEXUS_ROOT/forge/nexus-forge/nexus" verify "$HOME/work/nexus-micro-runtime-hello.img"

The output image has a nexus-runtime-package-proof/v1 manifest, BKDL evidence, and Ed25519 signature. Its runtime manifest records the package Variant-CID, NRP path, read-only NexFS /sysro projection, capability policy, and embedded runtime ledger sector. The QEMU regression verifies the ledger sector digest, boots the image, and checks that the serial output exposes the runtime ledger read from the image:

bash
forge/nexus-forge/tests/test-runtime-package-proof.sh *(planned — not yet in tree)*

This proves a development bridge from host package identity into boot-visible runtime evidence. The production nxs generation composer remains separate future work.