feat: auto-create PVC/Docker volumes on sandbox creation

kubernetes/charts/opensandbox-server/templates/server.yaml

@@ -22,6 +22,9 @@ rules:
   - apiGroups: [""]
     resources: ["secrets"]
     verbs: ["create", "delete", "get"]
+  - apiGroups: [""]
+    resources: ["persistentvolumeclaims"]
+    verbs: ["create", "get"]
   - apiGroups: ["node.k8s.io"]
     resources: ["runtimeclasses"]
     verbs: ["get", "list"]

server/configuration.md

@@ -195,6 +195,9 @@ Host-side storage related to **volume mounts** (host bind allowlist and OSSFS mo
 |-----|------|---------|-------------|
 | `allowed_host_paths` | list of strings | `[]` | Absolute path **prefixes** allowed for **host** bind mounts. If **empty**, all host paths are allowed (**unsafe for production**). |
 | `ossfs_mount_root` | string | `"/mnt/ossfs"` | Host directory under which OSSFS-backed mounts are resolved (`<root>/<bucket>/...`). |
+| `volume_auto_create` | bool | `true` | When enabled, PVC volumes (Kubernetes) and named volumes (Docker) are automatically created if they do not exist. When disabled, referencing a non-existent volume fails with an error. |
+| `volume_auto_delete` | bool | `false` | **Docker only.** When enabled, named volumes that were auto-created by the server are removed when the sandbox is deleted. Pre-existing volumes are never removed. Has no effect on Kubernetes PVCs, whose lifecycle is managed by the StorageClass reclaim policy (`Retain` / `Delete`). |
+| `volume_default_size` | string | `"1Gi"` | Default storage size for auto-created Kubernetes PVCs when the caller does not specify a size in the PVC provisioning hints. |
 
 Sandbox **volume** models (`host`, `pvc`, `ossfs`) in API requests are documented in the OpenAPI specs and OSEPs; this table only covers **server** storage settings.
 

server/opensandbox_server/api/schema.py

@@ -132,10 +132,9 @@ class PVC(BaseModel):
     """
     Platform-managed named volume backend.
 
-    A runtime-neutral abstraction for referencing a pre-existing, platform-managed
-    named volume. The semantics are identical across runtimes: claim an existing
-    volume by name, mount it into the container, and leave volume lifecycle
-    management to the user.
+    A runtime-neutral abstraction for referencing a platform-managed named volume.
+    If the volume does not yet exist and ``volume_auto_create`` is enabled on the
+    server, it will be created automatically using the provisioning hints below.
 
     - Kubernetes: maps to a PersistentVolumeClaim in the same namespace.
     - Docker: maps to a Docker named volume (created via ``docker volume create``).
@@ -152,6 +151,34 @@ class PVC(BaseModel):
         max_length=253,
     )
 
+    # Provisioning hints — used only when auto-creating a new volume.
+    # Ignored if the volume already exists on the platform.
+    storage_class: Optional[str] = Field(
+        None,
+        alias="storageClass",
+        description=(
+            "Kubernetes StorageClass name for auto-created PVCs. "
+            "None means use the cluster default. Ignored for Docker volumes."
+        ),
+    )
+    storage: Optional[str] = Field(
+        None,
+        description=(
+            "Storage capacity request for auto-created PVCs (e.g. '1Gi', '10Gi'). "
+            "Defaults to server-side configured value when omitted. "
+            "Ignored for Docker volumes."
+        ),
+        pattern=r"^\d+(\.\d+)?(Ki|Mi|Gi|Ti|Pi|Ei)?$",
+    )
+    access_modes: Optional[List[str]] = Field(
+        None,
+        alias="accessModes",
+        description=(
+            "Access modes for auto-created PVCs (e.g. ['ReadWriteOnce']). "
+            "Defaults to ['ReadWriteOnce'] when omitted. Ignored for Docker volumes."
+        ),
+    )
+
     class Config:
         populate_by_name = True
 

server/opensandbox_server/config.py

@@ -400,6 +400,31 @@ class StorageConfig(BaseModel):
             "Each entry must be an absolute path (e.g., '/data/opensandbox')."
         ),
     )
+    volume_auto_create: bool = Field(
+        default=True,
+        description=(
+            "When enabled, PVC volumes (Kubernetes) and named volumes (Docker) "
+            "are automatically created if they do not exist. When disabled, "
+            "referencing a non-existent volume will fail."
+        ),
+    )
+    volume_auto_delete: bool = Field(
+        default=False,
+        description=(
+            "When enabled (Docker only), named volumes that were auto-created "
+            "by the server are automatically removed when the sandbox is deleted. "
+            "Volumes that existed before sandbox creation are never removed. "
+            "Has no effect on Kubernetes PVCs, whose lifecycle is managed by "
+            "the StorageClass reclaim policy."
+        ),
+    )
+    volume_default_size: str = Field(
+        default="1Gi",
+        description=(
+            "Default storage size for auto-created PVCs when the caller does "
+            "not specify a size in the PVC provisioning hints."
+        ),
+    )
     ossfs_mount_root: str = Field(
         default="/mnt/ossfs",
         description=(

server/opensandbox_server/examples/example.config.k8s.toml

@@ -49,6 +49,13 @@ execd_image = "opensandbox/execd:v1.0.9"
 # Example: allowed_host_paths = ["/data/opensandbox", "/tmp/sandbox"]
 allowed_host_paths = []
 
+# Auto-create PVC (Kubernetes) or named volumes (Docker) when they don't exist.
+# Set to false to require volumes to be pre-created before sandbox creation.
+volume_auto_create = true
+
+# Default storage size for auto-created Kubernetes PVCs (when caller omits size).
+volume_default_size = "1Gi"
+
 [kubernetes]
 # Path to kubeconfig file. Leave as null to use in-cluster configuration
 # Replace with your path

server/opensandbox_server/examples/example.config.k8s.zh.toml

@@ -50,6 +50,13 @@ execd_image = "sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/execd
 # 示例：allowed_host_paths = ["/data/opensandbox", "/tmp/sandbox"]
 allowed_host_paths = []
 
+# 当沙箱请求的 PVC/Docker named volume 不存在时，是否自动创建。
+# 设为 false 则引用不存在的卷会返回错误。
+volume_auto_create = true
+
+# 自动创建 Kubernetes PVC 时的默认存储大小（当调用方未指定时使用）。
+volume_default_size = "1Gi"
+
 [kubernetes]
 # Path to kubeconfig file. Leave as null to use in-cluster configuration
 # Replace with your path

server/opensandbox_server/examples/example.config.toml

@@ -57,6 +57,18 @@ mode = "dns"
 # Example: allowed_host_paths = ["/data/opensandbox", "/tmp/sandbox"]
 allowed_host_paths = []
 
+# Auto-create PVC (Kubernetes) or named volumes (Docker) when they don't exist.
+# Set to false to require volumes to be pre-created before sandbox creation.
+volume_auto_create = true
+
+# Default storage size for auto-created Kubernetes PVCs (when caller omits size).
+volume_default_size = "1Gi"
+
+# (Docker only) Remove auto-created named volumes when the sandbox is deleted.
+# Pre-existing volumes are never removed. Has no effect on Kubernetes PVCs,
+# whose lifecycle is managed by the StorageClass reclaim policy (Retain/Delete).
+volume_auto_delete = false
+
 [docker]
 # Docker-specific knobs
 # -----------------------------------------------------------------

server/opensandbox_server/examples/example.config.zh.toml

@@ -55,6 +55,18 @@ mode = "dns"
 # 示例：allowed_host_paths = ["/data/opensandbox", "/tmp/sandbox"]
 allowed_host_paths = []
 
+# 当沙箱请求的 PVC/Docker named volume 不存在时，是否自动创建。
+# 设为 false 则引用不存在的卷会返回错误。
+volume_auto_create = true
+
+# 自动创建 Kubernetes PVC 时的默认存储大小（当调用方未指定时使用）。
+volume_default_size = "1Gi"
+
+# （仅 Docker）删除沙箱时自动移除由服务器创建的 named volume。
+# 已存在的 volume 不会被移除。对 Kubernetes PVC 无影响，
+# 因为 PVC 的生命周期由 StorageClass 的回收策略（Retain/Delete）管理。
+volume_auto_delete = false
+
 [docker]
 # Docker-specific knobs
 # -----------------------------------------------------------------

server/opensandbox_server/services/constants.py

@@ -23,6 +23,7 @@
 SANDBOX_EMBEDDING_PROXY_PORT_LABEL = "opensandbox.io/embedding-proxy-port"  # maps container 44772 -> host port
 SANDBOX_HTTP_PORT_LABEL = "opensandbox.io/http-port"  # maps container 8080 -> host port
 SANDBOX_OSSFS_MOUNTS_LABEL = "opensandbox.io/ossfs-mounts"
+SANDBOX_MANAGED_VOLUMES_LABEL = "opensandbox.io/volume-managed-by"
 OPEN_SANDBOX_INGRESS_HEADER = "OpenSandbox-Ingress-To"
 OPEN_SANDBOX_EGRESS_AUTH_HEADER = "OPENSANDBOX-EGRESS-AUTH"
 SANDBOX_EGRESS_AUTH_TOKEN_METADATA_KEY = "opensandbox.io/egress-auth-token"
@@ -112,6 +113,7 @@ class SandboxErrorCodes:
     "SANDBOX_EMBEDDING_PROXY_PORT_LABEL",
     "SANDBOX_HTTP_PORT_LABEL",
     "SANDBOX_OSSFS_MOUNTS_LABEL",
+    "SANDBOX_MANAGED_VOLUMES_LABEL",
     "OPEN_SANDBOX_INGRESS_HEADER",
     "OPEN_SANDBOX_EGRESS_AUTH_HEADER",
     "SANDBOX_EGRESS_AUTH_TOKEN_METADATA_KEY",