@@ -18,6 +18,21 @@ pub fn container_name(name: &str) -> String {
     format!("openshell-cluster-{name}")
 }
 
+/// Deterministic k3s node name derived from the gateway name.
+///
+/// k3s defaults to using the container hostname (= Docker container ID) as
+/// the node name.  When the container is recreated (e.g. after an image
+/// upgrade), the container ID changes, creating a new k3s node.  The
+/// `clean_stale_nodes` function then deletes PVCs whose backing PVs have
+/// node affinity for the old node — wiping the server database and any
+/// sandbox persistent volumes.
+///
+/// By passing a deterministic `--node-name` to k3s, the node identity
+/// survives container recreation, and PVCs are never orphaned.
+pub fn node_name(name: &str) -> String {
+    format!("openshell-{name}")
+}
+
 pub fn volume_name(name: &str) -> String {
     format!("openshell-cluster-{name}")
 }
 
@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 use crate::RemoteOptions;
-use crate::constants::{container_name, network_name, volume_name};
+use crate::constants::{container_name, network_name, node_name, volume_name};
 use crate::image::{self, DEFAULT_IMAGE_REPO_BASE, DEFAULT_REGISTRY, parse_image_ref};
 use bollard::API_DEFAULT_VERSION;
 use bollard::Docker;
