docs(gateway-config): VM driver example lists sandbox_uid but VmComputeConfig rejects it #2364

Agent Diagnostic

• Skills loaded: create-github-issue
• OpenShell version tested: main @ 8cf2673
• Latest release checked: unable to verify
• Known fixes reviewed: feat: inject sandbox UID via compute driver instead of requiring it in container images #1959 (sandbox UID injection feature) and feat(drivers): inject local sandbox identity #2335 (Docker/Podman identity injection PR) are in-flight but neither addresses this docs bug
• Possible duplicates reviewed: searched open issues for sandbox_uid — no existing report for this docs problem
• Findings: uncommenting sandbox_uid in the VM driver TOML example crashes the gateway at startup
• Remaining reason for filing: the docs example advertises a field that the gateway TOML parser rejects

Description

Actual behavior: The VM driver example in docs/reference/gateway-config.mdx (lines 423–425) shows:

# sandbox_uid = 20001

Uncommenting this line causes the gateway to crash at config parse time:

Error: configuration error: invalid [openshell.drivers.vm] table: unknown field
`sandbox_uid`, expected one of `state_dir`, `driver_dir`, `default_image`,
`grpc_endpoint`, `bootstrap_image`, `krun_log_level`, `vcpus`, `mem_mib`,
`overlay_disk_mib`, `guest_tls_ca`, `guest_tls_cert`, `guest_tls_key`

VmComputeConfig in crates/openshell-server/src/compute/vm.rs:65 uses #[serde(deny_unknown_fields)] and has no sandbox_uid field.

Expected behavior: The docs example should only show fields that the gateway TOML parser accepts. sandbox_uid exists on VmDriverConfig in the standalone openshell-driver-vm subprocess (crates/openshell-driver-vm/src/driver.rs:231), where it is set via --sandbox-uid / OPENSHELL_VM_SANDBOX_UID CLI args — not through the gateway TOML file.

Reproduction Steps

1. Create a minimal TOML file with the VM driver and sandbox_uid uncommented:

   [openshell]
   version = 1
   
   [openshell.gateway]
   compute_drivers = ["vm"]
   disable_tls = true
   
   [openshell.drivers.vm]
   sandbox_uid = 20001

2. Run openshell gateway --config /path/to/file.toml
3. Observe the "unknown field sandbox_uid" error

Proposed Fix

Remove lines 423–425 (the sandbox_uid comment block) from the VM driver example in docs/reference/gateway-config.mdx. The Kubernetes driver example at line 294 correctly shows sandbox_uid because KubernetesComputeConfig does accept it.

Environment

• OS: macOS Darwin 25.5.0
• OpenShell: main branch (8cf2673)