feat(sandbox): support storage-preserving sandbox configuration updates

.agents/skills/helm-dev-environment/SKILL.md

@@ -319,6 +319,29 @@ above) instead of relying only on `OPENSHELL_GATEWAY_ENDPOINT`; some tests call
 ### Kubernetes E2E Notes
 
 Use `mise run e2e:kubernetes` for the standard Helm-backed Kubernetes suite.
+Set `OPENSHELL_E2E_KUBE_TEST=kubernetes_image_update` to scope the Rust suite to
+combined image, command, environment, and metadata updates with retained sandbox,
+SSH, and PVC identities. The next start verifies the new argv and environment. This target is
+included in both existing Agent Sandbox API-version lanes; unlike the Python
+Docker suite, it exercises the driver that supports image updates.
+
+Image updates default to disabled outside test fixtures. The e2e wrapper opts
+in only for a fresh gateway fixture that it owns; set
+`OPENSHELL_E2E_KUBE_IMAGE_UPDATES=0` to prevent that opt-in. Do not propagate
+activation to an existing shared gateway or enable it during a mixed-version
+rollout. For manual testing, follow the retirement and activation checklist in
+`docs/kubernetes/high-availability.mdx` before setting
+`gatewayConfig: {"openshell.gateway": {enable_sandbox_updates: true}}`.
+The gateway process equivalents are `--enable-sandbox-updates true` and
+`OPENSHELL_ENABLE_SANDBOX_UPDATES=true`. Retire every old process and Job,
+settle outstanding driver work, prevent old binaries returning, and do not
+treat PostgreSQL connection markers or membership TTL expiry as retirement
+proof. SQLite testing supports one gateway process only. Image-update clients
+must call the separate `SandboxUpdates` service on the existing gateway
+listener, not add a method to the baseline `OpenShell` service or inspect new
+public `SandboxStatus` image fields. Pending-operation recovery uses the same
+requested image with a fresh version and the documented request-ID semantics.
+
 The kube e2e wrapper creates only one port-forward, to `svc/openshell`; it no
 longer forwards the unauthenticated health listener or runs a `/readyz` e2e
 target. `/readyz` remains covered by server unit/integration tests.

crates/openshell-core/README.md

@@ -65,6 +65,27 @@ configuration validation live in `openshell_core::middleware`. Policy admission
 and the supervisor runtime consume the same contract without introducing a
 dependency from the policy crate to the supervisor implementation.
 
+## Optional Compute Updates
+
+The generated `proto::compute::v1::compute_driver_server::ComputeDriver` trait
+retains its baseline methods and streaming associated type. External drivers
+that support image updates additionally serve `ComputeDriverImageUpdates` on
+the same endpoint and advertise `openshell.compute.update-sandbox-image`.
+Drivers without that capability need no new generated-trait method.
+
+Drivers supporting command and environment replacement additionally serve
+`ComputeDriverConfigurationUpdates` and advertise
+`openshell.compute.update-sandbox-configuration`. Its separate typed request
+retains image-update lifecycle preconditions. Both optional in-process methods
+have `UNIMPLEMENTED` defaults, so image-only implementations remain valid.
+
+Existing linked in-process drivers and factories need no new trait or hook.
+Only drivers opting into image updates implement
+`openshell_core::compute::ComputeDriver` and register that implementation through
+`ComputeDriverFactory::build_with_image_updates`. The default factory hook calls
+the existing `build` method without an updater. The gateway requires both this
+separate registration and the negotiated capability before invoking updates.
+
 ## Protobuf Struct Conversion
 
 Use `openshell_core::proto_struct` when crossing between `serde_json` values and

crates/openshell-core/src/compute.rs

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//! Opt-in in-process sandbox updates, separate from the baseline driver contract.
+
+use crate::proto::compute::v1::{
+    UpdateSandboxImageRequest, UpdateSandboxImageResponse, compute_driver_server,
+};
+
+/// Optional in-process image updater, registered separately by a driver factory.
+///
+/// Existing drivers need only the generated baseline trait, not this extension.
+/// Supporting factories opt in through `ComputeDriverFactory::build_with_image_updates`
+/// and advertise the image-update capability. External servers use the separate
+/// generated `ComputeDriverImageUpdates` or `ComputeDriverConfigurationUpdates`
+/// service on the same endpoint instead. Each operation requires its own capability.
+#[tonic::async_trait]
+pub trait ComputeDriver: compute_driver_server::ComputeDriver {
+    async fn update_sandbox_configuration(
+        &self,
+        _request: tonic::Request<crate::proto::compute::v1::UpdateSandboxConfigurationRequest>,
+    ) -> Result<
+        tonic::Response<crate::proto::compute::v1::UpdateSandboxConfigurationResponse>,
+        tonic::Status,
+    > {
+        Err(tonic::Status::unimplemented(
+            "sandbox configuration updates are not supported by this driver",
+        ))
+    }
+
+    async fn update_sandbox_image(
+        &self,
+        _request: tonic::Request<UpdateSandboxImageRequest>,
+    ) -> Result<tonic::Response<UpdateSandboxImageResponse>, tonic::Status> {
+        Err(tonic::Status::unimplemented(
+            "storage-preserving image updates are not supported by this driver",
+        ))
+    }
+}

crates/openshell-core/src/config.rs

@@ -252,6 +252,11 @@ pub struct Config {
     /// Disabled for local gateways by default.
     pub enable_websocket_tunnel: bool,
 
+    /// Operator activation after all gateways and outstanding legacy driver
+    /// operations have been drained onto the configuration-update-compatible protocol.
+    /// Disabled by default; not a license to run mixed-version writers.
+    pub enable_sandbox_updates: bool,
+
     /// Disabled-by-default gateway interceptor service configs.
     pub gateway_interceptors: Vec<GatewayInterceptorConfig>,
 
@@ -936,6 +941,7 @@ impl Config {
             oidc: None,
             auth: GatewayAuthConfig::default(),
             enable_websocket_tunnel: false,
+            enable_sandbox_updates: false,
             gateway_interceptors: Vec::new(),
             provider_profile_sources: vec![GatewayProviderProfileSourceConfig::User],
             mtls_auth: MtlsAuthConfig::default(),

crates/openshell-core/src/extension_protocol.rs

@@ -22,6 +22,11 @@ pub const COMPUTE_LAUNCH_AUTHENTICATION: &str = "openshell.compute.launch-authen
 /// Driver stages operator-selected external isolation routes for the supervisor.
 pub const COMPUTE_ISOLATION_BACKEND: &str = "openshell.compute.isolation-backend";
 
+/// Optional stopped-state image updates retaining the resource and its storage.
+pub const COMPUTE_UPDATE_SANDBOX_CONFIGURATION: &str =
+    "openshell.compute.update-sandbox-configuration";
+pub const COMPUTE_UPDATE_SANDBOX_IMAGE: &str = "openshell.compute.update-sandbox-image";
+
 const MAX_IMPLEMENTATION_NAME_BYTES: usize = 128;
 const MAX_IMPLEMENTATION_VERSION_BYTES: usize = 128;
 const MAX_CAPABILITY_BYTES: usize = 128;
@@ -125,6 +130,8 @@ pub fn gateway_metadata(family: ExtensionFamily) -> PeerMetadata {
     if family == ExtensionFamily::Compute {
         supported_capabilities.push(COMPUTE_LAUNCH_AUTHENTICATION.to_string());
         supported_capabilities.push(COMPUTE_ISOLATION_BACKEND.to_string());
+        supported_capabilities.push(COMPUTE_UPDATE_SANDBOX_IMAGE.to_string());
+        supported_capabilities.push(COMPUTE_UPDATE_SANDBOX_CONFIGURATION.to_string());
     }
     PeerMetadata {
         protocol_version: Some(ProtocolVersion {
@@ -396,6 +403,23 @@ fn valid_capability(value: &str) -> bool {
 mod tests {
     use super::*;
 
+    #[test]
+    fn compute_gateway_advertises_both_optional_extensions() {
+        let gateway = gateway_metadata(ExtensionFamily::Compute);
+        assert!(
+            gateway
+                .supported_capabilities
+                .iter()
+                .any(|c| c == COMPUTE_ISOLATION_BACKEND)
+        );
+        assert!(
+            gateway
+                .supported_capabilities
+                .iter()
+                .any(|c| c == COMPUTE_UPDATE_SANDBOX_IMAGE)
+        );
+    }
+
     fn compatible() -> (PeerMetadata, PeerMetadata) {
         let gateway = gateway_metadata(ExtensionFamily::Compute);
         let extension = extension_metadata(

crates/openshell-core/src/lib.rs

@@ -11,6 +11,7 @@
 
 pub mod activity;
 pub mod auth;
+pub mod compute;
 pub mod config;
 pub mod container_paths;
 pub mod denial;
@@ -57,6 +58,7 @@ pub mod rpc_error;
 pub mod sandbox_env;
 pub mod sandbox_generation;
 pub mod sandbox_session;
+pub mod sandbox_update;
 pub mod secrets;
 pub mod settings;
 pub mod shell;

crates/openshell-core/src/sandbox_update.rs

@@ -0,0 +1,48 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//! Shared projections for selected stopped-sandbox configuration changes.
+use crate::proto::{Sandbox, SandboxCommandUpdate, SandboxMapUpdate};
+use std::collections::HashMap;
+
+/// System metadata is never caller-replaceable, including subdomains.
+#[must_use]
+pub fn is_system_metadata_key(key: &str) -> bool {
+    key.split_once('/').is_some_and(|(domain, _)| {
+        domain == "openshell.ai"
+            || domain.ends_with(".openshell.ai")
+            || domain == "agents.x-k8s.io"
+            || domain.ends_with(".agents.x-k8s.io")
+    })
+}
+
+fn replace_user_metadata(current: &mut HashMap<String, String>, update: &SandboxMapUpdate) {
+    current.retain(|key, _| is_system_metadata_key(key));
+    current.extend(update.values.clone());
+}
+
+/// Caller must validate syntax and forbid system keys before projecting.
+pub fn apply_configuration(
+    sandbox: &mut Sandbox,
+    command: Option<&SandboxCommandUpdate>,
+    environment: Option<&SandboxMapUpdate>,
+    labels: Option<&SandboxMapUpdate>,
+    annotations: Option<&SandboxMapUpdate>,
+) {
+    if let Some(spec) = sandbox.spec.as_mut() {
+        if let Some(command) = command {
+            spec.command.clone_from(&command.argv);
+        }
+        if let Some(environment) = environment {
+            spec.environment.clone_from(&environment.values);
+        }
+    }
+    if let Some(metadata) = sandbox.metadata.as_mut() {
+        if let Some(labels) = labels {
+            replace_user_metadata(&mut metadata.labels, labels);
+        }
+        if let Some(annotations) = annotations {
+            replace_user_metadata(&mut metadata.annotations, annotations);
+        }
+    }
+}