Release/next

.github/workflows/version-tag.yml

@@ -86,6 +86,27 @@ jobs:
             echo "No proxy-domain changes detected."
           fi
 
+          # --- chutes-cvm domain ---
+          # src/chutes-cvm/*  →  src/chutes-cvm/VERSION
+          needs_cvm_bump=false
+          while IFS= read -r f; do
+            [ -z "$f" ] && continue
+            case "$f" in
+              src/chutes-cvm/*) needs_cvm_bump=true; break ;;
+            esac
+          done <<< "$changed_files"
+
+          if [ "$needs_cvm_bump" = true ]; then
+            if ! echo "$changed_files" | grep -qx "src/chutes-cvm/VERSION"; then
+              echo "::error::Changes under src/chutes-cvm/ require an src/chutes-cvm/VERSION bump."
+              errors=$((errors + 1))
+            else
+              echo "chutes-cvm domain: src/chutes-cvm/VERSION bumped."
+            fi
+          else
+            echo "No chutes-cvm-domain changes detected."
+          fi
+
           if [ "$errors" -gt 0 ]; then
             exit 1
           fi
@@ -178,3 +199,4 @@ jobs:
           tag_if_ready "src/sek8s/VERSION"             "sek8s-v"             "changelogs/sek8s"
           tag_if_ready "src/sek8s-common/VERSION"      "sek8s-common-v"      ""
           tag_if_ready "src/attestation-proxy/VERSION"  "attestation-proxy-v" "changelogs/attestation-proxy"
+          tag_if_ready "src/chutes-cvm/VERSION"         "chutes-cvm-v"        "changelogs/chutes-cvm"

AGENT.md

@@ -24,8 +24,8 @@ Do not introduce alternate frameworks (e.g., Prisma, NextAuth, Firebase). Stay w
 
 - **Never install a new dependency** without discussion first
 - **Never modify database schemas** without showing the migration plan (sek8s has no DB; this applies if one is added)
-- **Python services**: Poetry packages under `src/sek8s/` (import name `sek8s`), `src/sek8s-common/` (`sek8s_common`), and `src/attestation-proxy/` (`attestation_proxy`); tests under `tests/`
-- **Shell scripts** in `host-tools/scripts/` and `guest-tools/`
+- **Python services**: Poetry packages under `src/sek8s/` (import name `sek8s`), `src/sek8s-common/` (`sek8s_common`), `src/attestation-proxy/` (`attestation_proxy`), and `src/chutes-cvm/` (`chutes_cvm`, the host CLI/toolkit); tests under `tests/`
+- **Shell scripts** in `host-tools/scripts/`, `guest-tools/`, and the bundled `src/chutes-cvm/chutes_cvm/scripts/`
 - **Ansible roles** in `ansible/guest/roles/`
 - **OPA policies** in `ansible/guest/roles/admission-controller/files/policies/`
 - **Environment variables** go in config files (pydantic-settings, Ansible vars) — never hardcoded
@@ -35,7 +35,7 @@ Do not introduce alternate frameworks (e.g., Prisma, NextAuth, Firebase). Stay w
 - **Never commit or alter git history** without explicit human approval for that specific action — including `git commit`, `git commit --amend`, rebase, history-changing `reset`, `cherry-pick`, branch delete, or force-push. Leave changes for the author to review and commit unless they clearly asked you to perform a named git operation.
 - **Never modify Ansible roles** without understanding the guest image build pipeline
 - **Never hardcode attestation keys or measurements**
-- **Version bumps** — Three domains; see [docs/versioning.md](docs/versioning.md) for the full policy. **VM domain** (`ansible/guest/*`, `src/sek8s/*`, `src/sek8s-common/*`, `nvevidence/*`, root `pyproject.toml`/`poetry.lock`): bump `ansible/guest/VERSION`. Changes under **`ansible/host/`** do not bump the guest image version. **Proxy domain** (`src/attestation-proxy/*`): bump `src/attestation-proxy/VERSION`. **Ops domain** (`ansible/host/*`, `host-tools/*`, `.github/workflows/*`): bump `changelogs/ops/VERSION` using CalVer `YYYY.MM.PATCH` (e.g. `2026.05.0`; increment PATCH for a second release in the same month). Per-package `VERSION` files are the source of truth for `[tool.poetry] version` — keep them in sync via `scripts/sync_pyproject_versions.py`. Version bumps happen at release time, not during feature development.
+- **Version bumps** — Four domains; see [docs/versioning.md](docs/versioning.md) for the full policy. **VM domain** (`ansible/guest/*`, `src/sek8s/*`, `src/sek8s-common/*`, `nvevidence/*`, root `pyproject.toml`/`poetry.lock`): bump `ansible/guest/VERSION`. Changes under **`ansible/host/`** do not bump the guest image version. **Proxy domain** (`src/attestation-proxy/*`): bump `src/attestation-proxy/VERSION`. **chutes-cvm domain** (`src/chutes-cvm/*`, the independently installable host CLI): bump `src/chutes-cvm/VERSION` (SemVer); changelog fragments go in `changelogs/chutes-cvm/`. **Ops domain** (`ansible/host/*`, `host-tools/*`, `.github/workflows/*`): bump `changelogs/ops/VERSION` using CalVer `YYYY.MM.PATCH` (e.g. `2026.05.0`; increment PATCH for a second release in the same month). Per-package `VERSION` files are the source of truth for `[tool.poetry] version` — keep them in sync via `scripts/sync_pyproject_versions.py`. Version bumps happen at release time, not during feature development.
 - **Changelog fragments** — As you make changes, keep `changelogs/<component>/unreleased/<branch-name>.md` up to date using [Keep a Changelog](https://keepachangelog.com/) category headers (`### Added`, `### Changed`, `### Fixed`, `### Removed`). This is the only changelog file you should ever touch during development. **Never write `## [x.y.z]` version headings or edit `CHANGELOG.md` directly** — that is done by `make promote-changelogs` (or CI) at release time. PRs to `main` must have no unreleased fragments remaining.
 
 ## Patterns
@@ -50,6 +50,30 @@ Do not introduce alternate frameworks (e.g., Prisma, NextAuth, Firebase). Stay w
 - **One concern per module** — keep files focused; split when they grow large
 - **Follow existing naming** — check neighboring files and packages for conventions
 
+### chutes-cvm: bash vs Python
+
+**Python owns decisions and data; bash owns privileged, linear sequences of external-tool calls.**
+The language boundary must fall at a **data handoff**: Python resolves the values, then hands them
+to a bash step that performs the root-level system mutation. Never split a decision from its
+execution across the boundary (bash deciding *and* executing while Python builds args downstream is
+the anti-pattern).
+
+- **Put it in Python** when it makes decisions (precedence, validation, branching on parsed data),
+  models/validates structured data (config schema, manifest, GPU/topology profiles, measurements),
+  constructs commands from data (e.g. `guest/qemu.py` building the QEMU cmdline), is measurement- or
+  security-critical (must be unit-tested), or is the dispatch/UX surface (argparse, help, exit codes).
+- **Put it in bash** (bundled under `chutes_cvm/scripts/`) when it is a thin, mostly-linear sequence
+  of privileged system mutations via external tools (cryptsetup/qemu-nbd/mkfs/losetup, ip/iptables,
+  aria2c, lspci/nvidia-smi) where the logic *is* the tool invocations, branching is shallow, there is
+  no structured data to model, and a reviewer benefits from reading the literal root commands. These
+  need root + real devices, so they are untestable in unit tests regardless — porting them to Python
+  buys indirection, not testability.
+- **Smell tests**: a bash script carrying real precedence/parsing/validation logic → that logic
+  belongs in Python (the script shrinks to its system-mutation steps). A Python module that is only
+  `subprocess.run([...])` calls with no data modeling → fine to keep, but don't Pythonize a
+  cryptsetup sequence for purity. Standalone operator/diagnostic tools meant to be read and run
+  directly (e.g. `discover-profile.sh`) legitimately stay bash.
+
 ## Architecture Overview
 
 | Component | Purpose |
@@ -61,12 +85,13 @@ Do not introduce alternate frameworks (e.g., Prisma, NextAuth, Firebase). Stay w
 | **src/sek8s-common/sek8s_common/** | Shared config, server, auth, and constants for all sek8s packages |
 | **src/attestation-proxy/attestation_proxy/** | Dual-port attestation proxy (separate lean Docker image) |
 | **nvevidence/** | NVIDIA attestation SDK wrapper (separate Poetry package) |
-| **host-tools/** | Host setup (`chutes.host`), GPU binding/VM launch (`chutes.guest`), networking, orchestration (`quick-launch.sh`) |
+| **src/chutes-cvm/** | The `chutes-cvm` CLI + toolkit. `install.sh` is the **single source of truth for install** (fetch + venv + shims; repo-present=editable, standalone curl\|bash=non-editable). Under `chutes_cvm/` (import `chutes_cvm`, console script `chutes-cvm`): host setup (`host/`), GPU binding & VM launch (`guest/`), offline measurement generation (`measurement/`), and bundled data under `scripts/` — the privileged volume/network/teardown shell helpers the Python launch orchestrator (`guest/launch.py`) drives, config schema/template, and the nvidia-gpu-tools wheel (`scripts/gpu-tools/`). The GPU-tools **build recipe** is `tools/gpu-tools/` (`make bundle-gpu-tools`), outside the shipped package. |
+| **host-tools/** | Operator config examples (`scripts/config/`) and docs. The install script, VM-management scripts, and the GPU-tools wheel all moved into the `chutes-cvm` package; only the guest firmware (`firmware/`, MRTD-measured, image-bound) stays external to it. |
 | **guest-tools/** | TDX VM image builder, boot measurement extraction |
 | **ansible/guest/** | Ansible roles for guest image build (k3s, GPU drivers, attestation services, LUKS) |
 | **ansible/host/** | Operational Ansible (setup / launch / upgrade) for bare-metal TDX hosts over SSH |
 | **opa/** | OPA policy files for admission controller |
-| **guest-tools/** | Boot measurement extraction tools (`extract-acpi.sh`, `extract-vm-measurements.sh`) |
+| **guest-tools/** | Guest measurement & verification tooling (`measurement/`), image build output (`image/`), and R2 publish (`publish-image.sh`) |
 
 ## Environment Setup
 

Makefile

@@ -10,17 +10,28 @@ DC=docker compose -p ${PROJECT} -f ${COMPOSE_FILE} -f ${COMPOSE_BASE_FILE}
 POETRY ?= "poetry"
 
 SRC_DIR := src
-PACKAGES := $(shell ls $(SRC_DIR))
+# Python packages only: the Python tooling below derives src/<pkg>/<import>/ paths and
+# -p/--cov import names from this list, so non-Python packages under src/ (e.g. the
+# sr25519-signer Rust crate) must not appear in it.
+PACKAGES := $(patsubst $(SRC_DIR)/%/pyproject.toml,%,$(wildcard $(SRC_DIR)/*/pyproject.toml))
 VERSION := $(shell head ansible/guest/VERSION | grep -Eo "\d+.\d+.\d+")
 
 # Package filter: "make <target> sek8s" selects one package
 PKG_FILTER := $(filter $(PACKAGES),$(MAKECMDGOALS))
 SELECTED_PKGS := $(or $(PKG_FILTER),$(PACKAGES))
 