@@ -684,6 +684,11 @@ pub async fn ensure_container(
         format!("REGISTRY_HOST={registry_host}"),
         format!("REGISTRY_INSECURE={registry_insecure}"),
         format!("IMAGE_REPO_BASE={image_repo_base}"),
+        // Deterministic k3s node name so the node identity survives container
+        // recreation (e.g. after an image upgrade). Without this, k3s uses
+        // the container ID as the hostname/node name, which changes on every
+        // container recreate and triggers stale-node PVC cleanup.
+        format!("OPENSHELL_NODE_NAME={}", node_name(name)),
     ];
     if let Some(endpoint) = registry_endpoint {
         env_vars.push(format!("REGISTRY_ENDPOINT={endpoint}"));
 
@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-use crate::constants::{KUBECONFIG_PATH, container_name};
+use crate::constants::{KUBECONFIG_PATH, container_name, node_name};
 use bollard::Docker;
 use bollard::container::LogOutput;
 use bollard::exec::CreateExecOptions;
@@ -385,11 +385,17 @@ pub async fn clean_stale_nodes(docker: &Docker, name: &str) -> Result<usize> {
     let container_name = container_name(name);
     let mut stale_nodes: Vec<String> = Vec::new();
 
+    // Use the deterministic node name derived from the gateway name.
+    // This matches the `--node-name` flag passed to k3s in the entrypoint
+    // script.  Any k3s node that doesn't match this name is stale (left over
+    // from a previous container that used the container ID as hostname).
+    let expected_node = node_name(name);
+
     for attempt in 1..=MAX_ATTEMPTS {
-        // List ALL node names and the container's own hostname.  Any node that
-        // is not the current container is stale — we cannot rely on the Ready
-        // condition because k3s may not have marked the old node NotReady yet
-        // when this runs shortly after container start.
+        // List ALL node names.  Any node that is not the expected deterministic
+        // name is stale — we cannot rely on the Ready condition because k3s
+        // may not have marked the old node NotReady yet when this runs shortly
+        // after container start.
         let (output, exit_code) = exec_capture_with_exit(
             docker,
             &container_name,
@@ -406,16 +412,10 @@ pub async fn clean_stale_nodes(docker: &Docker, name: &str) -> Result<usize> {
         .await?;
 
         if exit_code == 0 {
-            // Determine the current node name (container hostname).
-            let (hostname_out, _) =
-                exec_capture_with_exit(docker, &container_name, vec!["hostname".to_string()])
-                    .await?;
-            let current_hostname = hostname_out.trim().to_string();
-
             stale_nodes = output
                 .lines()
                 .map(str::trim)
-                .filter(|l| !l.is_empty() && *l != current_hostname)
+                .filter(|l| !l.is_empty() && *l != expected_node)
                 .map(ToString::to_string)
                 .collect();
             break;
 
@@ -34,6 +34,18 @@ const SANDBOX_MANAGED_VALUE: &str = "openshell";
 const GPU_RESOURCE_NAME: &str = "nvidia.com/gpu";
 const GPU_RESOURCE_QUANTITY: &str = "1";
 
+/// Name of the default PersistentVolumeClaim template added to sandbox pods
+/// so that workspace data survives pod rescheduling (e.g. across gateway
+/// stop/start cycles).  The Sandbox CRD controller creates a PVC from this
+/// template and mounts it into the agent container.
+const DEFAULT_WORKSPACE_VOLUME_NAME: &str = "workspace";
+
+/// Mount path for the default workspace PVC inside the agent container.
+const DEFAULT_WORKSPACE_MOUNT_PATH: &str = "/home/user";
+
+/// Default storage size for the workspace PVC.
+const DEFAULT_WORKSPACE_STORAGE: &str = "1Gi";
+
 #[derive(Clone)]
 pub struct SandboxClient {
     client: Client,
@@ -748,6 +760,18 @@ fn sandbox_to_k8s_spec(
     host_gateway_ip: &str,
 ) -> serde_json::Value {
     let mut root = serde_json::Map::new();
+
+    // Determine whether the user provided custom volumeClaimTemplates.
+    // When they haven't, we inject a default workspace VCT so sandbox data
+    // persists across pod rescheduling.  We must know this before building
+    // the podTemplate so the workspace volume mount is only added when the
+    // corresponding VCT is present — a dangling mount would prevent scheduling.
+    let user_has_vct = spec
+        .and_then(|s| s.template.as_ref())
+        .and_then(|t| struct_to_json(&t.volume_claim_templates))
+        .is_some();
+    let inject_default_workspace = !user_has_vct;
+
     if let Some(spec) = spec {
         if !spec.log_level.is_empty() {
             root.insert("logLevel".to_string(), serde_json::json!(spec.log_level));
@@ -775,6 +799,7 @@ fn sandbox_to_k8s_spec(
                     &spec.environment,
                     client_tls_secret_name,
                     host_gateway_ip,
+                    inject_default_workspace,
                 ),
             );
             if !template.agent_socket.is_empty() {
@@ -789,6 +814,15 @@ fn sandbox_to_k8s_spec(
         }
     }
 
+    // Inject the default workspace volumeClaimTemplate when the user didn't
+    // provide their own.
+    if inject_default_workspace {
+        root.insert(
+            "volumeClaimTemplates".to_string(),
+            default_workspace_volume_claim_templates(),
+        );
+    }
+
     // podTemplate is required by the Kubernetes CRD - ensure it's always present
     if !root.contains_key("podTemplate") {
         let empty_env = std::collections::HashMap::new();
@@ -809,6 +843,7 @@ fn sandbox_to_k8s_spec(
                 spec_env,
                 client_tls_secret_name,
                 host_gateway_ip,
+                inject_default_workspace,
             ),
         );
     }
@@ -833,6 +868,7 @@ fn sandbox_template_to_k8s(
     spec_environment: &std::collections::HashMap<String, String>,
     client_tls_secret_name: &str,
     host_gateway_ip: &str,
+    inject_default_workspace: bool,
 ) -> serde_json::Value {
     // The supervisor binary is always side-loaded from the node filesystem
     // via a hostPath volume, regardless of which sandbox image is used.
@@ -905,15 +941,34 @@ fn sandbox_template_to_k8s(
         }),
     );
 
+    // Build volume mounts for the agent container.
+    let mut volume_mounts: Vec<serde_json::Value> = Vec::new();
+
+    // Default workspace volume mount so sandbox data persists across pod
+    // rescheduling.  Only added when the default workspace volumeClaimTemplate
+    // was injected (i.e. the user didn't provide custom volumeClaimTemplates).
+    // Adding this mount without the corresponding VCT would cause a dangling
+    // reference that prevents the pod from scheduling.
+    if inject_default_workspace {
+        volume_mounts.push(serde_json::json!({
+            "name": DEFAULT_WORKSPACE_VOLUME_NAME,
+            "mountPath": DEFAULT_WORKSPACE_MOUNT_PATH
+        }));
+    }
+
     // Mount client TLS secret for mTLS to the server.
     if !client_tls_secret_name.is_empty() {
+        volume_mounts.push(serde_json::json!({
+            "name": "openshell-client-tls",
+            "mountPath": "/etc/openshell-tls/client",
+            "readOnly": true
+        }));
+    }
+
+    if !volume_mounts.is_empty() {
         container.insert(
             "volumeMounts".to_string(),
-            serde_json::json!([{
-                "name": "openshell-client-tls",
-                "mountPath": "/etc/openshell-tls/client",
-                "readOnly": true
-            }]),
+            serde_json::Value::Array(volume_mounts),
         );
     }
 
@@ -978,6 +1033,28 @@ fn container_resources(template: &SandboxTemplate, gpu: bool) -> Option<serde_js
     }
 }
 
+/// Build the default `volumeClaimTemplates` array for sandbox pods.
+///
+/// Provides a single PVC named "workspace" that backs the sandbox home
+/// directory.  This ensures user data (files, installed packages, etc.)
+/// persists across pod rescheduling — which happens whenever the gateway
+/// is stopped and restarted.
+fn default_workspace_volume_claim_templates() -> serde_json::Value {
+    serde_json::json!([{
+        "metadata": {
+            "name": DEFAULT_WORKSPACE_VOLUME_NAME
+        },
+        "spec": {
+            "accessModes": ["ReadWriteOnce"],
+            "resources": {
+                "requests": {
+                    "storage": DEFAULT_WORKSPACE_STORAGE
+                }
+            }
+        }
+    }])
+}
+
 fn apply_gpu_limit(resources: &mut serde_json::Value) {
     let Some(resources_obj) = resources.as_object_mut() else {
         *resources = serde_json::json!({});
@@ -1631,6 +1708,7 @@ mod tests {
             &std::collections::HashMap::new(),
             "",
             "",
+            true,
         );
 
         assert_eq!(
@@ -1664,6 +1742,7 @@ mod tests {
             &std::collections::HashMap::new(),
             "",
             "",
+            true,
         );
 
         assert_eq!(
@@ -1693,6 +1772,7 @@ mod tests {
             &std::collections::HashMap::new(),
             "",
             "",
+            true,
         );
 
         assert_eq!(
@@ -1735,6 +1815,7 @@ mod tests {
             &std::collections::HashMap::new(),
             "",
             "",
+            true,
         );
 
         let limits = &pod_template["spec"]["containers"][0]["resources"]["limits"];
@@ -1761,6 +1842,7 @@ mod tests {
             &std::collections::HashMap::new(),
             "",
             "172.17.0.1",
+            true,
         );
 
         let host_aliases = pod_template["spec"]["hostAliases"]
@@ -1791,6 +1873,7 @@ mod tests {
             &std::collections::HashMap::new(),
             "",
             "",
+            true,
         );
 
         assert!(
@@ -1816,6 +1899,7 @@ mod tests {
             &std::collections::HashMap::new(),
             "my-tls-secret",
             "",
+            true,
         );
 
         let volumes = pod_template["spec"]["volumes"]
@@ -1831,4 +1915,74 @@ mod tests {
             "TLS secret volume must use mode 0400 to prevent sandbox user from reading the private key"
         );
     }
+
+    #[test]
+    fn default_workspace_mount_injected_when_no_custom_vct() {
+        let pod_template = sandbox_template_to_k8s(
+            &SandboxTemplate::default(),
+            false,
+            "openshell/sandbox:latest",
+            "",
+            "sandbox-id",
+            "sandbox-name",
+            "https://gateway.example.com",
+            "0.0.0.0:2222",
+            "secret",
+            300,
+            &std::collections::HashMap::new(),
+            "",
+            "",
+            true, // inject_default_workspace = true
+        );
+
+        let mounts = pod_template["spec"]["containers"][0]["volumeMounts"]
+            .as_array()
+            .expect("volumeMounts should exist");
+        let workspace_mount = mounts
+            .iter()
+            .find(|m| m["name"] == DEFAULT_WORKSPACE_VOLUME_NAME);
+        assert!(
+            workspace_mount.is_some(),
+            "workspace mount should be present when inject_default_workspace is true"
+        );
+        assert_eq!(
+            workspace_mount.unwrap()["mountPath"],
+            DEFAULT_WORKSPACE_MOUNT_PATH
+        );
+    }
+
+    #[test]
+    fn workspace_mount_not_injected_when_custom_vct_provided() {
+        // When the user provides custom volumeClaimTemplates, the workspace
+        // mount must NOT be added — a dangling mount would prevent scheduling.
+        let pod_template = sandbox_template_to_k8s(
+            &SandboxTemplate::default(),
+            false,
+            "openshell/sandbox:latest",
+            "",
+            "sandbox-id",
+            "sandbox-name",
+            "https://gateway.example.com",
+            "0.0.0.0:2222",
+            "secret",
+            300,
+            &std::collections::HashMap::new(),
+            "",
+            "",
+            false, // inject_default_workspace = false (user provided custom VCTs)
+        );
+
+        // volumeMounts should either be absent or not contain "workspace"
+        let has_workspace_mount = pod_template["spec"]["containers"][0]["volumeMounts"]
+            .as_array()
+            .map_or(false, |mounts| {
+                mounts
+                    .iter()
+                    .any(|m| m["name"] == DEFAULT_WORKSPACE_VOLUME_NAME)
+            });
+        assert!(
+            !has_workspace_mount,
+            "workspace mount must NOT be present when user provides custom volumeClaimTemplates"
+        );
+    }
 }
@@ -559,8 +559,26 @@ fi
 # routing to settle first.
 wait_for_default_route
 
+# ---------------------------------------------------------------------------
+# Deterministic k3s node name
+# ---------------------------------------------------------------------------
+# By default k3s uses the container hostname (= Docker container ID) as the
+# node name.  When the container is recreated (e.g. after an image upgrade),
+# the container ID changes, registering a new k3s node.  The bootstrap code
+# then deletes PVCs whose backing PVs have node affinity for the old node —
+# wiping the server database and any sandbox persistent volumes.
+#
+# OPENSHELL_NODE_NAME is set by the bootstrap code to a deterministic value
+# derived from the gateway name, so the node identity survives container
+# recreation and PVCs are never orphaned.
+NODE_NAME_ARG=""
+if [ -n "${OPENSHELL_NODE_NAME:-}" ]; then
+    NODE_NAME_ARG="--node-name=${OPENSHELL_NODE_NAME}"
+    echo "Using deterministic k3s node name: ${OPENSHELL_NODE_NAME}"
+fi
+
 # Execute k3s with explicit resolv-conf passed as a kubelet arg.
 # k3s v1.35.2+ no longer accepts --resolv-conf as a top-level server flag;
 # it must be passed via --kubelet-arg instead.
 # shellcheck disable=SC2086
-exec /bin/k3s "$@" --kubelet-arg=resolv-conf="$RESOLV_CONF" $EXTRA_KUBELET_ARGS
+exec /bin/k3s "$@" $NODE_NAME_ARG --kubelet-arg=resolv-conf="$RESOLV_CONF" $EXTRA_KUBELET_ARGS