Skip to content

nvx-rs: template and clone commands in nvx-rs sandbox #853

Closed as not planned
Closed as not planned

Description

Parent: #837 (#833). Needs: #852, and #818 and #820, in the NVX library wiring workstream (#816). Unblocks: #854.

Goal. NVX's CLI implements the template and clone operations through nvx::host, with stage 3's features from the start.

Today (dev d04d9fb): nvx-rs sandbox has run, provision, start, exec, stop and deprovision (nvx-rs/src/host/cli/sandbox/mod.rs:100-104, :188-189). nvx-rs run restores a raw snapshot on the terminal (nvx-rs/src/host/cli/run.rs:72-75). #818 adds GPT images, the RAM upper and protected paths to nvx-rs sandbox, and #820 gives each guest build an identity.

Implementation:

  1. Commands:

    • nvx-rs sandbox template create, refresh, list, inspect and remove;
    • starting and running a sandbox from a template, through sandbox start and sandbox run.

    They follow runtime adapter: template and clone operations #847's operation contracts: explicit selection; no capture, cold, rehash or format fallback; the template run as a clone's Start, one execution and teardown. remove retires the generation first, so that nothing new acquires it, reports busy while leases remain, and deletes it once they drain.

  2. Key: NVX's adapter supplies nvx-rs: give each guest build an identity from its build inputs, and package it #820's build ID as the guest's build identity.

  3. Features: shorter images and tmpfs clones without a scratch (nvx-rs: images shorter than a template's capacity, and tmpfs clones without a scratch #848), CPU targets (nvx-rs: per-clone CPU targets #849), per-clone network policies (nvx-rs: per-clone network policies on deny-all templates #850), and aggregate exports (nvx-rs: aggregate exports for clones #857). Unless Snapshot/restore workstream, stage 5: templates and clones in NVX's adapter, and acceptance #837's fallback applies, NVX never uses stage 1's interim rules.

  4. Protected roots: nvx-rs: GPT images, the RAM upper and protected paths in nvx-rs sandbox #818's protected paths extend to the template store and to capture and clone state, so that no share reaches them.

  5. Store: the CLI documents the store's location and eviction, which it chooses as an adapter.

  6. Outcomes: each failure class maps to a stable exit code and message.

Tests: CLI parsing and outcome mapping; remove with live leases. In VMs, on KVM, MSHV and WHP, with #852: template creation; clone start and run for each format and upper; shorter images; CPU and memory targets; per-clone network policies; aggregate exports; each failure status; reattach.

Guide (#591's numbering): 5.2.1 (the CLI as a control frontend for templates), 5.2.4 (a clone's lifecycle in NVX's adapter).

Done when: merged, with the commands documented.

Activity

  1. ppenna commented on Nov 13, 2026

    @ppenna
    Contributor

    Not planned as written: #837's rescope for #1076 replaced this design.

    The CLI keeps named snapshots in place of templates (#1114): snapshot capture, with --net for a NIC; snapshot restore, which provisions and starts a managed sandbox from a snapshot; and run --restore-snapshot. The template store and the old clone path are deleted (SL6.2a, #1513; SL6.2b, #1507).

    Closing with #837.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

No labels
No labels

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions