feat: support PVM-backed deployment

.github/workflows/docs.yml

@@ -3,49 +3,178 @@ name: Deploy Docs
 on:
   push:
     branches: [main]
+    tags: ["v*"]
     paths:
       - ".github/workflows/docs.yml"
       - "docs/**"
       - "src/api/openapi.yml"
   workflow_dispatch:
+    inputs:
+      ref:
+        description: >-
+          Optional: tag/branch/sha to (re)build docs from (e.g. "v0.1.0" to
+          rebuild an already-released version). Leave empty to build the ref
+          this run was triggered from. Always trigger this from "main" (via
+          the branch selector) so the current workflow logic is used; only
+          the "ref" input controls which content gets built and published.
+        required: false
+        type: string
 
 concurrency:
-  group: pages
+  group: docs-${{ github.ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+
 jobs:
   build:
-    runs-on: ubuntu-22.04
-    permissions:
-      contents: read
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.ctx.outputs.version }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.ref || github.sha }}
 
-      - uses: taiki-e/install-action@mdbook
+      - name: Determine target version
+        id: ctx
+        run: |
+          set -euo pipefail
+
+          if [[ "${{ github.ref_type }}" == "tag" ]]; then
+            echo "version=${{ github.ref_name }}" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          manual_ref="${{ inputs.ref }}"
+          if [[ "${{ github.event_name }}" == "workflow_dispatch" && -n "$manual_ref" ]]; then
+            if [[ "$manual_ref" =~ ^v[0-9] ]]; then
+              echo "version=$manual_ref" >> "$GITHUB_OUTPUT"
+            else
+              echo "version=dev" >> "$GITHUB_OUTPUT"
+            fi
+            exit 0
+          fi
 
-      - name: Configure GitHub Pages
-        uses: actions/configure-pages@v5
+          echo "version=dev" >> "$GITHUB_OUTPUT"
+
+      - uses: taiki-e/install-action@mdbook
 
       - name: Build docs
         run: |
           ln -sf ../../src/api/openapi.yml docs/src/openapi.yml
           mdbook build docs
 
-      - name: Upload GitHub Pages artifact
-        uses: actions/upload-pages-artifact@v4
+      - name: Upload built docs
+        uses: actions/upload-artifact@v6
         with:
+          name: docs-book
           path: docs/book
+          retention-days: 7
 
-  deploy:
+  publish:
     needs: build
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-latest
     permissions:
-      pages: write
-      id-token: write
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
+      contents: write
+    env:
+      VERSION: ${{ needs.build.outputs.version }}
     steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
+      - uses: actions/checkout@v6
+
+      - name: Download built docs
+        uses: actions/download-artifact@v6
+        with:
+          name: docs-book
+          path: book-output
+
+      - name: Publish to gh-pages branch
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          book_output="$(cd book-output && pwd)"
+          redirect_page="$(cd docs/redirects && pwd)/index.html"
+
+          publish_dir="$(mktemp -d)"
+          cleanup() {
+            rm -rf "$publish_dir"
+          }
+          trap cleanup EXIT
+
+          cd "$publish_dir"
+          git init -q
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git remote add origin "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+
+          max_attempts=5
+          for attempt in $(seq 1 "$max_attempts"); do
+            if git ls-remote --exit-code --heads origin gh-pages >/dev/null 2>&1; then
+              git fetch --depth=1 origin gh-pages
+              git checkout -B gh-pages FETCH_HEAD
+            else
+              git checkout --orphan gh-pages
+              git rm -rf . >/dev/null 2>&1 || true
+            fi
+
+            cp "$redirect_page" ./index.html
+
+            if [[ "$VERSION" == "dev" ]]; then
+              rm -rf dev
+              mkdir -p dev
+              cp -a "$book_output"/. dev/
+            else
+              rm -rf "$VERSION"
+              mkdir -p "$VERSION"
+              cp -a "$book_output"/. "$VERSION"/
+
+              if [[ -f versions.json ]]; then
+                existing="$(cat versions.json)"
+              else
+                existing='{"versions":[]}'
+              fi
+              echo "$existing" | jq \
+                --arg v "$VERSION" \
+                --arg d "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+                '.versions = ([{version: $v, date: $d}] + (.versions | map(select(.version != $v))))' \
+                > versions.json.tmp
+              mv versions.json.tmp versions.json
+
+              # Only promote this build to /latest/ if it is the highest known
+              # version. This lets maintainers rebuild an older tag (e.g. via
+              # workflow_dispatch with a "ref" input) to pick up a docs-only
+              # fix without accidentally rolling /latest/ back to stale content.
+              newest_version="$(jq -r '.versions[].version' versions.json | sort -V | tail -n1)"
+              if [[ "$newest_version" == "$VERSION" ]]; then
+                rm -rf latest
+                mkdir -p latest
+                cp -a "$book_output"/. latest/
+              else
+                echo "Skipping /latest/ update: ${VERSION} is not the newest known version (${newest_version})."
+              fi
+            fi
+
+            git add -A
+            if git diff --cached --quiet; then
+              echo "No documentation changes to publish for ${VERSION}."
+              exit 0
+            fi
+
+            git commit -q -m "chore: publish ${VERSION} docs for ${GITHUB_SHA}"
+
+            if git push origin gh-pages; then
+              echo "Published ${VERSION} docs."
+              exit 0
+            fi
+
+            echo "Push rejected (attempt ${attempt}/${max_attempts}), retrying with latest gh-pages..."
+            git checkout -q --detach
+            git branch -D gh-pages
+            sleep $((attempt * 3))
+          done
+
+          echo "::error::Failed to push docs to gh-pages branch after ${max_attempts} attempts"
+          exit 1

