Hardware Isolation with gVisor, Kata, and Firecracker

When OpenSandbox executes code generated by AI models, the default runc container runtime relies on Linux cgroups and namespaces for isolation — sufficient for trusted workloads but not for arbitrary untrusted code. Secure container runtimes add a hardware-level isolation boundary between the sandbox workload and the host kernel: gVisor intercepts syscalls in user space, while Kata Containers and Firecracker run each sandbox in its own microVM. This guide explains the available runtimes, how to configure them at the server level, and how to verify which runtime is active.

Runtime Comparison

Runtime	Isolation Mechanism	Startup Overhead	Memory Overhead	Best For
runc (default)	Process-level cgroups	~0ms	Minimal	Trusted workloads, local development
gVisor	User-space kernel (syscall interception)	~10–50ms	~50 MB	General workloads with low overhead
Kata (QEMU)	Full VM with QEMU hypervisor	~500ms	~20–50 MB	Maximum compatibility and isolation
Kata (Firecracker)	MicroVM with Firecracker hypervisor	~125ms	~5 MB	High density, minimal footprint
Kata (CLH)	Cloud Hypervisor	~200ms	~10–20 MB	Balanced performance and isolation

Secure runtimes introduce startup latency and per-sandbox memory overhead. For high-throughput use cases where many sandboxes are created concurrently, benchmark startup times against your SLA before choosing Kata (QEMU), which adds ~500 ms per sandbox. Kata (Firecracker) or gVisor are better fits for high-density deployments. Consider pre-warmed Pool CRDs to absorb startup overhead when using Kata.

Key Design Principle

Server-level configuration — the secure runtime is configured once by an administrator in ~/.sandbox.toml. All sandboxes on that server transparently use the configured runtime. SDK users and API callers require no code changes. The server injects the runtime at sandbox creation time: runtime in HostConfig for Docker mode, or runtimeClassName in the Pod spec for Kubernetes mode.

Supported Runtime Types

OpenSandbox accepts the following values for [secure_runtime].type:

Value	Runtime
`"gvisor"`	Google gVisor with `runsc`
`"kata"`	Kata Containers with QEMU hypervisor
`"firecracker"`	Kata Containers with Firecracker hypervisor
`""` (empty)	Standard `runc` — no secure runtime

Server Configuration

Secure runtimes are configured through the [secure_runtime] section of ~/.sandbox.toml. The server validates the configured runtime at startup and refuses to start if the runtime is unavailable.

[runtime]
type = "docker"  # or "kubernetes"
execd_image = "opensandbox/execd:latest"

# Secure container runtime configuration.
# When set, ALL sandboxes on this server use the specified runtime.
[secure_runtime]
# Runtime type: "", "gvisor", "kata", "firecracker"
type = ""

# Docker mode: OCI runtime name registered in /etc/docker/daemon.json
# e.g. "runsc" for gVisor, "kata-runtime" for Kata
docker_runtime = "runsc"

# Kubernetes mode: RuntimeClass name to set on sandbox Pod specs
# e.g. "gvisor", "kata-qemu", "kata-fc"
k8s_runtime_class = "gvisor"

Docker Mode

gVisor
Kata Containers

gVisor on Docker

Install the runsc OCI runtime and register it with the Docker daemon.

# Install runsc (Ubuntu/Debian)
curl -fsSL https://gvisor.dev/archive.key | sudo gpg --dearmor -o /usr/share/keyrings/gvisor-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/gvisor-archive-keyring.gpg] https://storage.googleapis.com/gvisor/releases release main" | \
  sudo tee /etc/apt/sources.list.d/gvisor.list
sudo apt-get update && sudo apt-get install -y runsc

sudo runsc install
sudo systemctl restart docker

Or manually:

{
  "runtimes": {
    "runsc": {
      "path": "/usr/bin/runsc",
      "runtimeArgs": [
        "--platform=systrap",
        "--network=host"
      ]
    }
  }
}

Configure OpenSandbox server:

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

Kata Containers on Docker

Kata Containers requires hardware virtualization (VT-x on Intel or AMD-V on AMD). Verify KVM is available before proceeding:

lscpu | grep Virtualization
lsmod | grep kvm

Download and install Kata static binaries:

KATA_VERSION="3.27.0"
wget https://github.com/kata-containers/kata-containers/releases/download/${KATA_VERSION}/kata-static-${KATA_VERSION}-amd64.tar.zst
zstd -d kata-static-${KATA_VERSION}-amd64.tar.zst
tar -xvf kata-static-${KATA_VERSION}-amd64.tar -C /
sudo ln -sf /opt/kata/bin/kata-runtime /usr/local/bin/kata-runtime

{
  "default-runtime": "runc",
  "runtimes": {
    "kata": {
      "runtimeType": "io.containerd.kata.v2"
    }
  }
}

sudo systemctl restart docker

Configure OpenSandbox server:

[secure_runtime]
type = "kata"
docker_runtime = "kata"

Kubernetes Mode

gVisor
Kata Containers

gVisor on Kubernetes

For Kubernetes with containerd, install both runsc and containerd-shim-runsc-v1 on every node:

