feat(server): add sandbox k8s runtime

Author: Generalwin

server/README.md

@@ -58,6 +58,12 @@ The server uses a TOML configuration file to select and configure the underlying
 ```bash
 cp example.config.toml ~/.sandbox.toml
 ```
+**[optional] Create K8S configuration file：
+The K8S version of the Sandbox Operator needs to be deployed in the cluster, refer to the Kubernetes directory.
+```bash
+cp example.config.k8s.toml ~/.sandbox.toml
+cp example.batchsandbox-template.yaml ~/batchsandbox-template.yaml
+```
 
 **[optional] Edit `~/.sandbox.toml`** for your environment:
 

server/README_zh.md

@@ -61,6 +61,12 @@ uv sync
 ```bash
 cp example.config.zh.toml ~/.sandbox.toml
 ```
+**[可选] 复制K8S版本配置文件：
+需要在集群中部署 K8S版本的Sandbox Operator，参考Kubernetes目录。
+```bash
+cp example.config.k8s.zh.toml ~/.sandbox.toml
+cp example.batchsandbox-template.yaml ~/batchsandbox-template.yaml
+```
 
 **[可选] 编辑 `~/.sandbox.toml`** 适配您的环境：
 

server/example.batchsandbox-template.yaml

@@ -0,0 +1,22 @@
+# Example BatchSandbox CR template for OpenSandbox Kubernetes runtime
+# This is a complete BatchSandbox CR template that will be merged with runtime values
+#
+# Usage in config.toml:
+#   [kubernetes]
+#   batchsandbox_template_file = "/path/to/this/file.yaml"
+
+# Metadata template (will be merged with runtime-generated metadata)
+metadata:
+  annotations:
+    template-source: "batchsandbox-template.yaml"
+    managed-by: "opensandbox"
+
+# Spec template
+spec:
+  replicas: 1
+  # Pod template specification
+  template:
+    spec:
+      restartPolicy: Never
+      tolerations:
+        - operator: "Exists"

server/example.config.k8s.toml

@@ -0,0 +1,49 @@
+# Copyright 2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Example Kubernetes Runtime Configuration for OpenSandbox Server
+#
+# This configuration file demonstrates how to configure the OpenSandbox server
+# to use Kubernetes as the sandbox runtime.
+#
+# Usage:
+#   1. Copy this file to ~/.sandbox.toml (or set SANDBOX_CONFIG_PATH environment variable)
+#   2. Update the configuration values according to your environment
+#   3. Start the server: uvicorn src.main:app --host 0.0.0.0 --port 8080
+
+[server]
+host = "0.0.0.0"
+port = 8080
+log_level = "INFO"
+# api_key = "your-secret-api-key"  # Optional: Uncomment to enable API key authentication
+
+[runtime]
+type = "kubernetes"
+execd_image = "opensandbox/execd:latest"
+
+[kubernetes]
+# Path to kubeconfig file. Leave as null to use in-cluster configuration
+# Replace with your path
+kubeconfig_path = "~/.kube/config"
+
+# Namespace for sandbox workloads
+namespace = "opensandbox"
+
+# Workload provider type: available providers are registered in the provider factory
+# If not specified, uses the first registered provider (typically "batchsandbox")
+workload_provider = "batchsandbox"
+
+# Path to the BatchSandbox template file
+# Replace with your path
+batchsandbox_template_file = "~/batchsandbox-template.yaml"

server/example.config.k8s.zh.toml

@@ -0,0 +1,49 @@
+# Copyright 2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Example Kubernetes Runtime Configuration for OpenSandbox Server
+#
+# This configuration file demonstrates how to configure the OpenSandbox server
+# to use Kubernetes as the sandbox runtime.
+#
+# Usage:
+#   1. Copy this file to ~/.sandbox.toml (or set SANDBOX_CONFIG_PATH environment variable)
+#   2. Update the configuration values according to your environment
+#   3. Start the server: uvicorn src.main:app --host 0.0.0.0 --port 8080
+
+[server]
+host = "0.0.0.0"
+port = 8080
+log_level = "INFO"
+# api_key = "your-secret-api-key"  # Optional: Uncomment to enable API key authentication
+
+[runtime]
+type = "kubernetes"
+execd_image = "sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/execd:latest"
+
+[kubernetes]
+# Path to kubeconfig file. Leave as null to use in-cluster configuration
+# Replace with your path
+kubeconfig_path = "~/.kube/config"
+
+# Namespace for sandbox workloads
+namespace = "opensandbox"
+
+# Workload provider type: available providers are registered in the provider factory
+# If not specified, uses the first registered provider (typically "batchsandbox")
+workload_provider = "batchsandbox"
+
+# Path to the BatchSandbox template file
+# Replace with your path
+batchsandbox_template_file = "~/batchsandbox-template.yaml"

