docs(gateway): add per-driver TOML example configurations

Adds focused single-driver examples next to the comprehensive
gateway.example.toml: kubernetes, docker, podman, and microvm. Each one
demonstrates the realistic settings for that driver plus how shared
[openshell.gateway] defaults inherit into the driver table.

A new unit test (`checked_in_examples_parse`) loads every example through
the config_file loader so schema drift fails CI rather than silently
shipping a broken example.

Author: TaylorMutch

crates/openshell-server/src/config_file.rs

@@ -515,4 +515,25 @@ version = 2
             .expect_err("missing file must be io error");
         assert!(matches!(err, ConfigFileError::Io { .. }));
     }
+
+    /// Lock in that every checked-in example under `examples/gateway/`
+    /// round-trips through the loader. Catches schema drift the moment a
+    /// field is renamed or a doc snippet falls out of date.
+    #[test]
+    fn checked_in_examples_parse() {
+        let repo_root = Path::new(env!("CARGO_MANIFEST_DIR"))
+            .parent()
+            .and_then(Path::parent)
+            .expect("crate manifest has grandparent");
+        for name in [
+            "gateway.example.toml",
+            "kubernetes.example.toml",
+            "docker.example.toml",
+            "podman.example.toml",
+            "microvm.example.toml",
+        ] {
+            let path = repo_root.join("examples/gateway").join(name);
+            load(&path).unwrap_or_else(|e| panic!("{name} failed to parse: {e}"));
+        }
+    }
 }

examples/gateway/docker.example.toml

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Docker-driver example. Sandboxes run as containers on a local bridge
+# network. The supervisor binary is bind-mounted from the host (no in-cluster
+# image pull required); guest mTLS material is supplied as host paths.
+#
+# `database_url` is env-only — set OPENSHELL_DB_URL / --db-url.
+
+[openshell]
+version = 1
+
+[openshell.gateway]
+bind_address    = "127.0.0.1:8080"
+log_level       = "info"
+compute_drivers = ["docker"]
+
+# Shared defaults inherited into [openshell.drivers.docker].
+supervisor_image = "ghcr.io/nvidia/openshell/supervisor:latest"
+guest_tls_ca     = "/etc/openshell/certs/ca.pem"
+guest_tls_cert   = "/etc/openshell/certs/client.pem"
+guest_tls_key    = "/etc/openshell/certs/client-key.pem"
+
+[openshell.drivers.docker]
+network_name   = "openshell-docker"
+# Skip the image-pull-and-extract step by pointing at a locally built binary.
+supervisor_bin = "/usr/local/libexec/openshell/openshell-sandbox"

examples/gateway/kubernetes.example.toml

@@ -0,0 +1,36 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Kubernetes-driver example. The gateway runs as a Pod and creates sandbox
+# Pods in another namespace. mTLS material for sandboxes is delivered via a
+# Kubernetes Secret rather than host-side file paths.
+#
+# `database_url` is env-only — set OPENSHELL_DB_URL / --db-url.
+
+[openshell]
+version = 1
+
+[openshell.gateway]
+bind_address          = "0.0.0.0:8080"
+health_bind_address   = "0.0.0.0:8081"
+metrics_bind_address  = "0.0.0.0:9090"
+log_level             = "info"
+compute_drivers       = ["kubernetes"]
+
+# Shared defaults inherited into [openshell.drivers.kubernetes].
+default_image          = "ghcr.io/nvidia/openshell/sandbox:latest"
+supervisor_image       = "ghcr.io/nvidia/openshell/supervisor:latest"
+image_pull_policy      = "IfNotPresent"
+client_tls_secret_name = "openshell-client-tls"
+
+[openshell.gateway.tls]
+cert_path      = "/etc/openshell-tls/server/tls.crt"
+key_path       = "/etc/openshell-tls/server/tls.key"
+client_ca_path = "/etc/openshell-tls/client-ca/ca.crt"
+
+[openshell.drivers.kubernetes]
+namespace                  = "agents"
+grpc_endpoint              = "https://openshell-gateway.agents.svc:8080"
+# Use the image volume on K8s >= 1.35 (GA in 1.36); switch to "init-container"
+# on older clusters or where the ImageVolume feature gate is off.
+supervisor_sideload_method = "image-volume"

examples/gateway/microvm.example.toml

@@ -0,0 +1,31 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# microVM-driver example. Each sandbox runs inside its own libkrun microVM
+# managed by the standalone `openshell-driver-vm` subprocess. Use this driver
+# when you want stronger isolation than container namespaces alone.
+#
+# `database_url` is env-only — set OPENSHELL_DB_URL / --db-url.
+
+[openshell]
+version = 1
+
+[openshell.gateway]
+bind_address    = "127.0.0.1:8080"
+log_level       = "info"
+# VM is never auto-detected; an explicit entry here is required.
+compute_drivers = ["vm"]
+
+# Shared defaults inherited into [openshell.drivers.vm].
+default_image  = "ghcr.io/nvidia/openshell/sandbox:latest"
+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"
+
+[openshell.drivers.vm]
+state_dir      = "/var/lib/openshell/vm"
+# Where the gateway looks for the openshell-driver-vm subprocess binary.
+driver_dir     = "/usr/local/libexec/openshell"
+vcpus          = 2
+mem_mib        = 2048
+krun_log_level = 1

examples/gateway/podman.example.toml

@@ -0,0 +1,30 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Podman-driver example. Sandboxes run as Podman containers on a user-mode
+# bridge network. The supervisor image is mounted read-only via Podman's
+# `type=image` mount; guest mTLS material is supplied as host paths.
+#
+# `database_url` is env-only — set OPENSHELL_DB_URL / --db-url.
+
+[openshell]
+version = 1
+
+[openshell.gateway]
+bind_address    = "127.0.0.1:8080"
+log_level       = "info"
+compute_drivers = ["podman"]
+
+# Shared defaults inherited into [openshell.drivers.podman].
+default_image     = "ghcr.io/nvidia/openshell/sandbox:latest"
+supervisor_image  = "ghcr.io/nvidia/openshell/supervisor:latest"
+image_pull_policy = "missing"   # Podman pull policy: always | missing | never | newer
+guest_tls_ca      = "/etc/openshell/certs/ca.pem"
+guest_tls_cert    = "/etc/openshell/certs/client.pem"
+guest_tls_key     = "/etc/openshell/certs/client-key.pem"
+
+[openshell.drivers.podman]
+# Rootless socket path. For root Podman use /run/podman/podman.sock.
+socket_path       = "/run/user/1000/podman/podman.sock"
+network_name      = "openshell"
+stop_timeout_secs = 10