sudo apt-get install -y runsc containerd-shim-runsc-v1

Configure containerd by adding the gVisor runtime to /etc/containerd/config.toml:

[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runsc]
  runtime_type = "io.containerd.runsc.v1"
  [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runsc.options]
    TypeUrl = "io.containerd.runsc.v1.options"
    ConfigPath = "/etc/containerd/runsc.toml"

sudo systemctl restart containerd

Create the RuntimeClass:

apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
  name: gvisor
handler: runsc
scheduling:
  nodeSelector:
    kubernetes.io/arch: amd64

kubectl apply -f gvisor-runtimeclass.yaml

Configure OpenSandbox server:

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

Kata Containers on Kubernetes

Install Kata using the official kata-deploy Helm chart, which configures containerd via a DaemonSet on all nodes automatically:

helm install kata-deploy \
  "oci://ghcr.io/kata-containers/kata-deploy-charts/kata-deploy" \
  --version "3.27.0" \
  --namespace kube-system \
  --create-namespace

kubectl wait --for=condition=ready pod \
  -l name=kata-deploy -n kube-system --timeout=300s

Verify the RuntimeClasses created by kata-deploy:

kubectl get runtimeclass
# NAME         HANDLER     AGE
# kata         kata-qemu   10m
# kata-qemu    kata-qemu   10m
# kata-clh     kata-clh    10m
# kata-fc      kata-fc     10m

Configure OpenSandbox server (QEMU example):

[secure_runtime]
type = "kata"
k8s_runtime_class = "kata-qemu"

For Kata + Firecracker:

[secure_runtime]
type = "firecracker"
k8s_runtime_class = "kata-fc"

Verifying the Active Runtime

After configuring a secure runtime, verify it is active without making any SDK code changes. Docker mode — inspect the container’s runtime field:

docker ps --format "{{.ID}}\t{{.Image}}\t{{.Names}}"
docker inspect <container_id> | grep -A2 Runtime
# Expected output for gVisor:
# "Runtime": "runsc",

Kubernetes mode — inspect the pod’s runtimeClassName:

kubectl get pod <pod-name> -o jsonpath='{.spec.runtimeClassName}'
# Expected output for gVisor:
# gvisor

Server startup log — the server logs the result of runtime validation on startup:

INFO     Validating secure runtime for Docker backend
INFO     Docker OCI runtime 'runsc' is available: {...}
INFO     Application startup complete.

If the runtime is not found, the server refuses to start:

ERROR    Configured Docker runtime 'runsc' is not available.
         Available runtimes: runc.
         Please install and configure it in /etc/docker/daemon.json.

Egress Sidecar Compatibility

gVisor does not support the egress sidecar. The egress sidecar uses a REDIRECT rule in the iptables nat table to intercept DNS queries. gVisor’s netstack implements the filter and mangle tables but not the nat table, so the sidecar cannot start under gVisor. You will see errors such as:

iptables: Failed to initialize nft: Protocol not supported

If you need both syscall isolation and FQDN egress control, use kata-qemu instead — it provides a full Linux kernel per pod and supports the egress sidecar unchanged. The OpenSandbox server returns HTTP 400 when secure_runtime.type = "gvisor" and network_policy are used together.

Compatibility Matrix

Feature	runc	gVisor	Kata (QEMU)	Kata (CLH)	Kata (FC)
Syscall compatibility	Full	Partial	Full	Full	Limited
GPU support	Yes	No	Yes	Yes	No
Privileged mode	Yes	No	Yes	Yes	No
Systemd	Yes	No	Yes	Yes	No
iptables `nat` table (egress sidecar)	Yes	No	Yes	Yes	Yes
Docker volume	Yes	Yes	Yes	Yes	Yes
IPv6	Yes	Yes	Yes	Yes	Yes

Get Started

SDKs

CLI & MCP

Guides

Deployment

Architecture

Hardware Isolation with gVisor, Kata, and Firecracker

Runtime Comparison

Key Design Principle

Supported Runtime Types

Server Configuration

Docker Mode

gVisor on Docker

Kata Containers on Docker

Kubernetes Mode

gVisor on Kubernetes

Kata Containers on Kubernetes

Verifying the Active Runtime

Egress Sidecar Compatibility

Compatibility Matrix

Build docs developers (and LLMs) love

Get Started

SDKs

CLI & MCP

Guides

Deployment

Architecture

Documentation Index

​Runtime Comparison

​Key Design Principle

​Supported Runtime Types

​Server Configuration

​Docker Mode

​gVisor on Docker

​Kata Containers on Docker

​Kubernetes Mode

​gVisor on Kubernetes

​Kata Containers on Kubernetes

​Verifying the Active Runtime

​Egress Sidecar Compatibility

​Compatibility Matrix

Build docs developers (and LLMs) love

Runtime Comparison

Key Design Principle

Supported Runtime Types

Server Configuration

Docker Mode

gVisor on Docker

Kata Containers on Docker

Kubernetes Mode

gVisor on Kubernetes

Kata Containers on Kubernetes

Verifying the Active Runtime

Egress Sidecar Compatibility

Compatibility Matrix