Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

microVM: remove the runtime and custom sandbox block roles

Open
  • Is something wrong?
#556 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
30/100
Issue type
Refactor
Clarity
Mostly clear
Activity status
Active
Tech stack
markdown, python, rust, shell
Domain
documentation, infrastructure

Research direction

Start with MicrovmSandboxBlockRole in openvmm/openvmm_defs/src/microvm.rs and follow it into openvmm_entry/src/cli_args/microvm.rs and the snapshot code in openvmm_helpers/src/snapshot/microvm.rs. On the NVX side, read scripts/nvx_tools/sandbox.py (LAYER_ROLES) and the sandbox-blocks scenario. Done means only distro and scratch remain, the freed slots and status words are absent, and the unit tests in scripts/test_nvx_tools.py pass. The open image-model decision needs a maintainer answer before the converter code is touched.

Written by the indexing model from the issue text.

Description

Summary

The microVM defines four sandbox block roles: distro, runtime, custom, and scratch. Nothing produces or attaches a runtime or custom layer. Remove both roles, so sandbox storage has a read-only distro layer and writable scratch.

Why

  • No producer. build-distro-layer builds only the Ubuntu distro layer, and the converter that would split images into distro, runtime, and custom is still proposed ("Image conversion" in doc/design/remaining-production-work.md).
  • No consumer. CI, the sandbox lifecycle and managed-exec tests, the snapshot scenarios, and every documentation example attach only distro and scratch. nvx-rs and aci_edge_sandboxes attach no sandbox blocks; they use the blockless managed root.
  • No end-to-end coverage. Outside unit tests, only the sandbox-blocks scenario attaches the two roles, as zero-filled raw images; it checks discovery tokens and read-only flags without mounting anything. No test mounts more than one EROFS lower layer, or captures and restores a snapshot with more than one.
  • Unused ABI surface. The roles cost two virtio-mmio slots, two IRQs, and two shared-status words, plus the matching paths in the snapshot contract and the guest agent.

Where the roles live

OpenVMM (openvmm/ submodule; paths relative to it):

  • openvmm/openvmm_defs/src/microvm.rs: MicrovmSandboxBlockRole::{Runtime, Custom}, the slots at 0xd0004000 (IRQ 12) and 0xd0005000 (IRQ 9), shared-status offsets 0x10 and 0x14, validate_microvm_sandbox_blocks ("at most three read-only layers"), and tests.
  • openvmm/openvmm_entry/src/cli_args/microvm.rs: --microvm-sandbox-block role parsing and the four-block limit.
  • openvmm/openvmm_helpers/src/snapshot/microvm.rs and openvmm/openvmm_entry/src/vm_controller/microvm.rs: manifest role names and the "one to three layers and scratch" capture rule.
  • Guide/src/user_guide/openvmm/run.md and Guide/src/reference/openvmm/management/cli.md.

NVX:

  • guest/common/nvx-init-agent: the runtime and custom mounts, the three-layer limit, and the lowerdir stacking.
  • scripts/nvx_tools/sandbox.py: LAYER_ROLES and the role addresses.
  • scripts/nvx_tools/microvm_tests.py and scripts/nvx_tools/microvm_test_scripts/sandbox-blocks.sh: the sandbox-blocks scenario.
  • scripts/test_nvx_tools.py: test_launch_contract_orders_roles_and_builds_agent_command_line.
  • doc/usage.md, doc/run.md, and doc/design/ (machine-and-device-abi.md, sandbox-filesystem-and-agent-architecture.md, configuration-boundary.md, remaining-production-work.md).

Decisions

  • Address layout. Keep scratch (0xd0006000, IRQ 11, status word 0x30018) and the control console where they are, and leave the freed windows, IRQs 9 and 12, and status words 0x30010 and 0x30014 unused. Fixed placement means an omitted device never shifts another; compacting would move scratch and the control console and change every machine contract. The architecture guide in #529 documents this layout.
  • Existing snapshots. Restore maps manifest role names to the enum, so a snapshot that records runtime or custom would fail with the existing unsupported-role error. Confirm that no retained snapshot or template uses these roles.
  • Image model. doc/design/sandbox-filesystem-and-agent-architecture.md proposes splitting curated images into distro, runtime, and custom for cache reuse. Decide whether the converter flattens each image into one distro layer, or whether layering returns together with the converter.

Tasks

  • OpenVMM: remove the Runtime and Custom roles, slots, IRQs, and status words from the CLI, the machine contract, snapshot capture and restore, and the tests; update the Guide.
  • NVX: promote the OpenVMM pin.
  • Guest agent: accept only the distro layer and drop the lowerdir stacking.
  • nvx.py sandbox: accept only --layer distro,....
  • Tests: attach only distro and scratch in sandbox-blocks, check that the freed slots are absent, and update the unit tests.
  • Docs: update doc/usage.md, doc/run.md, and doc/design/. The architecture guide in doc/design-doc/ (#529) already describes only distro and scratch.
Dominant language
Python
Stars
380
Forks
24
Avg merge
12h 3m
Merged PRs (30d)
292

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from microsoft/nvx

All issues in microsoft/nvx

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.