Help us improve
Share bugs, ideas, or general feedback.
From all-skills
Installs and operates the kubernetes-sigs/agent-sandbox controller for per-session, isolated AI agent pods on Kubernetes. Covers CRDs, SandboxTemplate/SandboxClaim manifests, warm pools, network policies, and RuntimeClass selection (Kata Containers vs gVisor).
npx claudepluginhub vinnie357/claude-skills --plugin sbxHow this skill is triggered — by the user, by Claude, or both
Slash command
/all-skills:k8s-agent-sandboxThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
The upstream open-source project `kubernetes-sigs/agent-sandbox` ships four CRDs that model "give me a per-session, isolated pod for an AI agent and reap it when the session ends." This skill covers the controller, the CRD model, and the lifecycle. Pair with `kata-on-kind` / `kata-on-gke` / `kina-microvm` for the RuntimeClass install and with `claude-code-on-sandbox` for the workload-side packa...
Decision-tree index routing to Kubernetes-orchestrated (Kata, gVisor, Apple Container) or single-host (docker) sandboxing for AI agents. Use when picking an isolation strategy.
Guides deployment of Google ADK agents to Cloud Run, GKE, or Agent Runtime, covering CI/CD, secrets, and rollback.
Installs CAST AI agent on Kubernetes clusters via Helm charts or Terraform with API key auth. For EKS/GKE/AKS onboarding, cost optimization, autoscaling.
Share bugs, ideas, or general feedback.
The upstream open-source project kubernetes-sigs/agent-sandbox ships four CRDs that model "give me a per-session, isolated pod for an AI agent and reap it when the session ends." This skill covers the controller, the CRD model, and the lifecycle. Pair with kata-on-kind / kata-on-gke / kina-microvm for the RuntimeClass install and with claude-code-on-sandbox for the workload-side packaging.
SandboxTemplate for an agent workload.SandboxClaim from a shell, CI job, or the Python SDK.SandboxWarmPool to get sub-second cold-starts.networkPolicyManagement: Managed.kubernetes-sigs/agent-sandbox is Apache-2.0 (verified at https://github.com/kubernetes-sigs/agent-sandbox). Latest release v0.4.6 (2026-05-14). API group agents.x-k8s.io (core Sandbox) and extensions.agents.x-k8s.io (templates, claims, warm pools). The upstream README example uses v1alpha1; docs/api.md documents v1beta1. Verify the installed CRD version before authoring manifests:
kubectl api-resources | grep -E 'agents\.x-k8s\.io'
GKE ships a managed variant ("Agent Sandbox") that became GA on 2026-05-20. The managed variant is gVisor-only; the upstream open-source project accepts any runtimeClassName including Kata. This skill targets the upstream because Kata (microVM isolation) is the primary use case here.
VERSION=v0.4.6
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/manifest.yaml
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/extensions.yaml
Two manifests because the project splits the core Sandbox CRD from the higher-level SandboxTemplate / SandboxClaim / SandboxWarmPool extensions. Apply both.
Verify the controller comes up:
kubectl get pods -n agent-sandbox-system
kubectl get crd | grep agents.x-k8s.io
gcloud beta container clusters create-auto ${CLUSTER_NAME} \
--location=${LOCATION} \
--cluster-version=${CLUSTER_VERSION} \
--enable-agent-sandbox
GKE version 1.35.2-gke.1269000 or later. IAM: roles/serviceusage.serviceUsageAdmin. APIs to enable: Artifact Registry, GKE.
# Create cluster, then add a sandbox node pool, then enable the addon.
gcloud container clusters create ${CLUSTER_NAME} --location=${LOCATION} --cluster-version=${CLUSTER_VERSION}
gcloud container node-pools create sandbox-pool \
--cluster=${CLUSTER_NAME} --location=${LOCATION} \
--image-type=cos_containerd --sandbox=type=gvisor
gcloud beta container clusters update ${CLUSTER_NAME} --location=${LOCATION} --enable-agent-sandbox
The managed addon installs the same CRDs but pins runtimeClassName: gvisor. For Kata on GKE, use the upstream install instead and follow kata-on-gke.
See references/crds.md for full field reference. One-paragraph summary of each:
Sandbox (agents.x-k8s.io) — the actual workload. A single stateful pod with a stable network identity.SandboxTemplate (extensions.agents.x-k8s.io) — a reusable PodSpec for sandboxes. podTemplate.spec.runtimeClassName picks the isolation tier.SandboxClaim (extensions.agents.x-k8s.io) — a per-session request that references a SandboxTemplate and optionally a SandboxWarmPool. Carries lifecycle.shutdownPolicy: Delete so the sandbox auto-reaps.SandboxWarmPool (extensions.agents.x-k8s.io) — N pre-warmed pods sitting idle so that a SandboxClaim resolves in sub-second instead of normal Pod scheduling time.The plugin's templates assume this flow:
SandboxTemplate per agent workload (e.g. one for claude-code-kata, one for python-runtime).SandboxWarmPool per template if cold-start latency matters.SandboxClaim per session.kubectl delete on the claim (or shutdownPolicy: Delete with a shutdownTime) tears down the pod.See references/lifecycle.md for the claim/warm-pool semantics.
Apply a SandboxClaim from a shell or CI step:
apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxClaim
metadata:
name: session-${SESSION_ID}
spec:
sandboxTemplateRef:
name: claude-code-kata
lifecycle:
shutdownPolicy: Delete
env:
- name: ANTHROPIC_API_KEY
valueFrom:
secretKeyRef:
name: anthropic
key: api-key
spec.env injects per-claim env vars into the pod — keep ANTHROPIC_API_KEY out of the template so the template stays generic across callers.
For the Python SDK alternative (k8s-agent-sandbox / agentic-sandbox-client), see references/python-sdk.md.
SandboxTemplateSpec has first-class networkPolicy (NetworkPolicySpec) and networkPolicyManagement (Managed / Unmanaged) fields. With Managed, the controller materializes a NetworkPolicy from the template.
Default-deny + DNS + outbound HTTPS to Anthropic:
spec:
networkPolicyManagement: Managed
networkPolicy:
egress:
- to:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: kube-system
ports:
- protocol: UDP
port: 53
- to:
- ipBlock:
cidr: 0.0.0.0/0 # narrow to resolved api.anthropic.com CIDRs in prod
ports:
- protocol: TCP
port: 443
The 0.0.0.0/0:443 block is a placeholder for development. In production, resolve api.anthropic.com and narrow to Anthropic's egress ranges. See references/network-policy.md for the resolution recipe and for layering Claude Code's own init-firewall.sh on top (defense in depth).
| RuntimeClass | Isolation | Where it runs | Skill |
|---|---|---|---|
kata-qemu | Hardware microVM (KVM) | Linux hosts only — kind on Linux, GKE Standard with N2 Ubuntu | kata-on-kind, kata-on-gke |
gvisor | Userspace kernel | Anywhere — Apple Silicon kind, GKE managed Agent Sandbox | claude-code-on-sandbox (gVisor template) |
| (omit) | Cluster-level (each node IS a microVM) | macOS via kina (Apple Container nodes) | kina-microvm |
The kina case is structurally different: there is no per-pod RuntimeClass swap because the cluster itself sits inside Apple Container microVMs. Omit runtimeClassName in the SandboxTemplate. See kina-microvm for why.
After install + template + claim:
kubectl get sandboxes -A
kubectl get sandboxclaims -A
kubectl describe sandboxclaim session-${SESSION_ID}
kubectl exec -it sandbox/session-${SESSION_ID} -- /bin/sh
If the claim sticks in Pending, check the controller logs:
kubectl logs -n agent-sandbox-system deploy/agent-sandbox-controller -f
The upstream README shows agents.x-k8s.io/v1alpha1 examples; docs/api.md documents v1beta1. Pin templates to whatever the installed manifest defines. Run kubectl api-resources | grep agents after install and use the listed version verbatim. Don't paste templates from this skill without that check.
kata-on-kind — install Kata Containers on a local Linux kind cluster.kata-on-gke — install Kata on a self-managed GKE node pool.kina-microvm — macOS path where the cluster itself is the microVM tier.claude-code-on-sandbox — build the Claude Code OCI image and deploy as a SandboxTemplate.agent-substrate-overview — alpha alternative control plane sharing the same primitives.Verify before claiming:
kubectl api-resources | grep agents and kubectl get crd | grep agents.x-k8s.io before pasting CRD manifests; the API version (v1alpha1 vs v1beta1) differs between upstream README examples and the docs.SandboxWarmPool is satisfying claims without kubectl describe sandboxwarmpool showing Ready replicas.https://api.anthropic.com/v1/models (or equivalent).