feat(driver-vm): add configurable sandbox UID/GID and update docs/examples

Phase 4 of the numeric-UID plan: replace hardcoded SANDBOX_UID (10001)
in VM rootfs preparation with configurable sandbox_uid/sandbox_gid fields.

Changes:
- Add sandbox_uid/sandbox_gid to VmDriverConfig with serde derives
- Pass resolved UID/GID through prepare_sandbox_rootfs_from_image_root
  to ensure_sandbox_guest_user which writes /etc/passwd/group/gshadow
- Update BYOC Dockerfile: remove groupadd/useradd, document runtime UID
  injection and the ability to skip baked-in sandbox user
- Update gateway-config.mdx: document sandbox_uid/sandbox_gid for both
  Kubernetes (with OpenShift SCC autodetection) and VM drivers
- Update sandbox-compute-drivers.mdx: add Sandbox User Identity section
  explaining numeric UID support across all compute drivers
- Update rootfs tests to use non-default UIDs, verify config passthrough

Signed-off-by: Seth Jennings <sjenning@redhat.com>

Author: sjenning

crates/openshell-driver-vm/src/driver.rs

@@ -207,7 +207,7 @@ enum GuestImagePayloadSource {
     LocalDocker { rootfs_archive: PathBuf },
 }
 
-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
 pub struct VmDriverConfig {
     pub openshell_endpoint: String,
     pub state_dir: PathBuf,
@@ -225,8 +225,19 @@ pub struct VmDriverConfig {
     pub gpu_enabled: bool,
     pub gpu_mem_mib: u32,
     pub gpu_vcpus: u8,
+    /// Resolved sandbox UID for rootfs `/etc/passwd` entry.
+    /// When empty, defaults to 10001 (the legacy hardcoded value).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub sandbox_uid: Option<u32>,
+    /// Resolved sandbox GID for rootfs `/etc/passwd` and `/etc/group` entries.
+    /// When empty, defaults to the resolved UID.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub sandbox_gid: Option<u32>,
 }
 
+/// Default sandbox UID used by the VM driver when no config value is set.
+pub const DEFAULT_SANDBOX_UID: u32 = 10001;
+
 impl Default for VmDriverConfig {
     fn default() -> Self {
         Self {
@@ -246,11 +257,23 @@ impl Default for VmDriverConfig {
             gpu_enabled: false,
             gpu_mem_mib: 8192,
             gpu_vcpus: 4,
+            sandbox_uid: None,
+            sandbox_gid: None,
         }
     }
 }
 
 impl VmDriverConfig {
+    /// Resolve the sandbox UID, falling back to DEFAULT_SANDBOX_UID.
+    pub fn resolve_sandbox_uid(&self) -> u32 {
+        self.sandbox_uid.unwrap_or(DEFAULT_SANDBOX_UID)
+    }
+
+    /// Resolve the sandbox GID, falling back to the resolved UID.
+    pub fn resolve_sandbox_gid(&self, resolved_uid: u32) -> u32 {
+        self.sandbox_gid.unwrap_or(resolved_uid)
+    }
+
     fn requires_tls_materials(&self) -> bool {
         self.openshell_endpoint.starts_with("https://")
     }
@@ -2545,21 +2568,28 @@ impl VmDriver {
         let image_identity_owned = image_identity.to_string();
         let exported_rootfs_for_build = exported_rootfs.clone();
         let prepared_rootfs_for_build = prepared_rootfs.clone();
+        let sandbox_uid = self.config.resolve_sandbox_uid();
+        let sandbox_gid = self.config.resolve_sandbox_gid(sandbox_uid);
         self.publish_vm_progress(
             sandbox_id,
             "PreparingRootfs",
-            format!("Preparing VM rootfs for local image \"{image_ref}\""),
+            format!(
+                "Preparing VM rootfs for local image \"{image_ref}\" (sandbox uid={sandbox_uid})"
+            ),
             HashMap::from([
                 ("image_ref".to_string(), image_ref.to_string()),
                 ("image_source".to_string(), "local_docker".to_string()),
                 ("image_identity".to_string(), image_identity.to_string()),
+                ("sandbox_uid".to_string(), sandbox_uid.to_string()),
             ]),
         );
         let prepare_result = tokio::task::spawn_blocking(move || {
             extract_rootfs_archive_to(&exported_rootfs_for_build, &prepared_rootfs_for_build)?;
             prepare_sandbox_rootfs_from_image_root(
                 &prepared_rootfs_for_build,
                 &image_identity_owned,
+                sandbox_uid,
+                sandbox_gid,
             )
             .map_err(|err| {
                 format!("vm sandbox image '{image_ref_owned}' is not base-compatible: {err}")
@@ -2678,20 +2708,25 @@ impl VmDriver {
         let image_ref_owned = image_ref.to_string();
         let image_identity_owned = image_identity.to_string();
         let prepared_rootfs_for_build = prepared_rootfs.clone();
+        let sandbox_uid = self.config.resolve_sandbox_uid();
+        let sandbox_gid = self.config.resolve_sandbox_gid(sandbox_uid);
         self.publish_vm_progress(
             sandbox_id,
             "PreparingRootfs",
-            format!("Preparing VM rootfs for image \"{image_ref}\""),
+            format!("Preparing VM rootfs for image \"{image_ref}\" (sandbox uid={sandbox_uid})"),
             HashMap::from([
                 ("image_ref".to_string(), image_ref.to_string()),
                 ("image_source".to_string(), "registry".to_string()),
                 ("image_identity".to_string(), image_identity.to_string()),
+                ("sandbox_uid".to_string(), sandbox_uid.to_string()),
             ]),
         );
         let prepare_result = tokio::task::spawn_blocking(move || {
             prepare_sandbox_rootfs_from_image_root(
                 &prepared_rootfs_for_build,
                 &image_identity_owned,
+                sandbox_uid,
+                sandbox_gid,
             )
             .map_err(|err| {
                 format!("vm sandbox image '{image_ref_owned}' is not base-compatible: {err}")

crates/openshell-driver-vm/src/main.rs

@@ -214,6 +214,8 @@ async fn main() -> Result<()> {
         gpu_enabled: args.gpu,
         gpu_mem_mib: args.gpu_mem_mib,
         gpu_vcpus: args.gpu_vcpus,
+        sandbox_uid: None,
+        sandbox_gid: None,
     })
     .await
     .map_err(|err| miette::miette!("{err}"))?;

crates/openshell-driver-vm/src/rootfs.rs

@@ -29,8 +29,10 @@ pub const fn sandbox_guest_init_path() -> &'static str {
 pub fn prepare_sandbox_rootfs_from_image_root(
     rootfs: &Path,
     image_identity: &str,
+    sandbox_uid: u32,
+    sandbox_gid: u32,
 ) -> Result<(), String> {
-    prepare_sandbox_rootfs(rootfs)?;
+    prepare_sandbox_rootfs(rootfs, sandbox_uid, sandbox_gid)?;
     validate_sandbox_rootfs(rootfs)?;
     fs::write(
         rootfs.join(ROOTFS_VARIANT_MARKER),
@@ -348,7 +350,7 @@ fn append_symlink_to_archive(
         .map_err(|e| format!("append symlink {}: {e}", source_path.display()))
 }
 
-fn prepare_sandbox_rootfs(rootfs: &Path) -> Result<(), String> {
+fn prepare_sandbox_rootfs(rootfs: &Path, sandbox_uid: u32, sandbox_gid: u32) -> Result<(), String> {
     for relative in ["opt/openshell/.initialized", "opt/openshell/.rootfs-type"] {
         remove_rootfs_path(rootfs, relative)?;
     }
@@ -377,7 +379,7 @@ fn prepare_sandbox_rootfs(rootfs: &Path) -> Result<(), String> {
     fs::create_dir_all(&opt_dir).map_err(|e| format!("create {}: {e}", opt_dir.display()))?;
     fs::write(opt_dir.join(".rootfs-type"), "sandbox\n")
         .map_err(|e| format!("write sandbox rootfs marker: {e}"))?;
-    ensure_sandbox_guest_user(rootfs)?;
+    ensure_sandbox_guest_user(rootfs, sandbox_uid, sandbox_gid)?;
     create_sandbox_mountpoint(&rootfs.join("sandbox"))?;
     create_sandbox_mountpoint(&rootfs.join("image-cache"))?;
     create_sandbox_mountpoint(&rootfs.join("lower"))?;
@@ -752,24 +754,25 @@ fn temporary_injection_path(image_path: &Path) -> PathBuf {
     ))
 }
 
-fn ensure_sandbox_guest_user(rootfs: &Path) -> Result<(), String> {
-    const SANDBOX_UID: u32 = 10001;
-    const SANDBOX_GID: u32 = 10001;
-
+fn ensure_sandbox_guest_user(
+    rootfs: &Path,
+    sandbox_uid: u32,
+    sandbox_gid: u32,
+) -> Result<(), String> {
     let etc_dir = rootfs.join("etc");
     fs::create_dir_all(&etc_dir).map_err(|e| format!("create {}: {e}", etc_dir.display()))?;
 
     ensure_line_in_file(
         &etc_dir.join("group"),
-        &format!("sandbox:x:{SANDBOX_GID}:"),
+        &format!("sandbox:x:{sandbox_gid}:"),
         |line| line.starts_with("sandbox:"),
     )?;
     ensure_line_in_file(&etc_dir.join("gshadow"), "sandbox:!::", |line| {
         line.starts_with("sandbox:")
     })?;
     ensure_line_in_file(
         &etc_dir.join("passwd"),
-        &format!("sandbox:x:{SANDBOX_UID}:{SANDBOX_GID}:OpenShell Sandbox:/sandbox:/bin/bash"),
+        &format!("sandbox:x:{sandbox_uid}:{sandbox_gid}:OpenShell Sandbox:/sandbox:/bin/bash"),
         |line| line.starts_with("sandbox:"),
     )?;
     ensure_line_in_file(
@@ -936,7 +939,9 @@ mod tests {
         fs::write(rootfs.join("bin/sed"), b"sed").expect("write sed");
         fs::write(rootfs.join("sbin/ip"), b"ip").expect("write ip");
 
-        prepare_sandbox_rootfs(&rootfs).expect("prepare sandbox rootfs");
+        // Use a non-standard UID so the test doesn't collide with the default.
+        let uid = 20001;
+        prepare_sandbox_rootfs(&rootfs, uid, uid).expect("prepare sandbox rootfs");
         validate_sandbox_rootfs(&rootfs).expect("validate sandbox rootfs");
 
         assert!(rootfs.join("srv/openshell-vm-sandbox-init.sh").is_file());
@@ -955,12 +960,14 @@ mod tests {
         assert!(
             fs::read_to_string(rootfs.join("etc/passwd"))
                 .expect("read passwd")
-                .contains("sandbox:x:10001:10001:OpenShell Sandbox:/sandbox:/bin/bash")
+                .contains(&format!(
+                    "sandbox:x:{uid}:{uid}:OpenShell Sandbox:/sandbox:/bin/bash"
+                ))
         );
         assert!(
             fs::read_to_string(rootfs.join("etc/group"))
                 .expect("read group")
-                .contains("sandbox:x:10001:")
+                .contains(&format!("sandbox:x:{uid}:"))
         );
         assert_eq!(
             fs::read_to_string(rootfs.join("etc/hosts")).expect("read hosts"),
@@ -980,7 +987,7 @@ mod tests {
         fs::create_dir_all(rootfs.join("sandbox")).expect("create sandbox workdir");
         fs::write(rootfs.join("sandbox/app.py"), "print('hello')\n").expect("write app");
 
-        prepare_sandbox_rootfs(&rootfs).expect("prepare sandbox rootfs");
+        prepare_sandbox_rootfs(&rootfs, 10001, 10001).expect("prepare sandbox rootfs");
 
         assert!(rootfs.join("sandbox").is_dir());
         assert_eq!(

docs/reference/gateway-config.mdx

@@ -197,6 +197,12 @@ sa_token_ttl_secs              = 3600
 # shared roots such as /run, /var, /tmp, and /etc are rejected.
 # Supervisor-to-gateway auth still uses gateway JWTs.
 provider_spiffe_workload_api_socket_path = "/spiffe-workload-api/spire-agent.sock"
+# Explicit sandbox UID/GID for the supervisor container securityContext and
+# PVC init container. When unset, the driver auto-detects from OpenShift SCC
+# namespace annotations (openshift.io/sa.scc.uid-range) if present, falling
+# back to 1000 on non-OpenShift clusters.
+# sandbox_uid = 1500
+# sandbox_gid = 1500
 ```
 
 ### Docker
@@ -309,6 +315,9 @@ overlay_disk_mib = 4096
 guest_tls_ca     = "/var/lib/openshell/guest-tls/ca.pem"
 guest_tls_cert   = "/var/lib/openshell/guest-tls/client.pem"
 guest_tls_key    = "/var/lib/openshell/guest-tls/client-key.pem"
+# Resolved sandbox UID/GID for the rootfs /etc/passwd entry.
+# Defaults to 10001 when unset; matching GID is used if sandbox_gid is empty.
+# sandbox_uid = 20001
 ```
 
 ### Extension Driver

docs/reference/sandbox-compute-drivers.mdx

@@ -315,3 +315,29 @@ If Agent Sandbox is upgraded in place, restart the OpenShell gateway after the c
 <Note>
 `Sandbox.spec.volumeClaimTemplates` is immutable after creation. To change storage configuration, delete the sandbox and create a new one with the updated spec.
 </Note>
+
+## Sandbox User Identity
+
+OpenShell accepts both the hardcoded username `"sandbox"` and numeric UIDs in `[1000, 2_000_000_000]` for the supervisor's process identity (the policy's `run_as_user` field). The driver resolves the UID at sandbox creation time and passes it to the supervisor via environment variables.
+
+### Kubernetes / OpenShift
+
+The Kubernetes driver auto-detects the sandbox UID from OpenShift SCC namespace annotations:
+
+- `openshift.io/sa.scc.uid-range` (format: `<start>/<size>`, e.g. `1000000000/10000`) provides the UID.
+- `openshift.io/sa.scc.supplemental-groups` provides the GID when present; otherwise the resolved UID is used as the GID.
+- On non-OpenShift clusters, or when annotations are absent, the driver falls back to `1000`.
+
+You can override autodetection with explicit `sandbox_uid` / `sandbox_gid` config in `[openshell.drivers.kubernetes]`. When set, the driver skips namespace annotation lookup entirely.
+
+The resolved UID/GID appear in:
+- Supervisor container environment variables (`OPENSHELL_SANDBOX_UID`, `OPENSHELL_SANDBOX_GID`) for direct kernel-level privilege dropping without `/etc/passwd` lookups.
+- PVC init container `securityContext.runAsUser/runAsGroup/fsGroup` for workspace ownership operations.
+
+### VM Driver
+
+The VM driver injects the sandbox UID into the rootfs guest's `/etc/passwd`, `/etc/group`, and `/etc/gshadow` during rootfs preparation. Default UID is `10001`; configure `sandbox_uid` in `[openshell.drivers.vm]` to use a different value.
+
+### Custom Images
+
+Custom sandbox images no longer need a baked-in `"sandbox"` user. If your image requires a passwd entry for tools like `sudo` or `ssh`, add one manually (e.g. `RUN useradd -m -u 1500 deploy`). The supervisor resolves the numeric UID directly via `setuid()` without needing `/etc/passwd`.

examples/bring-your-own-container/Dockerfile

@@ -14,15 +14,19 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
         curl iproute2 nftables \
     && rm -rf /var/lib/apt/lists/*
 
-# Create the sandbox user for non-root execution.
-# Use a high UID range to avoid conflicts with host users when running without
-# user namespace remapping (UID in container = UID on host).
-RUN groupadd -g 1000660000 sandbox && \
-    useradd -m -u 1000660000 -g sandbox sandbox
+# The sandbox user is injected at runtime by the compute driver.
+# Kubernetes: resolved from OpenShift SCC namespace annotations or explicit
+# sandbox_uid config. VM: resolves to 10001 by default, configurable in
+# gateway TOML.
+#
+# Images no longer need a baked-in "sandbox" user — numeric UIDs are accepted
+# and the driver passes them directly to setuid()/chown() at sandbox start.
+# If your image requires a passwd entry for tools like ssh or sudo, add one
+# manually (e.g. RUN useradd -m -u 1500 deploy).
 
-RUN install -d -o sandbox -g sandbox /sandbox
+RUN install -d /sandbox
 WORKDIR /sandbox
-COPY --chown=sandbox:sandbox app.py .
+COPY app.py .
 
 EXPOSE 8080