agent-sandbox on k7d

kubernetes-sigs/agent-sandbox runs isolated, stateful agent workloads as Sandbox objects, with warm pools (SandboxWarmPool) and claims (SandboxClaim) on top. It picks its isolation through the pod’s runtimeClassName, and k7d plugs in there with no upstream change: every Sandbox pod on k7 or k7-fc is its own k7d microVM — the native in-process VMM, or stock Firecracker under the jailer (Backends).

Tested with agent-sandbox v1.0.5 (every image and manifest digest-pinned in utils/agent-sandbox/pins.env) on k7d main after 0.9.0 — the integration, and the kubectl port-forward support it needs, landed after the 0.9.0 tarball.

Node prerequisites#

1. k3s, pinned: sudo utils/install-k3s.sh (k3s v1.36.5+k3s1), or your own cluster.
2. k7d, the shim and RuntimeClasses k7 and k7-fc: sudo ./packaging/install.sh --with-k3s from the release tarball (Installation). On a K7 cluster, k7 install --backend k7d,k7d-fc does the same.
3. agent-sandbox, pinned and sha256-checked: utils/agent-sandbox/install.sh installs the controller, CRDs, extensions and the Go sandbox-router; utils/agent-sandbox/uninstall.sh removes all of it.

Then run the demo:

KUBECONFIG=/etc/rancher/k3s/k3s.yaml examples/agent-sandbox/demo.sh

It creates a k7-fc warm pool and a claim, drives the upstream Python SDK through the router, and runs docker run hello-world inside a k7 sandbox.

Examples#

All in examples/agent-sandbox/. Every image is digest-pinned, and set CPU and memory limits — k7d sizes the VM from the container limits.

A bare Sandbox is an ordinary pod template with the RuntimeClass set:

apiVersion: agents.x-k8s.io/v1beta1kind: Sandboxmetadata:  name: python-k7spec:  service: true  podTemplate:    spec:      runtimeClassName: k7            # or k7-fc      automountServiceAccountToken: false      containers:      - name: python-runtime        image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0@sha256:…        ports: [{containerPort: 8888, name: http}]        readinessProbe: {httpGet: {path: /, port: 8888}, periodSeconds: 5, timeoutSeconds: 5}        resources:          limits: {cpu: "1", memory: 1Gi}          requests: {cpu: 250m, memory: 1Gi}

kubectl apply -f examples/agent-sandbox/sandbox-k7.yamlkubectl wait sandbox/python-k7 --for=condition=Ready --timeout=180s

A warm pool is a SandboxTemplate plus a SandboxWarmPool with replicas; a SandboxClaim adopts a booted VM from the pool without a restart (restartCount 0). networkPolicyManagement: Managed on the template gives the upstream default policy — ingress only from the sandbox-router, egress to public IPs only — and it is enforced on the pod IP of a k7d VM exactly as it would be for runc.

Docker-in-VM is two pod annotations on the template’s podTemplate; the workload keeps capabilities: {drop: [ALL]} and dockerd runs in the guest outside the container (Security — Docker as a guest service):

metadata:  annotations:    k7d.katakate.org/docker: "true"        # dockerd in the guest, socket at /var/run/docker.sock    k7d.katakate.org/docker-disk: "20Gi"   # ext4 graph disk, so overlay2 is not on tmpfs

Support matrix#

From crates/k7d/tests/test_agent_sandbox.rs, single node, k3s v1.36.5+k3s1 (flannel, kube-router NetworkPolicy), 2026-10-07.

V4 (sandboxd + Go SDK) is not run: v1.0.5 publishes no sandboxd image. Warm-forking a Sandbox (V12) is the next increment; today a fork of a pod VM goes through the daemon API (fork_vm with pod_netns) or k7 fork on a K7 cluster.

Timings#

Intel Core Ultra 7 265 (20 threads), 62 GB, NVMe, Hetzner, single node, 2026-10-07, images already pulled:

A warm claim adopts a running pool VM, so it costs the same as runc. With a readiness probe, cold start moves in steps of the probe period: k7-fc boots in about 1 s but misses the first probe.

Upstream TestRuntimeClassBurstRecovery with SANDBOX_POOL_SIZES=10,20,40 (two claims per pool slot, in batches):

Known gaps#

• Kubelet volume updates do not reach the guest. ConfigMap, Secret, downwardAPI and projected volumes are packed into one read-only erofs image when the pod is created. kubelet rotates projected tokens and updates ConfigMaps on the host; the guest keeps the first copy. Use automountServiceAccountToken: false (the examples do) or tokens whose lifetime covers the sandbox. The default kube-api-access token stays valid for a year on clusters with --service-account-extend-token-expiration (the default), but it is never refreshed.
• k7-fc has no virtiofs. hostPath and local-path PVCs fail Create naming the backend. Use k7 for volumeClaimTemplates on local-path storage.

Related pages#

• RuntimeClass k7 — how the runtime is registered, annotation reference
• Feature matrix — everything else the host RuntimeClass supports
• Backends — choosing k7 vs k7-fc