Add aci_edge_sandboxes with an OpenVMM sandbox backend

.dockerignore

@@ -5,6 +5,7 @@
 build
 data
 dist
+aci_edge_sandboxes
 openvmm
 third_party
 **/__pycache__

.github/actions/check-aci-edge-sandboxes/action.yml

@@ -0,0 +1,108 @@
+name: Check aci_edge_sandboxes
+description: Format, lint, document, and test the aci_edge_sandboxes crate
+
+inputs:
+  toolchain:
+    description: >-
+      Rust toolchain used for formatting, linting, and tests. It matches the toolchain
+      pinned by MXC, the crate's primary consumer.
+    required: false
+    default: "1.93"
+
+runs:
+  using: composite
+  steps:
+    - name: Install Rust toolchains
+      id: toolchains
+      shell: bash
+      working-directory: aci_edge_sandboxes
+      run: |
+        set -euo pipefail
+        msrv=$(sed -n 's/^rust-version = "\(.*\)"$/\1/p' Cargo.toml)
+        test -n "${msrv}"
+        rustup toolchain install "${{ inputs.toolchain }}" --profile minimal \
+          --component clippy,rustfmt
+        rustup toolchain install "${msrv}" --profile minimal
+        echo "msrv=${msrv}" >> "${GITHUB_OUTPUT}"
+
+    - name: Check formatting
+      shell: bash
+      working-directory: aci_edge_sandboxes
+      run: cargo "+${{ inputs.toolchain }}" fmt --check
+
+    - name: Lint
+      shell: bash
+      working-directory: aci_edge_sandboxes
+      env:
+        # --all-features enables `bundled`; stage nothing instead of downloading a release.
+        ACI_EDGE_SANDBOXES_BUNDLE: skip
+      run: |
+        set -euo pipefail
+        cargo "+${{ inputs.toolchain }}" clippy --locked --all-targets --all-features \
+          -- -D warnings
+        cargo "+${{ inputs.toolchain }}" clippy --locked --lib --no-default-features \
+          -- -D warnings
+
+    - name: Test
+      shell: bash
+      working-directory: aci_edge_sandboxes
+      env:
+        # --all-features enables `bundled`; stage nothing instead of downloading a release.
+        ACI_EDGE_SANDBOXES_BUNDLE: skip
+      run: |
+        set -euo pipefail
+        cargo "+${{ inputs.toolchain }}" test --locked --all-features
+        cargo "+${{ inputs.toolchain }}" test --locked
+
+    - name: Check artifact bundling
+      shell: bash
+      working-directory: aci_edge_sandboxes
+      run: |
+        set -euo pipefail
+        bundle=$(mktemp -d)
+        executable=openvmm
+        bundle_dir="${bundle}"
+        if [[ "${RUNNER_OS}" == Windows ]]; then
+          executable=openvmm.exe
+          bundle_dir=$(cygpath -w "${bundle}")
+        fi
+        mkdir -p "${bundle}/bin" "${bundle}/guest"
+        printf openvmm > "${bundle}/bin/${executable}"
+        printf kernel > "${bundle}/guest/vmlinux"
+        printf initramfs > "${bundle}/guest/initramfs.cpio.gz"
+        cp ../SOURCE-MANIFEST.json "${bundle}/"
+        (cd "${bundle}" && sha256sum "bin/${executable}" guest/vmlinux \
+          guest/initramfs.cpio.gz SOURCE-MANIFEST.json > SHA256SUMS)
+        ACI_EDGE_SANDBOXES_BUNDLE_DIR="${bundle_dir}" cargo "+${{ inputs.toolchain }}" test --locked --lib \
+          --features bundled artifacts
+
+    - name: Build documentation
+      shell: bash
+      working-directory: aci_edge_sandboxes
+      env:
+        ACI_EDGE_SANDBOXES_BUNDLE: skip
+        RUSTDOCFLAGS: -D warnings
+      run: cargo "+${{ inputs.toolchain }}" doc --locked --no-deps --all-features
+
+    - name: Check the minimum supported Rust version
+      shell: bash
+      working-directory: aci_edge_sandboxes
+      env:
+        # --all-features enables `bundled`; stage nothing instead of downloading a release.
+        ACI_EDGE_SANDBOXES_BUNDLE: skip
+      run: >-
+        cargo "+${{ steps.toolchains.outputs.msrv }}" check
+        --locked --all-targets --all-features
+
+    - name: Check the macOS build
+      if: runner.os == 'Linux'
+      shell: bash
+      working-directory: aci_edge_sandboxes
+      env:
+        # --all-features enables `bundled`; stage nothing instead of downloading a release.
+        ACI_EDGE_SANDBOXES_BUNDLE: skip
+      run: |
+        set -euo pipefail
+        rustup target add --toolchain "${{ inputs.toolchain }}" aarch64-apple-darwin
+        cargo "+${{ inputs.toolchain }}" check --locked --all-targets --all-features \
+          --target aarch64-apple-darwin