.github/workflows/release.yml

@@ -83,39 +83,59 @@ jobs:
 
       - name: Stage artifacts
         run: |
-          mkdir -p dist/bundle/ublk
-          cp target/release/server dist/bundle/server
-          strip dist/bundle/server
-          cp target/release/uvm-ublk-daemon dist/bundle/ublk/uvm-ublk-daemon
-          strip dist/bundle/ublk/uvm-ublk-daemon
-          cp config/default.toml dist/bundle/default.toml
-
-          STAGE_HOME="$PWD/dist/tmp-aenv"
-          STAGE_DEPS="$STAGE_HOME/deps"
-          mkdir -p "$STAGE_HOME"
-          AENV_HOME_PATH="$STAGE_HOME" dist/bundle/server --setup-only || {
-            echo "ERROR: --setup-only failed; check network and dependency downloads"
-            exit 1
-          }
-
-          test -d "$STAGE_DEPS" || {
-            echo "ERROR: deps dir missing at $STAGE_DEPS after --setup-only"
-            exit 1
-          }
-          test -f "$STAGE_DEPS/overlaybd/etc/overlaybd/overlaybd.json" || {
-            echo "ERROR: missing staged overlaybd default config after --setup-only"
-            exit 1
-          }
-          cp -a "$STAGE_DEPS" dist/bundle/deps
-          mkdir -p dist/bundle/etc/overlaybd
-          cp "$STAGE_DEPS/overlaybd/etc/overlaybd/overlaybd.json" dist/bundle/etc/overlaybd/overlaybd.json
-          rm -rf "$STAGE_HOME"
-          tar -czf dist/aenv-server-linux-x86_64.tar.gz -C dist/bundle .
+          set -euo pipefail
+
+          for MODE in kvm pvm; do
+            BUNDLE="dist/bundle-$MODE"
+            mkdir -p "$BUNDLE/ublk"
+            cp target/release/server "$BUNDLE/server"
+            strip "$BUNDLE/server"
+            cp target/release/uvm-ublk-daemon "$BUNDLE/ublk/uvm-ublk-daemon"
+            strip "$BUNDLE/ublk/uvm-ublk-daemon"
+            cp config/default.toml "$BUNDLE/default.toml"
+
+            sed -i \
+              "s/^virtualization_mode = .*/virtualization_mode = \"$MODE\"/" \
+              "$BUNDLE/default.toml"
+            grep -qx "virtualization_mode = \"$MODE\"" "$BUNDLE/default.toml" || {
+              echo "ERROR: failed to configure virtualization_mode=$MODE"
+              exit 1
+            }
+
+            STAGE_HOME="$PWD/dist/tmp-aenv-$MODE"
+            STAGE_DEPS="$STAGE_HOME/deps"
+            mkdir -p "$STAGE_HOME"
+            AENV_VIRTUALIZATION_MODE="$MODE" \
+              AENV_HOME_PATH="$STAGE_HOME" \
+              "$BUNDLE/server" --setup-only || {
+                echo "ERROR: $MODE --setup-only failed; check network and dependency downloads"
+                exit 1
+              }
+
+            test -d "$STAGE_DEPS" || {
+              echo "ERROR: deps dir missing at $STAGE_DEPS after $MODE --setup-only"
+              exit 1
+            }
+            test -f "$STAGE_DEPS/overlaybd/etc/overlaybd/overlaybd.json" || {
+              echo "ERROR: missing staged overlaybd default config for $MODE"
+              exit 1
+            }
+            cp -a "$STAGE_DEPS" "$BUNDLE/deps"
+            mkdir -p "$BUNDLE/etc/overlaybd"
+            cp "$STAGE_DEPS/overlaybd/etc/overlaybd/overlaybd.json" "$BUNDLE/etc/overlaybd/overlaybd.json"
+            rm -rf "$STAGE_HOME"
+            if [[ "$MODE" == "kvm" ]]; then
+              ARCHIVE="dist/aenv-server-linux-x86_64.tar.gz"
+            else
+              ARCHIVE="dist/aenv-server-linux-x86_64-pvm.tar.gz"
+            fi
+            tar -czf "$ARCHIVE" -C "$BUNDLE" .
+          done
 
       - uses: actions/upload-artifact@v7
         with:
-          name: server-bundle
-          path: dist/aenv-server-linux-x86_64.tar.gz
+          name: server-bundles
+          path: dist/aenv-server-linux-x86_64*.tar.gz
 
   release:
     name: Create GitHub Release
@@ -154,6 +174,7 @@ jobs:
             dist/aenv-linux-aarch64
             dist/aenv-darwin-x86_64
             dist/aenv-darwin-aarch64
+            dist/aenv-server-linux-x86_64-pvm.tar.gz
             dist/aenv-server-linux-x86_64.tar.gz
 
       - uses: actions/upload-artifact@v7
@@ -162,9 +183,17 @@ jobs:
           path: dist/
 
   docker-publish:
-    name: Build and push Docker images
+    name: Build and push Docker image (${{ matrix.mode }})
     needs: release
     runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - mode: kvm
+            version_suffix: ""
+          - mode: pvm
+            version_suffix: "-pvm"
     permissions:
       contents: read
       packages: write
@@ -191,6 +220,8 @@ jobs:
           file: deploy/docker/Dockerfile.agentenv
           push: true
           cache-from: type=gha,scope=agentenv-runtime
+          build-args: |
+            AENV_VIRTUALIZATION_MODE=${{ matrix.mode }}
           tags: |
-            ghcr.io/${{ env.OWNER }}/aenv-server:${{ github.ref_name }}
-            ghcr.io/${{ env.OWNER }}/aenv-server:latest
+            ghcr.io/${{ env.OWNER }}/aenv-server:${{ github.ref_name }}${{ matrix.version_suffix }}
+            ghcr.io/${{ env.OWNER }}/aenv-server:latest${{ matrix.version_suffix }}

CLAUDE.md

@@ -2,7 +2,7 @@
 
 ## What is AgentENV
 
-AgentENV is a Rust workspace for running AI agents inside isolated, snapshot-capable Firecracker-based environments. It exposes an E2B-compatible HTTP API so agents can create, pause, resume, and reuse sandboxes. Requires a Linux host with `/dev/kvm` access.
+AgentENV is a Rust workspace for running AI agents inside isolated, snapshot-capable Firecracker-based environments. It exposes an E2B-compatible HTTP API so agents can create, pause, resume, and reuse sandboxes. Requires a Linux host with `/dev/kvm` access and a host virtualization setup matching `virtualization_mode` (`kvm` by default; `pvm` requires x86_64 and `kvm_pvm`).
 
 ## Build, Lint, Test Commands
 
@@ -28,7 +28,7 @@ make agentenv-server          # shorthand for cargo adev codegen server
 make custom-extension-client  # shorthand for cargo adev codegen custom-extension
 ```
 
-Dependency downloads, generated OverlayBD runtime configs, and OverlayBD packaging are provisioned automatically during server startup. Machine-wide KVM group access, ublk device permissions, OverlayBD system config, and network sysctls require a one-time root setup via `server --setup-host --runtime-user <user> --runtime-group <group>`; normal startup validates those prerequisites and fails with actionable errors when they are missing.
+Dependency downloads, generated OverlayBD runtime configs, and OverlayBD packaging are provisioned automatically during server startup. Machine-wide `/dev/kvm` group access, ublk device permissions, OverlayBD system config, and network sysctls require a one-time root setup via `server --setup-host --runtime-user <user> --runtime-group <group>`; normal startup validates those prerequisites and the selected KVM/PVM mode, and fails with actionable errors when they are missing. AgentENV does not load or install `kvm_pvm`.
 
 All registry access goes through `regctl`: userImage manifest fetch, config blob fetch, layer download, tools drive image download (`src/setup/deps.rs::extract_ext4_from_ghcr`, unpacked with `umoci`), and OCI referrers lookup when `[image_resolver].try_referrers_overlaybd_prefixes` is non-empty (referrers lookup failures fall back to the source image). Server setup provisions both automatically: `regctl` is downloaded from the `[regclient]` entry in `config/deps_manifest.toml` to `/usr/local/bin/regctl`, and `umoci` is installed as a `[packages.runtime]` system package. `src/image/oci_image.rs` fetches the manifest via `regctl manifest get` and classifies it — standard OCI tar images trigger a full `regctl image copy` + per-layer conversion into local `.commit` files, while overlaybd-native images skip blob download entirely and emit a remote-ref `image.json` that the overlaybd runtime's `registryfs_v2` backend reads directly from the registry. User-facing image references are normalized by `ImageResolver` from template API `userImage` fields and CLI image arguments. For private registries referenced by `userImage`, run `docker login <registry>` before starting the server; `write_generated_overlaybd_global_config` auto-detects `~/.docker/config.json` (or `$DOCKER_CONFIG/config.json`) and wires the overlaybd runtime's `credentialConfig.mode=file` so the runtime can authenticate too.
 
@@ -57,7 +57,7 @@ sudo -E cargo test -p agentenv --test orchestrator_integration orchestrator::
 sudo -E cargo test -p agentenv --test orchestrator_integration orchestrator::test_name
 ```
 
