Agent Sandbox Kubernetes SIG : des sandboxes isolees et stateful pour vos agents AI

Overview

Agent Sandbox est un projet Kubernetes SIG Apps (depot : kubernetes-sigs/agent-sandbox) qui developpe une CRD (Custom Resource Definition) Sandbox et son controller associe. L’objectif est de fournir une API declarative et standardisee pour gerer des workloads qui necessitent les caracteristiques d’un conteneur long-running, stateful, singleton avec une identite stable — une experience proche d’une VM legere a un seul conteneur, construite sur les primitives Kubernetes (README : https://github.com/kubernetes-sigs/agent-sandbox).

Le projet est ecrit en Go (60%) avec un SDK Python (34%) et propose une architecture en couches : un CRD core Sandbox, des extensions (SandboxTemplate, SandboxClaim, SandboxWarmPool), et une gamme de runtimes d’isolation (gVisor, Kata Containers).

Objectif

Kubernetes excelle pour les applications stateless et repliquees (Deployments) et les ensembles stateful numerotes (StatefulSets). Cependant, il manque une abstraction pour les cas d’usage suivants (README — section Motivation) :

• Environnements de developpement : espaces cloud isoles, persistants et accessibles par le reseau pour les developpeurs
• Runtimes d’agents AI : environnements isoles pour executer du code non fiable genere par LLM
• Notebooks et outils de recherche : sessions conteneurisees persistantes pour Jupyter Notebooks
• Services stateful a un seul pod : hebergement d’applications mono-instance (agents de build, petites bases de donnees) necessitant une identite stable sans le surcout de StatefulSet

Ces besoins peuvent etre approximes en combinant StatefulSet (taille 1), Service et PersistentVolumeClaim, mais cette approche est lourde et ne propose pas de gestion de cycle de vie specialisee comme la mise en veille prolongee (hibernation).

Liens utiles

• Depot principal GitHub
• Site web du projet
• Documentation officielle
• Guide demarrage
• Releases (v0.5.0)
• Roadmap 2026
• Python SDK sur PyPI
• Go SDK
• Exemples d’utilisation
• Documentation API v1beta1
• Slack #agent-sandbox
• gVisor
• Kata Containers

Installation

Controller et CRDs

L’installation se fait par kubectl apply sur les manifests publies a chaque release (README — section Installation) :

export VERSION="v0.5.0"\nkubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/\${VERSION}/manifest.yaml\nkubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/\${VERSION}/extensions.yamlLangage du code : JavaScript (javascript)

Helm

Le projet fournit egalement un chart Helm pour le controller, avec des options pour podSecurityContext, containerSecurityContext, podAnnotations et podLabels (release v0.5.0).

SDK Python

pip install k8s-agent-sandbox

SDK Go

go get sigs.k8s.io/agent-sandbox/clients/go/sandbox@latestLangage du code : JavaScript (javascript)

Notions et concepts

CRD Sandbox

La ressource Sandbox est le coeur du projet (README — section Core). Elle fournit une API declarative pour gerer un pod unique, stateful, avec une identite stable et un stockage persistant.

apiVersion: agents.x-k8s.io/v1beta1\nkind: Sandbox\nmetadata:\n  name: my-sandbox\nspec:\n  podTemplate:\n    spec:\n      containers:\n      - name: my-container\n        image: python:3.13-slimLangage du code : HTTP (http)

Caracteristiques cles (README) :

• Identite stable : hostname et identite reseau stables (my-sandbox)
• Stockage persistant : volumes qui survivent aux redemarrages (via volumeClaimTemplates)
• Gestion du cycle de vie : creation, suppression programmee, pause (hibernation) et reprise

Extensions

Le module extensions ajoute trois CRDs complementaires (README — section Extensions) :

• SandboxTemplate : templates reutilisables qui codifient la configuration d’execution pour un provisionnement coherent des sandboxes
• SandboxClaim : abstraction orientee utilisateur qui provisionne une sandbox depuis un template sans exposer les details de configuration bas niveau
• SandboxWarmPool : pools de pods prechauffes pour une allocation quasi-instantanee des sandboxes

Modes de fonctionnement (v0.5.0+)

La version v0.5.0 a introduit spec.operatingMode en remplacement de spec.replicas (release notes) :

• Running : la sandbox est active
• Suspended : la sandbox est mise en veille, les ressources CPU sont liberees mais le PVC est conserve

Modes de connexion SDK

Le Python SDK supporte trois modes de connexion (Documentation Python SDK Quickstart) :

Mode	Classe	Usage
Tunnel (defaut)	SandboxLocalTunnelConnectionConfig	Developpement local et CI — tunnel via kubectl port-forward
Gateway	SandboxGatewayConnectionConfig	Production avec un Kubernetes Gateway public
Direct	SandboxDirectConnectionConfig	Agents in-cluster, contourne la decouverte

Isolation

Le projet est agnostique du runtime d’isolation (Documentation) :

• gVisor : noyau utilisateur qui intercepte les appels systeme, compatible avec la plupart des workloads conteneurises
• Kata Containers : isolation au niveau materiel avec un noyau separe par sandbox

L’isolation se configure simplement via runtimeClassName dans le podTemplate :

spec:\n  podTemplate:\n    spec:\n      runtimeClassName: gvisor

Hibernation et reprise automatique

Parmi les caracteristiques souhaitees (README — section Desired Sandbox Characteristics) :

• Hibernation profonde : sauvegarde de l’etat sur le stockage persistant
• Reprise automatique : reprise de la sandbox a la premiere connexion reseau
• Suppression programmee : nettoyage automatique apres un TTL configurable

Commandes

Installation du controller

kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v0.5.0/manifest.yaml\nkubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v0.5.0/extensions.yamlLangage du code : JavaScript (javascript)

Installation du SDK Python

pip install k8s-agent-sandbox

Installation du sandbox-router

kubectl apply -f clients/python/agentic-sandbox-client/sandbox-router/sandbox_router.yaml

Deploiement du WarmPool

apiVersion: extensions.agents.x-k8s.io/v1beta1\nkind: SandboxWarmPool\nmetadata:\n  name: python-sandbox-pool\nspec:\n  templateRef: python-sandbox-template\n  replicas: 3Langage du code : HTTP (http)

Demo

Preparation du run

Ce workflow suppose un cluster Kubernetes avec le controller Agent Sandbox installe et un SandboxWarmPool nomme python-sandbox-pool (Documentation Python SDK Quickstart). Le sandbox-router doit etre deployee dans le cluster pour permettre au SDK Python de se connecter.

Creation d’une sandbox avec le Python SDK

from k8s_agent_sandbox import SandboxClient\n\nclient = SandboxClient()\n\nsandbox = client.create_sandbox(\n    warmpool="python-sandbox-pool",\n    namespace="default",\n)Langage du code : JavaScript (javascript)

Le mode de connexion par defaut (SandboxLocalTunnelConnectionConfig) ouvre un tunnel kubectl port-forward vers le service du routeur. Cela fonctionne sans IP publique, y compris sur KinD et Minikube (Documentation).

Execution d’une commande simple

try:\n    result = sandbox.commands.run("echo 'Hello from Agent Sandbox!'")\n    print(result.stdout)\nfinally:\n    sandbox.terminate()Langage du code : PHP (php)

Execution d’un script Python

sandbox = client.create_sandbox(\n    warmpool="python-sandbox-pool",\n    namespace="default",\n)\ntry:\n    sandbox.files.write(\n        "hello.py",\n        'print("Hello, World! Greetings from inside the sandbox.")\n',\n    )\n    result = sandbox.commands.run("python3 hello.py")\n    print(result.stdout)\nfinally:\n    sandbox.terminate()Langage du code : JavaScript (javascript)

Cycle de vie complet avec un agent ADK

L’exemple le plus abouti est celui de l’agent Code Interpreter sur ADK (Agent Development Kit) (Documentation Code Execution) :

1. Un agent ADK (utilisant Gemini 2.5 Flash) wrappe SandboxClient comme un outil
2. Pour chaque requete, il cree une sandbox depuis un template
3. Il ecrit le code Python dans un fichier via sandbox.files.write()
4. Il execute le code via sandbox.commands.run("python3 run.py")
5. Il recupere stdout et stderr
6. Il termine la sandbox via sandbox.terminate()

@tool\ndef execute_python_code(code: str) -> str:\n    sandbox = client.create_sandbox(\n        warmpool="python-sandbox-pool",\n        namespace="default",\n    )\n    try:\n        sandbox.files.write("run.py", code)\n        result = sandbox.commands.run("python3 run.py")\n        return result.stdout\n    finally:\n        sandbox.terminate()Langage du code : CSS (css)

Verification de l’isolation gVisor

kubectl wait --for=condition=Ready sandbox sandbox-example\nkubectl get pods -o jsonpath='{range .items[*]}{.metadata.name}: {.spec.runtimeClassName}{"\n"}{end}'Langage du code : JavaScript (javascript)

Conclusion

Agent Sandbox comble un vide dans l’ecosysteme Kubernetes : une API standard pour les workloads isoles, stateful et singleton. Avec ses extensions (templates, claims, warm pools), ses SDK Python et Go, et son support de runtimes d’isolation comme gVisor et Kata Containers, le projet est deja utilisable pour des cas concrets comme l’execution de code genere par LLM, les environnements de developpement ephemeres ou les agents AI iteratifs.

La version v0.5.0 (juin 2026) apporte la graduation de l’API en v1beta1, un renforcement de la securite (anti-SSRF, protection des metadatas, prevention d’empoisonnement des warm pools) et des ameliorations de performance significatives (creation parallele de sandboxes, selection optimisee des warm pools). La roadmap 2026 prevoit notamment un router first-class, un SDK TypeScript, un serveur MCP, et des objectifs de latence de claim sous 50ms.

Le depot (README : https://github.com/kubernetes-sigs/agent-sandbox) et la documentation (https://agent-sandbox.sigs.k8s.io/docs/) fournissent tous les elements pour un premier deploiement, que ce soit sur KinD pour le developpement local ou sur GKE/AKS pour la production.