.github/actions/validate-nvx/action.yml

@@ -17,6 +17,7 @@ runs:
         python3 scripts/nvx.py test-openvmm-unit --help
         python3 scripts/nvx.py test-openvmm --help
         python3 scripts/nvx.py test-microvm --help
+        python3 scripts/nvx.py test-aci-edge-sandboxes --help
         python3 scripts/nvx.py test-adversarial --help
         python3 scripts/nvx.py benchmark --help
 
@@ -41,6 +42,8 @@ runs:
         if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
         python scripts\nvx.py test-microvm --help
         if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+        python scripts\nvx.py test-aci-edge-sandboxes --help
+        if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
         python scripts\nvx.py test-adversarial --help
         if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
         python scripts\nvx.py benchmark --help

.github/copilot-instructions.md

@@ -21,6 +21,9 @@
   [validate-nvx](./actions/validate-nvx/action.yml) as the authoritative local
   quality and CLI test definitions. Start with the narrowest affected test, then
   run the applicable commands from those actions.
+- For changes under `aci_edge_sandboxes/`, run the commands in
+  [check-aci-edge-sandboxes](./actions/check-aci-edge-sandboxes/action.yml), which need no hypervisor.
+  `scripts/nvx.py test-aci-edge-sandboxes` exercises the crate on a real hypervisor.
 - OpenVMM source changes also require the package-scoped checks prescribed by the
   nested repository. Do not claim unavailable hardware or cross-platform gates
   passed; report the missing prerequisite and rely on CI when appropriate.

.github/workflows/ci.yml

@@ -41,6 +41,24 @@ jobs:
       - name: Check code quality
         uses: ./.github/actions/check-quality
 
+  aci-edge-sandboxes:
+    name: aci-edge-sandboxes / ${{ matrix.os }}
+    if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+
+      - name: Check aci_edge_sandboxes
+        uses: ./.github/actions/check-aci-edge-sandboxes
+
   openvmm-changes:
     name: Detect CI workload inputs
     if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
@@ -109,7 +127,7 @@ jobs:
             run_workloads "At least one non-documentation file changed between \`${BASE_SHA}\` and \`${HEAD_SHA}\`."
           fi
 
-          relevant_paths='^(openvmm($|/)|\.github/workflows/(ci|build-openvmm-binary|run-nvx-microvm-tests|run-platform)\.yml$|\.github/actions/(build-guest-artifacts|build-openvmm|checkout-openvmm|sccache|setup-curl|validate-nvx|validate-runner)/|scripts/nvx\.py$|scripts/nvx_tools/|scripts/setup/|kernel/|alpine/|guest/|ubuntu/|docker/Dockerfile$|SOURCE-MANIFEST\.json$)'
+          relevant_paths='^(openvmm($|/)|aci_edge_sandboxes/|\.github/workflows/(ci|build-openvmm-binary|run-nvx-microvm-tests|run-platform)\.yml$|\.github/actions/(build-guest-artifacts|build-openvmm|checkout-openvmm|sccache|setup-curl|validate-nvx|validate-runner)/|scripts/nvx\.py$|scripts/nvx_tools/|scripts/setup/|kernel/|alpine/|guest/|ubuntu/|docker/Dockerfile$|SOURCE-MANIFEST\.json$)'
           if grep -Eq "${relevant_paths}" "${changed_files}"; then
             run_tests "At least one OpenVMM test input changed between \`${BASE_SHA}\` and \`${HEAD_SHA}\`."
           else
