feat(sandbox): add gpu sandbox scheduling support (#257)

* feat(sandbox): add gpu sandbox scheduling support

Allow sandbox creation to request GPU resources explicitly or infer them from GPU image names. This wires GPU intent through bootstrap, validates gateway support, and adds dedicated GPU E2E coverage for follow-up cluster testing.

Author: pimlock

architecture/gateway-single-node.md

@@ -299,6 +299,7 @@ GPU support is part of the single-node gateway bootstrap path rather than a sepa
 - `deploy/docker/cluster-entrypoint.sh` checks `GPU_ENABLED=true` and copies GPU-only manifests from `/opt/openshell/gpu-manifests/` into k3s's manifests directory.
 - `deploy/kube/gpu-manifests/nvidia-device-plugin-helmchart.yaml` installs the NVIDIA device plugin chart, currently pinned to `0.18.2`, along with GPU Feature Discovery and Node Feature Discovery.
 - k3s auto-detects `nvidia-container-runtime` on `PATH`, registers the `nvidia` containerd runtime, and creates the `nvidia` `RuntimeClass` automatically.
+- The OpenShell Helm chart grants the gateway service account cluster-scoped read access to `node.k8s.io/runtimeclasses` and core `nodes` so GPU sandbox admission can verify both the `nvidia` `RuntimeClass` and allocatable GPU capacity before creating a sandbox.
 
 The runtime chain is:
 
@@ -377,6 +378,7 @@ When `openshell sandbox create` cannot connect to a gateway (connection refused,
 1. `should_attempt_bootstrap()` in `crates/openshell-cli/src/bootstrap.rs` checks the error type. It returns `true` for connectivity errors and missing default TLS materials, but `false` for TLS handshake/auth errors.
 2. If running in a terminal, the user is prompted to confirm.
 3. `run_bootstrap()` deploys a gateway named `"openshell"`, sets it as active, and returns fresh `TlsOptions` pointing to the newly-written mTLS certs.
+4. When `sandbox create` requests GPU explicitly (`--gpu`) or infers it from an image whose final name component contains `gpu` (such as `nvidia-gpu`), the bootstrap path enables gateway GPU support before retrying sandbox creation.
 
 ## Container Environment Variables
 

architecture/sandbox-custom-containers.md

@@ -24,6 +24,10 @@ The CLI classifies the value in this order:
 
 The community registry prefix defaults to `ghcr.io/nvidia/openshell-community/sandboxes` and can be overridden with the `OPENSHELL_COMMUNITY_REGISTRY` environment variable.
 
+### GPU image-name detection
+
+`sandbox create` also infers GPU intent from the final image name. The current rule matches when the last image name component contains `gpu` (for example `ghcr.io/nvidia/openshell-community/sandboxes/nvidia-gpu:latest` or `registry.example.com/team/my-gpu-image:latest`). When that rule matches, the sandbox request is treated the same as passing `--gpu`.
+
 ### Dockerfile build flow
 
 When `--from` points to a Dockerfile or directory, the CLI:

crates/openshell-cli/src/bootstrap.rs

@@ -122,6 +122,7 @@ fn resolve_bootstrap_name() -> String {
 pub async fn run_bootstrap(
     remote: Option<&str>,
     ssh_key: Option<&str>,
+    gpu: bool,
 ) -> Result<(TlsOptions, String, String)> {
     let gateway_name = resolve_bootstrap_name();
     let location = if remote.is_some() { "remote" } else { "local" };
@@ -159,6 +160,7 @@ pub async fn run_bootstrap(
     {
         options = options.with_registry_token(token);
     }
+    options = options.with_gpu(gpu);
 
     let handle = deploy_gateway_with_panel(options, &gateway_name, location).await?;
     let server = handle.gateway_endpoint().to_string();

crates/openshell-cli/src/main.rs

@@ -1051,6 +1051,14 @@ enum SandboxCommands {
         #[arg(long, value_enum, conflicts_with = "no_keep")]
         editor: Option<CliEditor>,
 
+        /// Request GPU resources for the sandbox.
+        ///
+        /// When no gateway is running, auto-bootstrap starts a GPU-enabled
+        /// gateway. GPU intent is also inferred automatically for known
+        /// GPU-designated image names such as `nvidia-gpu`.
+        #[arg(long)]
+        gpu: bool,
+
         /// SSH destination for remote bootstrap (e.g., user@hostname).
         /// Only used when no cluster exists yet; ignored if a cluster is
         /// already active.
@@ -1791,6 +1799,7 @@ async fn main() -> Result<()> {
                     keep,
                     no_keep,
                     editor,
+                    gpu,
                     remote,
                     ssh_key,
                     providers,
@@ -1868,6 +1877,7 @@ async fn main() -> Result<()> {
                                 &ctx.name,
                                 upload_spec.as_ref(),
                                 keep,
+                                gpu,
                                 editor,
                                 remote.as_deref(),
                                 ssh_key.as_deref(),
@@ -1889,6 +1899,7 @@ async fn main() -> Result<()> {
                                 from.as_deref(),
                                 upload_spec.as_ref(),
                                 keep,
+                                gpu,
                                 editor,
                                 remote.as_deref(),
                                 ssh_key.as_deref(),