supermachine-kernel 0.2.0

Pre-built Linux kernel image and in-VM init shim for supermachine, bundled as xz-compressed payloads inside the crate (no network required at build time). Versioned in lockstep with the supermachine library; pin both to the same version with `=`.
Documentation

supermachine-kernel

Pre-built Linux kernel image and in-VM init-oci shim for the supermachine microVM runtime.

This is a data crate. No public functions worth calling on their own; depend on it alongside supermachine so the runtime finds its kernel + init shim.

Quick start

[dependencies]
supermachine        = "=0.2"
supermachine-kernel = "=0.2"

Pin both to the same version with = — the snapshot format is keyed to the kernel build, and a partial cargo update would invalidate previously baked snapshots.

// Stage the bundled assets into a writable scratch dir, then
// point supermachine at them.
let scratch = std::env::temp_dir().join("supermachine-assets");
std::fs::create_dir_all(&scratch)?;
supermachine_kernel::extract_kernel_to(&scratch.join("kernel"))?;
supermachine_kernel::extract_init_oci_to(&scratch.join("init-oci"))?;

let assets = supermachine::AssetPaths::from_dir(&scratch);
let vm = supermachine::Vm::start(
    &supermachine::Image::from_snapshot("path/to/snapshot")?,
    &supermachine::VmConfig::new().with_assets(assets),
)?;

For .app-bundle distribution, do the extraction in a build.rs so the bundle is self-contained — no first-run download.

What this ships

Asset Size Purpose
KERNEL_BYTES ~29 MiB aarch64 Linux Image with the AF_TSI patch series. Loaded into guest RAM at VM start.
INIT_OCI_BYTES ~1.6 MiB Statically-linked aarch64-musl PID 1. Mounts overlayfs, /proc, /dev; exec's the OCI image entrypoint. Only needed for fresh bakes; snapshot restore doesn't use it.

The bytes ship inside the published .crate as xz-compressed payloads (kernel.xz ≈ 7 MiB, init-oci.xz ≈ 330 KiB). cargo's outer gzip on the tarball adds essentially nothing on already-xz data, so the final .crate is ~7.3 MiB — comfortably under crates.io's 10 MiB cap. No network, no separate install step: cargo add supermachine-kernel and build.rs decompresses the payloads into OUT_DIR at first build.

build.rs resolves the assets in this order:

  1. SUPERMACHINE_KERNEL_PATH / SUPERMACHINE_INIT_OCI_PATH env vars — point at uncompressed files. Use this for a custom kernel build.
  2. The bundled kernel.xz / init-oci.xz next to Cargo.toml. Decompressed via xz -d (universally available on macOS 11+ and every mainstream Linux distro). This is the default path.

Decompression runs once at first cargo build (~50–100 ms); subsequent builds use cargo's incremental cache. If xz is missing on the build host: brew install xz, apt install xz-utils, or dnf install xz.

API

  • [KERNEL_BYTES] / [KERNEL_LEN]
  • [INIT_OCI_BYTES] / [INIT_OCI_LEN]
  • [extract_kernel_to] / [extract_kernel_to_with_parents]
  • [extract_init_oci_to] / [extract_init_oci_to_with_parents]

See the rustdoc for usage notes.

License

This crate is a combined work under three licenses (see the NOTICE file shipped in this crate for full attribution + the GPL §3(b) source-availability offer):

  • Apache-2.0 — our build glue (build.rs, src/lib.rs). See LICENSE-APACHE.
  • GPL-2.0-only — the bundled Linux kernel image (kernel.xz). See LICENSE-GPL-2.0. Source available on request per GPL-2.0 §3(b) — see NOTICE for the written offer (email domas@supercorp.ai with the crate version received).
  • MIT — musl libc statically linked into the bundled init-oci binary (init-oci.xz). See LICENSE-MIT.

SPDX expression: Apache-2.0 AND GPL-2.0-only AND MIT.

Redistributing this crate requires satisfying each license on its respective component. Most redistributors are fine: the kernel runs as guest data, not as linked host code.