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

> Learn how to integrate OpenSandbox with Kubernetes using the agent-sandbox component. Configure runtime, initialize client, and manage Sandbox resources in your cluster.

- Repository: [Alibaba/OpenSandbox](https://github.com/alibaba/OpenSandbox)
- Tags: how-to-guide
- Published: 2026-03-08

---

**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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/config.py) at lines 267-282, controls template loading, shutdown behavior, and ingress exposure.

```yaml

# 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`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/k8s/client.py). This client handles authentication and exposes the CoreV1, CustomObjects, and Node APIs required by the provider.

```python
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`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/k8s/provider_factory.py) (lines 106-124) to construct an `AgentSandboxProvider`:

```python
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`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/k8s/agent_sandbox_provider.py) implements the `WorkloadProvider` interface defined in [`server/src/services/k8s/workload_provider.py`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/agent_sandbox_template.py))

```python
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:

```python
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:

```python
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:

```python
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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/config.py) | Pydantic models for `AgentSandboxRuntimeConfig` and application settings (lines 267-282). |
| [`server/src/services/k8s/provider_factory.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/k8s/provider_factory.py) | Factory that instantiates `AgentSandboxProvider` with runtime-specific arguments (lines 106-124). |
| [`server/src/services/k8s/client.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/k8s/client.py) | Kubernetes client wrapper for CoreV1, CustomObjects, and Node APIs. |
| [`server/src/services/k8s/egress_helper.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/k8s/egress_helper.py) | Helper for injecting egress sidecars and network policies. |
| [`server/src/services/k8s/workload_provider.py`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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.