feat: add -p/--publish port forwarding to vz run

Wire port forwarding through the full stack: CLI flag, vz.json `ports`
field, proto CreateSandboxRequest, daemon handler, and into the existing
boot_shared_vm port forwarding infrastructure.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: lightsofapollo

crates/vz-cli/src/commands/dev.rs

@@ -50,6 +50,10 @@ pub struct DevRunArgs {
     #[arg(short, long)]
     pub env: Vec<String>,
 
+    /// Publish a container port to the host (HOST:CONTAINER[/PROTO]).
+    #[arg(short = 'p', long = "publish")]
+    pub publish: Vec<String>,
+
     /// Force fresh VM (stop existing, re-provision).
     #[arg(long)]
     pub fresh: bool,
@@ -94,6 +98,10 @@ struct VzConfig {
     #[serde(default)]
     env: BTreeMap<String, String>,
 
+    /// Port mappings (HOST:CONTAINER or HOST:CONTAINER/PROTO).
+    #[serde(default)]
+    ports: Vec<String>,
+
     /// Resource limits.
     #[serde(default)]
     resources: ResourceConfig,
@@ -140,6 +148,11 @@ pub async fn cmd_run(args: DevRunArgs) -> anyhow::Result<()> {
 
     let volume_mounts = build_volume_mounts(&config, &project_dir)?;
 
+    // Merge ports from vz.json and CLI -p flags.
+    let mut all_port_specs = config.ports.clone();
+    all_port_specs.extend(args.publish.iter().cloned());
+    let port_mappings = parse_port_mappings(&all_port_specs)?;
+
     // --fresh: delete persistent disk so the container starts with a clean filesystem.
     if args.fresh {
         let run_dir = home_dir()?.join(".vz").join("run").join(&sandbox_id);
@@ -226,6 +239,7 @@ pub async fn cmd_run(args: DevRunArgs) -> anyhow::Result<()> {
                 labels,
                 volume_mounts: proto_mounts,
                 disk_image_path: disk_image_path.to_string_lossy().to_string(),
+                port_mappings: port_mappings.clone(),
             })
             .await
             .context("failed to create sandbox via daemon")?;
@@ -250,6 +264,12 @@ pub async fn cmd_run(args: DevRunArgs) -> anyhow::Result<()> {
         }
 
         eprintln!("VM ready.");
+        for pm in &port_mappings {
+            eprintln!(
+                "  Port {} -> {} ({})",
+                pm.host_port, pm.container_port, pm.protocol
+            );
+        }
 
         // Run setup commands if needed.
         // When --fresh, force re-run by clearing any cached hashes.
@@ -956,6 +976,52 @@ fn is_terminal_state_error(error: &DaemonClientError) -> bool {
     )
 }
 
+fn parse_port_mappings(
+    specs: &[String],
+) -> anyhow::Result<Vec<runtime_v2::PortMapping>> {
+    specs.iter().map(|s| parse_port_mapping(s)).collect()
+}
+
+fn parse_port_mapping(spec: &str) -> anyhow::Result<runtime_v2::PortMapping> {
+    let (ports_part, protocol) = match spec.split_once('/') {
+        Some((ports, proto)) => (ports, proto.to_ascii_lowercase()),
+        None => (spec, "tcp".to_string()),
+    };
+
+    if protocol != "tcp" && protocol != "udp" {
+        bail!(
+            "invalid -p protocol '{protocol}' in '{spec}', expected tcp or udp"
+        );
+    }
+
+    let mut parts = ports_part.split(':');
+    let host_str = parts
+        .next()
+        .context("invalid -p value, expected HOST:CONTAINER[/PROTO]")?;
+    let container_str = parts
+        .next()
+        .with_context(|| format!("invalid -p value '{spec}', expected HOST:CONTAINER[/PROTO]"))?;
+
+    if parts.next().is_some() {
+        bail!(
+            "invalid -p value '{spec}', host IP is not supported yet; expected HOST:CONTAINER[/PROTO]"
+        );
+    }
+
+    let host_port = host_str
+        .parse::<u32>()
+        .with_context(|| format!("invalid host port '{host_str}' in -p '{spec}'"))?;
+    let container_port = container_str
+        .parse::<u32>()
+        .with_context(|| format!("invalid container port '{container_str}' in -p '{spec}'"))?;
+
+    Ok(runtime_v2::PortMapping {
+        host_port,
+        container_port,
+        protocol,
+    })
+}
+
 fn parse_memory(raw: Option<&str>) -> anyhow::Result<u64> {
     match raw {
         None => Ok(8192),

crates/vz-runtime-proto/proto/runtime_v2.proto

@@ -61,6 +61,18 @@ message CreateSandboxRequest {
   repeated VolumeMount volume_mounts = 6;
   // Optional path to a persistent disk image (ext4) attached as VirtioBlock.
   string disk_image_path = 7;
+  // Host-to-container port mappings for port forwarding.
+  repeated PortMapping port_mappings = 8;
+}
+
+// Host-to-container port mapping for port forwarding.
+message PortMapping {
+  // Host port to listen on.
+  uint32 host_port = 1;
+  // Container port to forward to.
+  uint32 container_port = 2;
+  // Protocol: "tcp" or "udp".
+  string protocol = 3;
 }
 
 // A host directory to expose inside the shared VM via VirtioFS.

crates/vz-runtime-proto/src/generated/vz.runtime.v2.rs

@@ -42,6 +42,22 @@ pub struct CreateSandboxRequest {
     /// Optional path to a persistent disk image (ext4) attached as VirtioBlock.
     #[prost(string, tag = "7")]
     pub disk_image_path: ::prost::alloc::string::String,
+    /// Host-to-container port mappings for port forwarding.
+    #[prost(message, repeated, tag = "8")]
+    pub port_mappings: ::prost::alloc::vec::Vec<PortMapping>,
+}
+/// Host-to-container port mapping for port forwarding.
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct PortMapping {
+    /// Host port to listen on.
+    #[prost(uint32, tag = "1")]
+    pub host_port: u32,
+    /// Container port to forward to.
+    #[prost(uint32, tag = "2")]
+    pub container_port: u32,
+    /// Protocol: "tcp" or "udp".
+    #[prost(string, tag = "3")]
+    pub protocol: ::prost::alloc::string::String,
 }
 /// A host directory to expose inside the shared VM via VirtioFS.
 #[derive(Clone, PartialEq, ::prost::Message)]

crates/vz-runtimed-client/src/sandbox.rs

@@ -356,6 +356,7 @@ impl DaemonClient {
             labels: HashMap::new(),
             volume_mounts: Vec::new(),
             disk_image_path: String::new(),
+            port_mappings: Vec::new(),
         };
         let _ = self.create_sandbox(request).await?;
         Ok(())

crates/vz-runtimed/src/grpc/handlers/sandbox/mod.rs

@@ -9,8 +9,9 @@ use std::path::{Path, PathBuf};
 #[cfg(target_os = "linux")]
 use std::process::Command;
 use vz_runtime_contract::{
-    RuntimeBackend, SPACE_CACHE_KEY_SCHEMA_VERSION, SpaceCacheIndex, SpaceCacheKey,
-    SpaceCacheLookup, SpaceRemoteCacheTrustConfig, SpaceRemoteCacheVerificationOutcome,
+    PortMapping as ContractPortMapping, PortProtocol, RuntimeBackend,
+    SPACE_CACHE_KEY_SCHEMA_VERSION, SpaceCacheIndex, SpaceCacheKey, SpaceCacheLookup,
+    SpaceRemoteCacheTrustConfig, SpaceRemoteCacheVerificationOutcome,
     SpaceRemoteCacheVerifiedArtifact, StackResourceHint, StackVolumeMount,
 };
 use vz_runtime_proto::runtime_v2::container_service_server::ContainerService as _;
@@ -800,6 +801,7 @@ async fn boot_runtime_sandbox_resources(
     labels: &BTreeMap<String, String>,
     explicit_mounts: &[vz_runtime_proto::runtime_v2::VolumeMount],
     disk_image_path: Option<std::path::PathBuf>,
+    port_mappings: &[vz_runtime_proto::runtime_v2::PortMapping],
     request_id: &str,
 ) -> Result<(), Status> {
     let mut volume_mounts = Vec::new();
@@ -855,10 +857,23 @@ async fn boot_runtime_sandbox_resources(
         disk_image_path,
     };
 
+    let ports: Vec<ContractPortMapping> = port_mappings
+        .iter()
+        .map(|pm| ContractPortMapping {
+            host: pm.host_port as u16,
+            container: pm.container_port as u16,
+            protocol: match pm.protocol.as_str() {
+                "udp" => PortProtocol::Udp,
+                _ => PortProtocol::Tcp,
+            },
+            target_host: None,
+        })
+        .collect();
+
     match daemon
         .manager()
         .backend()
-        .boot_shared_vm(sandbox_id, Vec::new(), resources)
+        .boot_shared_vm(sandbox_id, ports, resources)
         .await
     {
         Ok(()) => Ok(()),

crates/vz-runtimed/src/grpc/handlers/sandbox/rpc.rs

@@ -62,6 +62,7 @@ impl runtime_v2::sandbox_service_server::SandboxService for SandboxServiceImpl {
         let normalized_idempotency_key = normalize_idempotency_key(idempotency_key.as_deref());
         let explicit_volume_mounts = request.volume_mounts;
         let explicit_disk_image_path = request.disk_image_path;
+        let explicit_port_mappings = request.port_mappings;
         let mut labels: BTreeMap<String, String> = request.labels.into_iter().collect();
         // Requesters cannot predeclare default-source audit labels.
         labels.remove(SANDBOX_LABEL_BASE_IMAGE_DEFAULT_SOURCE);
@@ -184,6 +185,7 @@ impl runtime_v2::sandbox_service_server::SandboxService for SandboxServiceImpl {
             &labels,
             &explicit_volume_mounts,
             disk_image_path,
+            &explicit_port_mappings,
             &request_id,
         )
         .await