-Integration tests require root (network namespaces), `/dev/kvm`, and `AENV_CONFIG_PATH` pointing to a valid config.
+Integration tests require root (network namespaces), `/dev/kvm`, host modules matching `AENV_VIRTUALIZATION_MODE`, and `AENV_CONFIG_PATH` pointing to a valid config.
 
 ## Architecture
 
@@ -95,7 +95,7 @@ When changing code under `services/`, validate via `make -C services test` (or `
 
 ### Per-Node Subsystems
 
-Each node is an AgentENV server binary (`src/bin/server.rs`) running on a Linux host with `/dev/kvm`. It wires together:
+Each node is an AgentENV server binary (`src/bin/server.rs`) running on a Linux host with `/dev/kvm` and one configured KVM/PVM mode. It wires together:
 
 **API layer** (`src/api/`): Axum HTTP server with OpenAPI-generated endpoint traits (`src/api/generated/` from `src/api/openapi.yml`) plus a reverse proxy. Implementations live in `src/api/impls/` (sandbox CRUD, snapshot CRUD, template-facing CRUD, auth, generic cursor-based pagination). The proxy (`src/api/proxy.rs`) forwards HTTP/WebSocket to sandboxes using routing headers (`x-agentenv-sandbox-id`, `x-agentenv-target-port`).
 

README.md

@@ -28,6 +28,8 @@ AgentENV (AENV) is a platform for running agent environments at scale, powering
 - **Linux kernel 6.8+**; the install script additionally requires **Ubuntu 24.04** (see *Quick Start* below for installation options)
 - `/dev/kvm` access for Firecracker microVM execution
 
+If your server does not support standard KVM, see the [PVM deployment guide](https://kvcache-ai.github.io/AgentENV/deployment/pvm.html) before installing.
+
 ---
 
 ## ⚡ Quick Start (Single Node)
@@ -48,6 +50,8 @@ curl -fsSL https://raw.githubusercontent.com/kvcache-ai/AgentENV/main/scripts/in
 sudo systemctl start aenv
 ```
 
+If this installation fails because standard KVM is unavailable, follow the [PVM deployment guide](https://kvcache-ai.github.io/AgentENV/deployment/pvm.html) instead.
+
 *Option B — Docker*
 
 Set up the server:

config/default.toml

@@ -12,11 +12,15 @@
 # override. AENV_RUNTIME_PATH separately defaults to "/run/aenv".
 home_path = "/var/lib/aenv"
 
+# Node-wide mutually exclusive virtualization backend. Override with
+# AENV_VIRTUALIZATION_MODE.
+virtualization_mode = "kvm"
+
 [firecracker]
 # Boot arguments passed to the guest kernel. This value takes precedence over
 # the DEFAULT_BOOT_ARGS constant in src/sandbox/firecracker/config.rs.
 # Keep the DAMON reclaim parameters in sync between both locations.
-boot_args = "console=ttyS0 reboot=k panic=1 pci=off init=/init damon_reclaim.enabled=Y damon_reclaim.min_age=60000000 damon_reclaim.quota_ms=100 damon_reclaim.quota_sz=1073741824 damon_reclaim.quota_reset_interval_ms=1000 damon_reclaim.wmarks_high=900 damon_reclaim.wmarks_mid=700 damon_reclaim.wmarks_low=200 damon_reclaim.skip_anon=Y damon_reclaim.wmarks_interval=5000000"
+boot_args = "console=ttyS0 reboot=k panic=1 pci=off mitigations=off init=/init damon_reclaim.enabled=Y damon_reclaim.min_age=60000000 damon_reclaim.quota_ms=100 damon_reclaim.quota_sz=1073741824 damon_reclaim.quota_reset_interval_ms=1000 damon_reclaim.wmarks_high=900 damon_reclaim.wmarks_mid=700 damon_reclaim.wmarks_low=200 damon_reclaim.skip_anon=Y damon_reclaim.wmarks_interval=5000000"
 # Optional allowlist for cold-start extraBootArgs prefixes. If omitted or empty,
 # no request-provided extra boot args are appended.
 # allowed_extra_boot_args_prefixes = ["aenv-custom."]