server/example.config.toml

@@ -48,16 +48,3 @@ apparmor_profile = ""
 pids_limit = 512
 # Seccomp profile: empty string uses Docker default; set to an absolute path for a custom profile
 seccomp_profile = ""
-
-
-# -----------------------------------------------------------------
-# Kubernetes runtime example (uncomment when runtime.type = "kubernetes")
-# Exactly one runtime.* block should remain active at any time.
-#
-# [kubernetes]
-# # Path to kubeconfig for authenticating with the target cluster
-# kubeconfig_path = "~/.kube/config"
-# # Namespace that will host sandbox pods
-# namespace = "sandbox-system"
-# # Service account bound to sandbox workloads
-# service_account = "sandbox-runner"

server/example.config.zh.toml

@@ -48,16 +48,3 @@ apparmor_profile = ""
 pids_limit = 512
 # Seccomp profile: empty string uses Docker default; set to an absolute path for a custom profile
 seccomp_profile = ""
-
-
-# -----------------------------------------------------------------
-# Kubernetes runtime example (uncomment when runtime.type = "kubernetes")
-# Exactly one runtime.* block should remain active at any time.
-#
-# [kubernetes]
-# # Path to kubeconfig for authenticating with the target cluster
-# kubeconfig_path = "~/.kube/config"
-# # Namespace that will host sandbox pods
-# namespace = "sandbox-system"
-# # Service account bound to sandbox workloads
-# service_account = "sandbox-runner"

server/pyproject.toml

@@ -25,6 +25,7 @@ dependencies = [
     "docker",
     "fastapi",
     "httpx",
+    "kubernetes",
     "pydantic",
     "pydantic-settings",
     "pyyaml",

server/src/config.py

@@ -104,6 +104,14 @@ class KubernetesRuntimeConfig(BaseModel):
         default=None,
         description="Service account bound to sandbox workloads.",
     )
+    workload_provider: Optional[str] = Field(
+        default=None,
+        description="Workload provider type. If not specified, uses the first registered provider.",
+    )
+    batchsandbox_template_file: Optional[str] = Field(
+        default=None,
+        description="Path to BatchSandbox CR YAML template file. Used when workload_provider is 'batchsandbox'.",
+    )
 
 
 class RuntimeConfig(BaseModel):

server/src/services/constants.py

@@ -20,10 +20,10 @@
 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
 
-
 class SandboxErrorCodes:
     """Canonical error codes for sandbox service operations."""
 
+    # Docker runtime error codes
     DOCKER_INITIALIZATION_ERROR = "DOCKER::INITIALIZATION_ERROR"
     CONTAINER_QUERY_FAILED = "DOCKER::SANDBOX_QUERY_FAILED"
     SANDBOX_NOT_FOUND = "DOCKER::SANDBOX_NOT_FOUND"
@@ -41,8 +41,20 @@ class SandboxErrorCodes:
     BOOTSTRAP_INSTALL_FAILED = "DOCKER::SANDBOX_BOOTSTRAP_INSTALL_FAILED"
     INVALID_ENTRYPOINT = "DOCKER::INVALID_ENTRYPOINT"
     INVALID_PORT = "DOCKER::INVALID_PORT"
-    INVALID_METADATA_LABEL = "SANDBOX::INVALID_METADATA_LABEL"
     NETWORK_MODE_ENDPOINT_UNAVAILABLE = "DOCKER::NETWORK_MODE_ENDPOINT_UNAVAILABLE"
+    
+    # Kubernetes runtime error codes
+    K8S_INITIALIZATION_ERROR = "KUBERNETES::INITIALIZATION_ERROR"
+    K8S_SANDBOX_NOT_FOUND = "KUBERNETES::SANDBOX_NOT_FOUND"
+    K8S_POD_FAILED = "KUBERNETES::POD_FAILED"
+    K8S_POD_READY_TIMEOUT = "KUBERNETES::POD_READY_TIMEOUT"
+    K8S_API_ERROR = "KUBERNETES::API_ERROR"
+    K8S_POD_IP_NOT_AVAILABLE = "KUBERNETES::POD_IP_NOT_AVAILABLE"
+    
+    # Common error codes
+    UNKNOWN_ERROR = "SANDBOX::UNKNOWN_ERROR"
+    API_NOT_SUPPORTED = "SANDBOX::API_NOT_SUPPORTED"
+    INVALID_METADATA_LABEL = "SANDBOX::INVALID_METADATA_LABEL"
 
 
 __all__ = [