edera-agent

Run Agent Sandbox workloads on the Edera runtime, so each AI-agent sandbox gets its own kernel instead of sharing the host's.

Agent Sandbox gives you a declarative Sandbox API for stateful, singleton agent workloads. By itself, a Sandbox pod shares the host kernel — a container escape lands an attacker on the node. Edera changes the runtime underneath: with runtimeClassName: edera, each Sandbox boots inside an Edera zone, a lightweight VM with a dedicated guest kernel. Same Sandbox API, same workload — now contained to its own kernel.

This walkthrough takes you from an Edera-enabled cluster to a verified, isolated agent sandbox. It defaults to Amazon EKS, but the only EKS-specific step is storage (Step 2).

What you'll do

1. Install the Agent Sandbox controller.
2. (EKS) Make sure dynamic block storage works.
3. Deploy a minimal sandbox on Edera and prove it has its own kernel.
4. Deploy a realistic agent sandbox (a VS Code devcontainer on a persistent volume).

Prerequisites

• An Edera-enabled Kubernetes cluster. Edera Protect installs the zone runtime and the Edera-patched node kernel/containerd, and registers the edera RuntimeClass. Follow the Edera install docs to enable it. Confirm it is present:

  kubectl get runtimeclass edera
  # NAME    HANDLER   AGE
  # edera   edera     ...

• kubectl configured against that cluster.

• For the kustomize overlay (optional): kubectl v1.14+ has it built in.

Step 1 — Install the Agent Sandbox controller

Install the controller and the Sandbox CRD. Pin a version that serves the v1beta1 API (v0.5.0rc1 or newer). Older releases (v0.4.x) serve only v1alpha1, and the project has no conversion webhook, so the API version you install is the one you must use.

export AGENT_SANDBOX_VERSION="v0.5.0rc1"
kubectl apply -f "https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/manifest.yaml"

kubectl -n agent-sandbox-system rollout status deploy/agent-sandbox-controller
kubectl get crd sandboxes.agents.x-k8s.io \
  -o jsonpath='{range .spec.versions[*]}{.name}{" served="}{.served}{"\n"}{end}'
# v1beta1 served=true

Step 2 — (EKS only) Make dynamic block storage work

The realistic example in Step 4 uses a PersistentVolumeClaim. On a current EKS cluster the default gp2 StorageClass points at the in-tree kubernetes.io/aws-ebs provisioner, which has been removed from Kubernetes — so PVCs hang in Pending forever. Install the EBS CSI driver and make a gp3 StorageClass the default.

See docs/eks-setup.md for the full commands (IAM role + addon). The short version:

# Install the aws-ebs-csi-driver addon with an IAM role, then:
kubectl apply -f docs/gp3-storageclass.yaml
kubectl get storageclass   # gp3 should show "(default)"

Not on EKS? GKE, minikube, and kind ship a working default StorageClass, so you can skip this step.

Step 3 — Deploy a minimal sandbox on Edera

The only Edera-specific line is runtimeClassName: edera.

kubectl apply -f manifests/minimal-sandbox.yaml
kubectl wait --for=condition=Ready sandbox/edera-minimal --timeout=120s

Prove it has its own kernel

# Host node kernel (the Edera-patched host)
kubectl get node -o jsonpath='{.items[0].status.nodeInfo.kernelVersion}{"\n"}'
# e.g. 6.18.34-edera

# Guest kernel inside the sandbox — a different, separate kernel
kubectl exec edera-minimal -- uname -r
# e.g. 6.18.34   (no -edera suffix: this is the zone's own kernel)

The values differ because the sandbox is not sharing the host kernel. Process isolation follows from the same fact — the sandbox has its own PID 1:

kubectl exec edera-minimal -- ps -ef
# PID 1 is your container's command, not the host init. The host's
# processes are invisible.

Clean up:

kubectl delete -f manifests/minimal-sandbox.yaml

Step 4 — Deploy a realistic agent sandbox

This deploys a VS Code (code-server) devcontainer, built on the fly by envbuilder, with a persistent workspace on an EBS volume — a stand-in for a real coding-agent workload.

kubectl apply -f manifests/vscode-sandbox.yaml
kubectl get pvc      # workspaces-pvc-sandbox-example should be Bound
kubectl logs -f sandbox-example   # watch the devcontainer build

The first build takes several minutes (clone, build image, install code-server). Once up, verify isolation the same way:

kubectl get node -o jsonpath='{.items[0].status.nodeInfo.kernelVersion}{"\n"}'
kubectl exec sandbox-example -c devcontainer-main -- uname -r
kubectl exec sandbox-example -c devcontainer-main -- df -h /workspaces

Sizing matters on Edera. Each sandbox is a zone (a real VM), so size it like one. Edera maps a container's memory limit to the zone's maximum memory; without a limit, the zone falls back to Edera's default maximum (1024M) regardless of the pod's memory request — which OOM-kills the build. The upstream example sets a 2Gi request with no limit and a 4Gi ephemeral-storage cap, so it both OOMs and runs out of build disk. manifests/vscode-sandbox.yaml sets memory request and limit to 8Gi and ephemeral-storage to 20Gi. Size for the peak your workload needs, and see Edera memory ballooning for dynamic vs. static modes.

Using the kustomize overlay instead

If you prefer the upstream overlay pattern, overlays/edera patches the upstream vscode-sandbox base (pinned to the same release) with the Edera runtime class and the larger resource sizing:

kubectl apply -k overlays/edera

Accessing the sandbox

With VM-based runtimes (Edera, Kata) direct pod port-forward is not compatible. Use the Sandbox Router, a reverse proxy that routes by an X-Sandbox-ID header:

kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/agent-sandbox/v0.5.0rc1/clients/python/agentic-sandbox-client/sandbox-router/sandbox_router.yaml
kubectl port-forward svc/sandbox-router-svc 8080:8080
curl -H "X-Sandbox-ID: sandbox-example" -H "X-Sandbox-Port: 13337" http://localhost:8080

Why Edera (vs. gVisor / Kata)

	Shared host kernel?	Dedicated kernel	Needs bare-metal / nested virt
runc (default)	yes	no	no
gVisor	no (userspace kernel)	userspace re-implementation	no
Kata Containers	no	yes (per-VM)	yes
Edera	no	yes (per-zone)	no

Edera gives you Kata-style per-sandbox kernel isolation without requiring bare-metal nodes or nested-virtualization-enabled instances. This walkthrough was verified on a stock t3.2xlarge EKS node.

Troubleshooting

• no matches for kind "Sandbox" in version "agents.x-k8s.io/v1beta1" — you installed a v0.4.x controller (v1alpha1 only). Reinstall v0.5.0rc1+ (Step 1).
• PVC stuck Pending on EKS — the in-tree EBS provisioner is gone; install the EBS CSI driver (Step 2 / docs/eks-setup.md).
• Sandbox OOMKilled during build — set a memory limit (Edera maps it to the zone's max; without it the zone caps at 1024M). See the sizing note in Step 4.
• no space left on device during build — bump ephemeral-storage.
• kubectl exec fails with execvpe failed — the workload's image has no shell yet (e.g. envbuilder mid-build). Wait for the build to finish, or use the minimal-sandbox.yaml for quick checks.

Repository layout

manifests/
  minimal-sandbox.yaml     # storage-free quick verify (alpine)
  vscode-sandbox.yaml      # realistic devcontainer, sized for Edera zones
overlays/edera/            # kustomize overlay over the upstream base
docs/
  eks-setup.md             # EBS CSI driver + storage class setup
  gp3-storageclass.yaml