@@ -916,6 +934,7 @@ jobs:
     name: Publish development release
     needs:
       - quality
+      - aci-edge-sandboxes
       - openvmm-vmm-tests
       - openvmm-unit-tests
       - nvx-microvm-tests-kvm
@@ -931,6 +950,7 @@ jobs:
         github.ref == 'refs/heads/dev' &&
         !cancelled() &&
         needs.quality.result == 'success' &&
+        needs.aci-edge-sandboxes.result == 'success' &&
         (
           needs.openvmm-vmm-tests.result == 'success' ||
           needs.openvmm-vmm-tests.result == 'skipped'
@@ -1002,6 +1022,7 @@ jobs:
     name: Required status check
     needs:
       - quality
+      - aci-edge-sandboxes
       - openvmm-changes
       - artifacts
       - build-openvmm-linux-gnu
@@ -1037,6 +1058,7 @@ jobs:
           RUN_TESTS: ${{ needs.openvmm-changes.outputs.run-tests }}
           RUN_WORKLOADS: ${{ needs.openvmm-changes.outputs.run-workloads }}
           QUALITY_RESULT: ${{ needs.quality.result }}
+          ACI_EDGE_SANDBOXES_RESULT: ${{ needs.aci-edge-sandboxes.result }}
           CHANGES_RESULT: ${{ needs.openvmm-changes.result }}
           ARTIFACTS_RESULT: ${{ needs.artifacts.result }}
           BUILD_LINUX_GNU_RESULT: ${{ needs.build-openvmm-linux-gnu.result }}

.github/workflows/run-nvx-microvm-tests.yml

@@ -515,6 +515,22 @@ jobs:
           Invoke-Nvx sandbox deprovision --state-dir $state
           Remove-Item -Recurse -Force $share, $scratch, $outside
 
+      - name: Run aci_edge_sandboxes lifecycle test on Linux
+        if: runner.os != 'Windows'
+        shell: bash
+        run: >-
+          python3 scripts/nvx.py test-aci-edge-sandboxes
+          --backend "${{ inputs.backend }}"
+          --output-dir "build/test-results/aci-edge-sandboxes-${{ inputs.backend }}"
+
+      - name: Run aci_edge_sandboxes lifecycle test on Windows
+        if: runner.os == 'Windows'
+        shell: powershell
+        run: >-
+          python scripts\nvx.py test-aci-edge-sandboxes
+          --backend "${{ inputs.backend }}"
+          --output-dir "build/test-results/aci-edge-sandboxes-${{ inputs.backend }}"
+
       - name: Upload NVX microVM failure logs
         if: failure()
         uses: actions/upload-artifact@v7
@@ -525,4 +541,5 @@ jobs:
             build/test-results/ubuntu-${{ inputs.backend }}
             build/test-results/ubuntu-kvm-extended
             build/test-results/azurelinux-${{ inputs.backend }}
+            build/test-results/aci-edge-sandboxes-${{ inputs.backend }}
           if-no-files-found: warn

.gitignore

@@ -7,6 +7,7 @@
 /.venv/
 /.ruff_cache/
 /.nvx-hosts.json
+/aci_edge_sandboxes/target/
 __pycache__/
 *.py[cod]
 *.log

README.md

@@ -65,6 +65,7 @@ python scripts\nvx.py run
 - [Run](doc/run.md) - Instructions for running NVX.
 - [Benchmark](doc/benchmarks.md) - Instructions for benchmarking NVX.
 - [Command-line reference](doc/usage.md) - Complete `scripts/nvx.py` command and option reference.
+- [Rust API](aci_edge_sandboxes/README.md) - The `aci_edge_sandboxes` crate for driving the sandbox lifecycle from Rust.
 
 ### Development