Enable real guest networking and make demos network-first

README.md

@@ -22,11 +22,11 @@ The package includes a bundled Linux x86_64 runtime payload:
 
 No system Firecracker installation is required for basic usage.
 
-Current limitation:
-- The bundled runtime is currently shim-based.
-- `doctor` reports runtime capabilities, and current bundles report no real guest boot, no guest exec agent, and no guest networking.
-- Until a real guest-capable bundle is installed, `vm_exec` runs in `host_compat` mode rather than `guest_vsock`.
-- This means demo commands can exercise lifecycle/control-plane behavior, but they are not yet proof of command execution inside a real VM guest.
+Current status:
+- The bundled runtime is real, not shim-based.
+- `doctor` reports real guest capability flags for VM boot, guest exec, and guest networking.
+- `vm_exec` now runs in `guest_vsock` mode when the VM is started from the bundled runtime.
+- Networking still requires host privileges for TAP/NAT setup; see the networking section below.
 
 Host requirements still apply:
 - Linux host
@@ -68,12 +68,13 @@ Available real-runtime targets:
 - `make runtime-build-kernel-real`
 - `make runtime-build-rootfs-real`
 - `make runtime-materialize`
+- `make runtime-boot-check`
+- `make runtime-network-check`
 
-Current limitation:
-- the pipeline is real, but the checked-in source artifacts in `runtime_sources/` are still shim/placeholder inputs
+Notes:
 - the real-source path depends on `docker`, outbound access to GitHub and Debian snapshot mirrors, and enough disk for kernel/rootfs builds
-- replacing those inputs with real Firecracker binaries, a real kernel, and real rootfs images is what upgrades the packaged bundle from `host_compat` to true guest execution
-- the next artifact-replacement steps are documented in `runtime_sources/README.md`
+- `make runtime-boot-check` validates that the bundled runtime can boot a real microVM
+- `make runtime-network-check` validates outbound internet access from inside the guest by cloning `https://github.com/octocat/Hello-World.git`
 
 ## Run deterministic lifecycle demo
 
@@ -82,8 +83,14 @@ make demo
 ```
 
 The demo creates a VM, starts it, runs a command, and returns structured output.
-If the runtime reports `guest_vsock` plus networking, it uses an internet probe.
-Otherwise it falls back to a local compatibility command and the result will report `execution_mode=host_compat`.
+If the VM was started with networking enabled, it uses an internet probe.
+Otherwise it runs `git --version`.
+
+To run the deterministic demo with guest networking enabled:
+
+```bash
+make network-demo
+```
 
 ## Runtime doctor
 
@@ -100,12 +107,16 @@ This prints bundled runtime paths, profile availability, checksum validation sta
 - Host TAP/NAT setup is opt-in with:
 
 ```bash
-PYRO_VM_ENABLE_NETWORK=1 make doctor
+PYRO_VM_ENABLE_NETWORK=1 make demo
 ```
 
-- Current limitation:
-  - network metadata and host preflight exist
-  - real in-guest outbound networking still depends on a non-shim runtime bundle with real guest boot and guest exec support
+- Network setup requires host privilege to manage TAP/NAT state.
+- The current implementation auto-uses `sudo -n` for `ip`, `nft`, and `iptables` commands when available.
+- To validate real guest egress directly:
+
+```bash
+make runtime-network-check
+```
 
 ## Run Ollama lifecycle demo
 
@@ -117,6 +128,7 @@ make ollama-demo
 
 Defaults are configured in `Makefile`.
 The demo streams lifecycle progress logs and ends with a short text summary.
+`make ollama-demo` now enables guest networking by default.
 The command it asks the model to run is a small public repository clone:
 
 ```bash