How to Integrate OpenSandbox with Kubernetes Using the Agent-Sandbox Component

To integrate OpenSandbox with Kubernetes using the agent-sandbox component, configure the AgentSandboxRuntimeConfig, initialize a K8sClient, use the provider factory to instantiate an AgentSandboxProvider, and invoke its lifecycle methods to manage Sandbox custom resources inside your cluster.

OpenSandbox is an open-source sandbox runtime developed by Alibaba that executes user code inside Kubernetes using the agent-sandbox Custom Resource Definition (CRD). This integration allows you to leverage native Kubernetes workload management while maintaining strict isolation boundaries. The AgentSandboxProvider class in server/src/services/k8s/agent_sandbox_provider.py serves as the primary bridge between OpenSandbox's API and the Kubernetes control plane.

Configure the Agent-Sandbox Runtime

Before creating workloads, define the AgentSandboxRuntimeConfig in your application configuration. This model, located in server/src/config.py at lines 267-282, controls template loading, shutdown behavior, and ingress exposure.

# config.yaml

runtime:
  type: kubernetes
  execd_image: "registry.cn-hangzhou.aliyuncs.com/opensandbox/execd:latest"

agent_sandbox:
  template_file: "configs/agent_sandbox_template.yaml"
  shutdown_policy: "Delete"
  ingress_enabled: true

The shutdown_policy determines whether the Sandbox CR is retained or deleted when the workload stops, while ingress_enabled controls whether the provider automatically creates an Ingress resource for external access.

Initialize the Kubernetes Client and Provider

First, instantiate the K8sClient wrapper located in server/src/services/k8s/client.py. This client handles authentication and exposes the CoreV1, CustomObjects, and Node APIs required by the provider.

from src.config import AppConfig
from src.services.k8s.client import K8sClient

app_cfg = AppConfig.parse_file("config.yaml")
k8s_client = K8sClient(app_cfg.kubernetes)

Next, use the provider factory in server/src/services/k8s/provider_factory.py (lines 106-124) to construct an AgentSandboxProvider:

from src.services.k8s.provider_factory import create_workload_provider

provider = create_workload_provider(
    provider_type="agent-sandbox",
    k8s_client=k8s_client,
    k8s_config=app_cfg.kubernetes,
    agent_sandbox_config=app_cfg.agent_sandbox,
    ingress_config=app_cfg.ingress,
    app_config=app_cfg,
)

The factory automatically injects the template path, shutdown policy, and secure runtime configuration into the provider instance.

Manage Sandbox Workloads

The AgentSandboxProvider in server/src/services/k8s/agent_sandbox_provider.py implements the WorkloadProvider interface defined in server/src/services/k8s/workload_provider.py. It translates high-level sandbox requests into Kubernetes Sandbox custom resources.

Creating a Workload

Call create_workload (lines 159-204) to generate a Sandbox CR. The provider automatically:

• Sanitizes the sandbox ID to a DNS-1035-compatible label using _to_dns1035_label (lines 56-74)
• Builds a pod spec with an execd init container, user container, and optional egress sidecar
• Injects a RuntimeClass if a secure runtime is configured
• Applies the custom template loaded by AgentSandboxTemplateManager (lines 19-31 in agent_sandbox_template.py)

from datetime import datetime, timedelta
from src.api.schema import ImageSpec

result = provider.create_workload(
    sandbox_id="demo-01",
    namespace="opensandbox",
    image_spec=ImageSpec(uri="python:3.11-slim"),
    entrypoint=["python", "-c", "print('Hello')"],
    env={"KEY": "value"},
    resource_limits={"cpu": "500m", "memory": "256Mi"},
    labels={"app": "demo"},
    expires_at=datetime.utcnow() + timedelta(hours=2),
    execd_image="registry.cn-hangzhou.aliyuncs.com/opensandbox/execd:latest",
    network_policy=None,
    egress_image=None,
)

Querying Status and Endpoints

Retrieve workload state using get_status (lines 500-545), which extracts the Ready condition from the Sandbox CR or falls back to pod state inference:

workload = provider.get_workload("demo-01", "opensandbox")
status = provider.get_status(workload)

Resolve network endpoints via get_endpoint_info (lines 998-1022). This method prefers Ingress endpoints when ingress_enabled is true; otherwise it returns the Pod IP:

endpoint = provider.get_endpoint_info(workload, port=8080, sandbox_id="demo-01")

Deleting Workloads

Remove the sandbox with delete_workload (lines 335-347), which respects the shutdown_policy defined in the runtime configuration:

