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

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 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 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 and server/src/services/k8s/agent_sandbox_provider.py.

Configuration Examples

Enabling gVisor in Docker Mode

# ~/.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

[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)

[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.

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 and the Kubernetes providers in server/src/services/k8s/batchsandbox_provider.py and 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".

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