-# Wire package goal into PROJECT for docker targets (build/tag/push/sign)
+# Standalone docker images: docker/<name> with a Dockerfile and no matching src/ package.
+# Image filter: "make images busybox" selects one image; bare "make images" builds all.
+STANDALONE_IMAGES := $(shell for d in docker/*/; do n=$$(basename "$$d"); [ -f "$$d/Dockerfile" ] && [ ! -d "src/$$n" ] && echo $$n; done)
+IMG_FILTER := $(filter $(STANDALONE_IMAGES),$(MAKECMDGOALS))
+SELECTED_IMGS := $(or $(IMG_FILTER),$(STANDALONE_IMAGES))
+
+# Wire package/image goal into PROJECT for docker targets (build/tag/push/sign)
 ifeq ($(PROJECT),)
 ifneq ($(PKG_FILTER),)
 override PROJECT := $(firstword $(PKG_FILTER))
+else ifneq ($(IMG_FILTER),)
+override PROJECT := $(firstword $(IMG_FILTER))
 endif
 endif
 
@@ -45,6 +56,12 @@ $(PKG_FILTER):
 	@:
 endif
 
+# Allow standalone image names as make goals (no-op targets)
+ifneq ($(IMG_FILTER),)
+$(IMG_FILTER):
+	@:
+endif
+
 .DEFAULT_GOAL := help
 
 .EXPORT_ALL_VARIABLES:

README.md

@@ -14,16 +14,16 @@ Confidential GPU infrastructure for Chutes miners and zero-trust workloads. This
 | `**docs/**`             | Integration guide with [chutes-miner](https://github.com/chutesai/chutes-miner) and system-status service documentation |
 | `ansible/guest/`          | Ansible roles for guest image build automation                                                                          |
 | `sek8s/`, `nvevidence/` | Python services running inside the guest (attestation, evidence verification, system status)                            |
-| `guest-tools/`          | Boot measurement extraction tools (`extract-acpi.sh`, `extract-vm-measurements.sh`)                                     |
+| `guest-tools/`          | Guest measurement & verification tooling (`measurement/`), image build output (`image/`), R2 publish (`publish-image.sh`)  |
 
 
 ---
 
 ## Quick start roadmap
 
 1. **Set up the host** — Use `[host-tools/](host-tools/)` to prepare your TDX-capable machine with the required kernel, PCCS, and networking.
-2. **Download the VM image** — Run `./quick-launch.sh --download` from `host-tools/scripts/` to fetch the prebuilt guest image (requires `aria2`).
-3. **Configure and launch** — Run `./quick-launch.sh --template` to generate a `config.yaml`, fill in your miner credentials and network settings, then `./quick-launch.sh config.yaml` to create volumes, configure GPUs, and boot the VM in one command.
+2. **Download the VM image** — Run `chutes-cvm image download` to fetch + verify the prebuilt guest image set (requires `aria2`).
+3. **Configure and launch** — Run `chutes-cvm config init` to generate a `config.yaml`, fill in your miner credentials and network settings, then `chutes-cvm guest launch config.yaml` to create volumes, configure GPUs, and boot the VM in one command.
 4. **Understand the integration** — Read `[docs/end-to-end-miner.md](docs/end-to-end-miner.md)` to see how this repo integrates with the [chutes-miner](https://github.com/chutesai/chutes-miner) control plane.
 5. **Build the guest image** (optional) — Use `[guest-tools/](guest-tools/)` and `[ansible/guest/](ansible/guest/)` to customize or rebuild the encrypted VM image.
 6. **Monitor VM status** — See `[docs/system-status.md](docs/system-status.md)` for using the system-status API to inspect service health and GPU telemetry inside the VM.
@@ -46,7 +46,7 @@ The `config.yaml` defines your deployment: VM identity, miner credentials, netwo
 ## Key Documentation
 
 - `**[host-tools/README.md](host-tools/README.md)`** — Setting up the TDX host and launching VMs
-- `**[guest-tools/README.md](guest-tools/README.md)**` — Building and measuring the encrypted VM image
+- `**[docs/specs/tdx-measurement-verification.md](docs/specs/tdx-measurement-verification.md)**` — How the guest image's TDX measurements are structured, reproduced, and independently verified (on-host capture in `guest-tools/measurement/`; offline replay/generation in `chutes_cvm.measurement`)
 - `**[docs/end-to-end-miner.md](docs/end-to-end-miner.md)**` — Complete integration workflow with chutes-miner
 - `**[docs/system-status.md](docs/system-status.md)**` — System status API for monitoring service health and GPU telemetry
 

ansible/guest/README.md

@@ -66,7 +66,7 @@ The build process:
 3. Applies security hardening and admission policies
 4. Encrypts root filesystem with LUKS
 5. Configures initramfs for TDX-based boot unlock
-6. Outputs final encrypted image under `guest-tools/image/<build_env>/<vm_version>.qcow2` (see `playbooks/group_vars/host.yml` and inventory `build_env`; `vm_version` comes from `ansible/guest/VERSION`; append `-debug` when `debug_build` is true)
+6. Outputs the final encrypted image SET under `guest-tools/image/<build_env>/<vm_version>/` — the `<vm_version>.qcow2`, its direct-boot `.vmlinuz`/`.initrd`/`.cmdline` sidecars, and `manifest.json` (see `playbooks/group_vars/host.yml` and inventory `build_env`; `vm_version` comes from `ansible/guest/VERSION`; a debug build appends `-debug` to both the directory and the image name). The directory is a ready-to-use image set: copy it into `/var/lib/chutes/base-images/<variant>/` to boot it with `chutes-cvm guest launch`.
 
 At the **start** of `chutes-miner-vm.yml` (before the build VM is launched), the playbook prints the build configuration and **pauses for confirmation** (press Enter to continue, Ctrl+C to abort).
 
@@ -91,10 +91,10 @@ Host tools automatically configure iptables rules for k3s API (port 6443) and No
 
 ### Configuration Volumes
 
-Production VMs require three attached volumes (created by `quick-launch.sh`):
+Production VMs require three attached volumes (created by `chutes-cvm guest launch`):
 
 #### Config Volume (`tdx-config`)
-- **Created by**: `host-tools/scripts/volumes/create-config.sh`
+- **Created by**: `src/chutes-cvm/chutes_cvm/scripts/volumes/create-config.sh`
 - **Filesystem**: ext4 with label `tdx-config`
 - **Mount point**: `/var/config`
 - **Contents**:
@@ -106,14 +106,14 @@ Production VMs require three attached volumes (created by `quick-launch.sh`):
   - `docker-hub-token` - (optional) Docker Hub PAT for authenticated pulls and cosign
 
 #### Cache Volume (`tdx-cache`)
-- **Created by**: `host-tools/scripts/volumes/create-cache.sh`
+- **Created by**: `src/chutes-cvm/chutes_cvm/scripts/volumes/create-cache.sh`
 - **Filesystem**: XFS with label `tdx-cache`
 - **Mount point**: `/var/snap`
 - **Purpose**: Persistent storage for HF/model caches (e.g., `/var/snap/cache` for model weights)
 - **Size**: Configurable (default 5000G)
 
 #### Storage Volume (`storage`)
-- **Created by**: `host-tools/scripts/volumes/create-cache.sh` (with label `storage`)
+- **Created by**: `src/chutes-cvm/chutes_cvm/scripts/volumes/create-cache.sh` (with label `storage`)
 - **Filesystem**: XFS with label `storage`
 - **Mount point**: `/cache/storage` (contents bind-mounted into standard paths)
 - **Purpose**: Persistent k3s state, containerd data, kubelet pods, admission controller certs, and chutes agent state
@@ -168,11 +168,11 @@ See role-specific defaults for component configuration.
 
 This Ansible playbook builds the VM image only. The following are handled by host-tools:
 
-- ❌ TDX-enabled host system setup → See `host-tools/scripts/chutes/host/`
-- ❌ GPU passthrough configuration → Handled automatically by `run-td`
-- ❌ Network infrastructure → See `host-tools/scripts/network/setup-bridge.sh`
-- ❌ Config/cache/storage volume creation → See `host-tools/scripts/volumes/create-*.sh`
-- ❌ VM launch and orchestration → See `host-tools/scripts/quick-launch.sh`
+- ❌ TDX-enabled host system setup → See `src/chutes-cvm/chutes_cvm/host/`
+- ❌ GPU passthrough configuration → Handled automatically by `chutes-cvm guest launch`
+- ❌ Network infrastructure → See `src/chutes-cvm/chutes_cvm/scripts/network/setup-bridge.sh`
+- ❌ Config/cache/storage volume creation → See `src/chutes-cvm/chutes_cvm/scripts/volumes/create-*.sh`
+- ❌ VM launch and orchestration → Handled by `chutes-cvm guest launch`
 - ✅ Guest OS and k3s installation
 - ✅ GPU drivers and attestation services
 - ✅ Security hardening and admission control

ansible/guest/VERSION

@@ -1 +1 @@
-1.3.1
+1.4.0

ansible/guest/inventory-reproduce.yml

@@ -0,0 +1,35 @@
+---
+# inventory-reproduce.yml
+#
+# Reproduce the Chutes production guest image and its measurements as an independent third party.
+# Identical to inventory.yml except it needs NONE of our secrets:
+#   * luks_passphrase is a hardcoded, published constant (below) instead of the LUKS_PASSPHRASE env.
+#     It does NOT affect the measured registers — MRTD/RTMR0-3 cover the firmware, kernel, initrd,
+#     cmdline and the baked configs (incl. the root key), not the LUKS container — so any value
+#     yields the same measurements; first-boot rotation replaces it anyway.
+#   * The root RSA PUBLIC key is fetched from R2 (root_signing_key_url), same as our own builds.
+# Everything else is the standard prod build. Build, then compare your measurements to the published
+# ones at GET https://api.chutes.ai/servers/tee/measurements.
+all:
+  children:
+    vm:
+      hosts: # Dynamically populated by playbook
+    host:
+      hosts:
+        localhost:
+          ansible_connection: local
+
+  vars:
+    ansible_user: "{{ lookup('env', 'USER') }}"
+    # Root RSA PUBLIC key — fetched from R2 (public), baked into the image, measured into RTMR3.
+    root_signing_key_url: "https://vm.chutes.ai/root-signing-key.pem"
+    root_signing_key_path: "/tmp/chutes-root-signing-key.pem"
+    # Published constant — intentionally NOT a secret (does not affect measurements; see header).
+    luks_passphrase: "chutes"
+    tdx_base_url: "https://cvm.chutes.ai"
+    validator_base_url: "https://api.chutes.ai"
+    build_env: "prod"
+    prime_wait_timeout: 300
+
+    debug_build: false
+    guest_ssh_keys: []