provider.delete_workload("demo-01", "opensandbox")

Advanced Integration Features

Secure Runtime Integration

To use gVisor, Kata Containers, or Firecracker, configure the secure_runtime section in your application config. The SecureRuntimeResolver populates self.runtime_class, which AgentSandboxProvider._build_pod_spec injects as runtimeClassName into the pod spec (lines 58-62 in server/src/services/k8s/agent_sandbox_provider.py).

Network Policies and Egress Sidecars

For restricted network access, pass a NetworkPolicy object and an egress_image to create_workload. The provider invokes apply_egress_to_spec (referenced in lines 62-68) to inject the sidecar container and security context, as implemented in server/src/services/k8s/egress_helper.py.

Custom CR Templates

Supply a custom YAML template via agent_sandbox.template_file. The AgentSandboxTemplateManager (lines 19-31 in server/src/services/k8s/agent_sandbox_template.py) loads this file and merges runtime values, allowing you to customize labels, annotations, or affinity rules without modifying provider code.

Informer Cache for Fast Reads

By default, the provider uses a Kubernetes Informer to cache Sandbox CR reads, reducing API server load. The informer is created lazily in _get_informer (lines 777-794 in server/src/services/k8s/agent_sandbox_provider.py). Disable this by passing enable_informer=False to the factory if you require direct API server queries.

Key Source Files

File	Purpose
server/src/services/k8s/agent_sandbox_provider.py	Core provider implementing workload lifecycle, pod spec construction, DNS-1035 naming, and endpoint resolution (lines 77-200, 224-332, 350-500).
server/src/services/k8s/agent_sandbox_template.py	Template loader that merges user-supplied YAML with runtime parameters (lines 19-31).
server/src/config.py	Pydantic models for AgentSandboxRuntimeConfig and application settings (lines 267-282).
server/src/services/k8s/provider_factory.py	Factory that instantiates AgentSandboxProvider with runtime-specific arguments (lines 106-124).
server/src/services/k8s/client.py	Kubernetes client wrapper for CoreV1, CustomObjects, and Node APIs.
server/src/services/k8s/egress_helper.py	Helper for injecting egress sidecars and network policies.
server/src/services/k8s/workload_provider.py	Abstract base class defining the provider interface.

Summary

• Configure the integration by defining AgentSandboxRuntimeConfig in server/src/config.py, specifying the template file, shutdown policy, and ingress settings.
• Initialize the K8sClient and use create_workload_provider from server/src/services/k8s/provider_factory.py to obtain an AgentSandboxProvider.
• Manage sandbox lifecycles using create_workload, get_status, get_endpoint_info, and delete_workload, which operate on Sandbox custom resources in the Kubernetes API.
• Secure your workloads by configuring SecureRuntimeResolver for gVisor or Kata Containers, and restrict network access using the egress helper and network policies.
• Customize deployments by supplying a custom CR template via AgentSandboxTemplateManager to modify pod specs without changing provider code.

Frequently Asked Questions

How does the AgentSandboxProvider generate Kubernetes resource names?

The provider sanitizes sandbox IDs to comply with DNS-1035 standards using the _to_dns1035_label method in server/src/services/k8s/agent_sandbox_provider.py (lines 56-74). This ensures resource names are valid Kubernetes identifiers containing only lowercase alphanumeric characters and hyphens.

Can I use gVisor or Kata Containers with OpenSandbox?

Yes. Configure the secure_runtime section in your application config to specify a k8s_runtime_class. The SecureRuntimeResolver passes this value to AgentSandboxProvider._build_pod_spec, which injects runtimeClassName into the pod spec (lines 58-62 in server/src/services/k8s/agent_sandbox_provider.py), enabling gVisor, Kata, or Firecracker isolation.

What is the difference between the Delete and Retain shutdown policies?

The shutdown_policy in AgentSandboxRuntimeConfig controls CR lifecycle after sandbox termination. When set to "Delete", the provider removes the Sandbox CR immediately via delete_namespaced_custom_object (lines 335-347 in server/src/services/k8s/agent_sandbox_provider.py). When set to "Retain", the CR persists for debugging or audit purposes.

How do I expose sandbox services externally?

Set ingress_enabled: true in AgentSandboxRuntimeConfig. When creating a workload, the provider checks this flag and calls get_endpoint_info (lines 998-1022 in server/src/services/k8s/agent_sandbox_provider.py), which returns an Ingress endpoint instead of a cluster-internal Pod IP, allowing external HTTP/HTTPS access to the sandbox.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}