# Secure Container Runtimes Compatible with OpenSandbox: gVisor, Kata, and Firecracker

> Discover secure container runtimes compatible with OpenSandbox: gVisor, Kata Containers, and Firecracker. Enhance your container security today.

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

---

**OpenSandbox supports hardened container runtimes including gVisor (runsc), Kata Containers (QEMU), and Firecracker (via Kata), configurable through the `[secure_runtime]` section in `~/.sandbox.toml` without requiring any SDK changes.**

OpenSandbox provides multi-layered sandbox isolation for executing untrusted code in the alibaba/OpenSandbox repository. While the default configuration uses standard runc containers, the platform implements a **Pluggable Secure Container Runtime** architecture (OSEP-0004) that enables administrators to deploy sandboxes inside gVisor, Kata Containers, or Firecracker micro-VMs for stronger security boundaries than traditional container isolation.

## Supported Secure Container Runtimes

The runtime selection is defined in [`oseps/0004-secure-container-runtime.md`](https://github.com/alibaba/OpenSandbox/blob/main/oseps/0004-secure-container-runtime.md) and implemented through a server-side resolver. The following secure container runtimes are validated and supported:

### gVisor (runsc)

gVisor provides a user-space kernel that intercepts and filters system calls. Configure `type = "gvisor"` to utilize the runsc runtime. For Docker deployments, set `docker_runtime = "runsc"`; for Kubernetes, use `k8s_runtime_class = "gvisor"`.

### Kata Containers (QEMU Backend)

Kata Containers creates lightweight VMs using QEMU as the hypervisor. Set `type = "kata"` with `docker_runtime = "kata-runtime"` for Docker mode or `k8s_runtime_class = "kata-qemu"` for Kubernetes clusters.

### Firecracker (via Kata)

Firecracker enables micro-VM isolation backed by AWS's Firecracker hypervisor, exposed through Kata's `kata-fc` RuntimeClass. **Important limitation**: Firecracker is supported **only in Kubernetes mode**. Configure `type = "firecracker"` and `k8s_runtime_class = "kata-fc"` while leaving `docker_runtime` empty.

## How Runtime Selection Works

The `SecureRuntimeResolver` reads the `[secure_runtime]` configuration from `~/.sandbox.toml` at server startup and injects the appropriate runtime parameters during sandbox creation.

### Startup Validation

The server validates that the configured runtime exists before accepting traffic. For Docker, it checks `docker_client.info()["Runtimes"]`; for Kubernetes, it verifies the RuntimeClass exists via `k8s_client.read_runtime_class`. If validation fails, the server aborts immediately with a clear error.

### Docker Mode Implementation

The `DockerSandboxService` in [`server/src/services/docker.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/docker.py) passes the resolved runtime string to `docker_client.containers.run(..., runtime=…)`.

### Kubernetes Mode Implementation

Both `BatchSandboxProvider` and `AgentSandboxProvider` set the `runtimeClassName` field on pod specifications when the resolver yields a non-empty value. This logic resides in [`server/src/services/k8s/batchsandbox_provider.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/k8s/batchsandbox_provider.py) and [`server/src/services/k8s/agent_sandbox_provider.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/k8s/agent_sandbox_provider.py).

## Configuration Examples

### Enabling gVisor in Docker Mode

```toml

# ~/.sandbox.toml

[runtime]
type = "docker"
execd_image = "opensandbox/execd:v1.0.5"

[secure_runtime]
type = "gvisor"
docker_runtime = "runsc"
k8s_runtime_class = "gvisor"

```

### Deploying with Kata Containers on Kubernetes

```toml
[runtime]
type = "kubernetes"
execd_image = "opensandbox/execd:v1.0.5"

[secure_runtime]
type = "kata"
docker_runtime = "kata-runtime"  # Ignored in K8s mode

k8s_runtime_class = "kata-qemu"

```

### Firecracker Micro-VMs (Kubernetes Only)

```toml
[secure_runtime]
type = "firecracker"
docker_runtime = ""               # Not supported in Docker mode

k8s_runtime_class = "kata-fc"

```

## SDK Integration

Because the runtime selection is **server-wide**, SDK users do not need to modify application code. The isolation upgrade is a pure infrastructure change handled entirely by the server configuration in [`server/src/config.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/config.py).

```python
from opensandbox import Sandbox

sandbox = await Sandbox.create(
    image="python:3.11",
    entrypoint=["python", "-c", "print('hello from secure runtime')"],
)
result = await sandbox.exec(["python", "-c", "print('running')"])
print(result.stdout)

```

The sandbox automatically executes under gVisor, Kata, or Firecracker depending on the server's `[secure_runtime]` configuration, with no runtime-specific parameters exposed in the public API.

## Summary

- OpenSandbox supports **gVisor**, **Kata Containers**, and **Firecracker** as hardened alternatives to runc.
- Configuration resides in `~/.sandbox.toml` under the `[secure_runtime]` section with fields `type`, `docker_runtime`, and `k8s_runtime_class`.
- The `SecureRuntimeResolver` validates runtimes at startup against Docker daemon capabilities or Kubernetes RuntimeClass definitions.
- Implementation files include [`server/src/services/docker.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/docker.py) and the Kubernetes providers in [`server/src/services/k8s/batchsandbox_provider.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/k8s/batchsandbox_provider.py) and [`server/src/services/k8s/agent_sandbox_provider.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/k8s/agent_sandbox_provider.py).
- SDK users require **zero code changes** to leverage secure container runtimes compatible with OpenSandbox.

## Frequently Asked Questions

### What is the difference between Kata Containers and Firecracker in OpenSandbox?

Kata Containers utilizes a QEMU backend for full VM isolation, while Firecracker provides a lightweight micro-VM optimized for fast startup and density. In OpenSandbox, Firecracker is exposed through Kata's `kata-fc` RuntimeClass but is restricted to Kubernetes mode only, whereas Kata supports both Docker and Kubernetes deployments.

### Do I need to modify my application code to use gVisor?

No. The runtime selection is server-wide and handled entirely by the infrastructure. The Python SDK and other client libraries remain unchanged; sandboxes automatically execute under the configured secure runtime without exposing runtime-specific parameters in the API.

### Where is the secure runtime configuration validated?

The server validates configuration at startup in the resolver logic defined in the OSEP-0004 specification. It checks Docker daemon capabilities via `docker_client.info()["Runtimes"]` or queries the Kubernetes API via `k8s_client.read_runtime_class` to ensure the specified RuntimeClass exists, failing fast if the runtime is unavailable.

### Can I use Firecracker with Docker mode in OpenSandbox?

No. Firecracker support is implemented exclusively for Kubernetes mode through the `kata-fc` RuntimeClass. When configuring `type = "firecracker"`, Docker deployments are not supported, and you must leave the `docker_runtime` field empty while setting `k8s_runtime_class = "kata-fc"`.