DOCSEARCHbyAlgolia
Submit Docs

Agent Sandbox Documentation

repository·main·Indexed 25 days ago

https://github.com/kubernetes-sigs/agent-sandbox

A Kubernetes-native orchestrator for managing isolated, stateful, singleton workloads like AI agent runtimes or development environments. It uses a Sandbox CRD to manage pods with stable identities and persistent storage, delegating isolation to runtimes such as gVisor or Kata Containers. The project includes a Go Client SDK, a LangChain DeepAgents backend (deepagents-k8s-agent-sandbox), and an MCP Server for LLM-based sandbox management.

Tokens
172.2K
Snippets
357
Records
749
Agent score
83%

What's inside Agent Sandbox

  1. Overview of KEP-539.2: Standardizing Sandbox Runtime Interfaces

    main
    KEP-539.2 proposes a standardized interaction interface between AI agent client SDKs and isolated sandbox runtimes managed by agent-sandbox. The goal is to enable a single SDK to communicate with different sandbox runtimes seamlessly, ensuring vendor neutrality and feature completeness (such as file watching and Jupyter integration).

  2. Overview of Agent Sandbox

    main

    Agent Sandbox is a Kubernetes-native platform designed for managing isolated, stateful, singleton workloads. It is specifically built for AI agent runtimes, development environments, and scenarios requiring long-running containers with stable identities.

    Instead of manually managing Kubernetes primitives like StatefulSets, Services, and PersistentVolumeClaims, Agent Sandbox provides a declarative API via several Custom Resource Definitions (CRDs) to automate the lifecycle of these environments.

  3. Overview of agent-sandbox-rl

    main
    The agent-sandbox-rl package is a multi-cluster batch orchestration layer designed for Reinforcement Learning (RL) workloads on top of the k8s-agent-sandbox. Unlike the base k8s-agent-sandbox Python client which is limited to a single cluster and single sandbox, agent-sandbox-rl provides a framework-agnostic API to manage the full RL run lifecycle across multiple Kubernetes clusters. It handles image loading, cluster configuration, template/pool management, compute replica sizing, preflight checks, and teardown. It is designed to plug into RL stacks like R2E-Gym, tunix, TorchRL, and SkyRL.

  4. Overview of Agent Sandbox Network Policy Management

    main

    Agent Sandbox uses a Template-Level Shared Network Policy model. Instead of creating individual policies for every SandboxClaim, the controller maintains a single Kubernetes NetworkPolicy for each SandboxTemplate.

    Key behaviors:

    • Naming: Generated policies are named <template-name>-network-policy and reside in the template's namespace.
    • Targeting: The controller injects the label agents.x-k8s.io/sandbox-template-ref-hash onto Sandbox Pods, which the shared policy uses in its podSelector for precise enforcement.
    • Updates: Modifying the NetworkPolicy within a SandboxTemplate triggers an immediate update to the underlying Kubernetes NetworkPolicy.
    • DNS Protection: In the default posture, the controller overrides the Pod's DNS to use public resolvers (Google/Cloudflare) to prevent internal cluster DNS enumeration, provided dnsPolicy is not explicitly set to ClusterFirst in the PodSpec.

  5. Overview of the Sandbox Router

    main
    The Sandbox Router is a lightweight, asynchronous reverse proxy built with FastAPI and Uvicorn. It provides scalable and dynamic access to thousands of ephemeral agent sandboxes in a Kubernetes cluster by acting as a central entry point. Instead of creating individual network routes for every sandbox, the router receives requests and forwards them to the correct destination based on a unique identifier provided in the request headers.

  6. Overview of Agent Sandbox components

    main

    Agent Sandbox is a sandbox orchestrator that manages isolated, stateful, singleton workloads. It delegates low-level container isolation to Sandbox Runtimes (like gVisor or Kata Containers) via RuntimeClass.

    Core: Sandbox

    The Sandbox CRD provides a declarative API for a single, stateful pod with:

    • Stable Identity: Stable hostname and network identity.
    • Persistent Storage: Storage that survives restarts.
    • Lifecycle Management: Managed creation, scheduled deletion, pausing, and resuming.

    Extensions

    • SandboxTemplate: Reusable templates for creating multiple similar Sandboxes.
    • SandboxClaim: Allows creating Sandboxes from a SandboxWarmPool.
    • SandboxWarmPool: Manages a pool of pre-warmed Sandboxes for rapid allocation.

  7. Overview of Containarium SSH Sandbox Access Pattern

    main

    The Containarium SSH Sandbox provides an SSH-reachable, MCP-native access pattern for the Sandbox CRD. Unlike standard kubectl exec methods that require the agent to hold cluster credentials, this pattern uses SSH as the transport.

    Key Security Properties:

    • Credential Isolation: The agent holds only an SSH key, never a kube-apiserver token or cluster credentials. The cluster credential is only used once by an operator to provision the environment.
    • Forced Command Pinning: Every SSH session is hard-pinned via a forced command (-c /usr/local/bin/agent-box) directly into the MCP server. Even if a client sends a different command, the session only executes the MCP server.
    • Reduced Blast Radius: A leaked SSH key can only access the specific box's MCP surface and cannot be used for any cluster-scoped operations.
    • MCP Integration: The agent-box binary exposes typed tools (e.g., shell_exec, read_file, write_file, list_directory) over stdio, making it compatible with MCP-speaking agents like Claude Code or Cursor.

  8. Understand the agent-sandbox-rl architecture

    main

    agent-sandbox-rl is an orchestration layer built on top of the k8s-agent-sandbox SDK. While the SDK manages individual sandbox lifecycles, agent-sandbox-rl handles fleet-level concerns including:

    • Resource Management: CRUD for SandboxTemplate and SandboxWarmPool via the Resources component.
    • Placement & Sizing: Determining which cluster to use and how many replicas are needed based on concurrency and disk awareness.
    • Execution Strategies: Managing how pools are warmed up (e.g., naive, sliding, or pipelined windowed strategies).
    • Registry Rewriting: Redirecting images to in-region mirrors or pull-through caches.
    • Preflight & Prepull: Running per-cluster checks and using DaemonSets to cache images.

  9. Explore Agent Sandbox usage examples

    main

    The examples/ directory provides various implementation patterns for using the Agent Sandbox. Use these examples to understand how to integrate sandboxes with specific runtimes, agents, or infrastructure patterns:

    Agent & Framework Integrations

    • Agent Development Kit (ADK): Use code-interpreter-agent-on-adk to use Agent Sandbox as a tool within ADK.
    • LangChain/LangGraph: See langchain for a coding agent implementation using LangGraph.
    • Hermes Agent: See hermes-agent (with persistence and custom skills) or hermes-agents-as-a-service (multi-user platform pattern with per-user claims and suspend/resume).
    • Nullclaw: See nullclaw-sandbox for running the Nullclaw minimal AI assistant runtime.
    • Gemini Computer Use: See gemini-cu-sandbox for a Python runtime sandbox tailored for Gemini.

    Runtimes & Environments

    • Browsers: chrome-sandbox (Chrome in a sandbox), playwright-sandbox (Playwright with Chromium), and gke-swap (optimizing Chrome pod density on GKE).
    • Development Tools: jupyterlab (JupyterLab), vscode-sandbox (VSCode), and python-runtime-sandbox (Python runtime).
    • Specialized Runtimes: firecracker-sandbox (Kata Containers with Firecracker VMM), windows-sandbox (Windows guest via KVM/QEMU), and containarium-ssh-sandbox (Containarium's agent-box via SSH with MCP server).

    Infrastructure & Scaling Patterns

    • Scaling: hpa-swp-scaling (using Kubernetes HPA) and keda-scale-to-zero (using KEDA and Google Managed Service for Prometheus).
    • Networking & Policy: composing-sandbox-nw-policies (composing network policies) and policy (using different sandbox policies).
    • Resource Management: apf-insulation (API Priority and Fairness overlay for high-rate claims) and manual-pdb (manual PodDisruptionBudget configuration).

    Advanced Patterns

    • MCP Servers: mcp-server-sandbox (running an MCP server inside a sandbox with attached storage).
    • RL/Eval Workloads: agent-sandbox-rl (multi-cluster batch orchestration for SWE-bench-style workloads).

  10. Understand the Agent Sandbox Performance Report Template

    main

    The REPORT_TEMPLATE.md is used by the agent-sandbox-rl harness to generate standardized performance reports for benchmarking different sandbox strategies. These reports compare how different warm-pool management strategies (like naive, sliding, or pipelined) affect end-to-end task execution time and resource footprint in a Kubernetes cluster.

    Key components of a report include:

    • Performance Progress: An ASCII bar chart comparing wall-clock time across strategies.
    • Parameters: The configuration used for the run (images, tasks, concurrency, etc.).
    • Methodology: Details on how the harness manages SandboxTemplate and SandboxWarmPool resources.
    • Results Table: A breakdown of wall-clock time, phase-specific timings, and efficiency metrics.
    • Metric Glossary: Definitions for the timing phases used in the report.

  11. Use Agent Sandbox for Code Execution

    main

    Agent Sandbox allows you to run untrusted, AI-generated code in isolated Kubernetes pods. This prevents malicious or buggy code from accessing production systems, networks, or data.

    Key Benefits:

    • Security: Prevents access to host systems. Can be combined with runtimes like gVisor or Kata Containers for kernel-level isolation.
    • Isolation: Each sandbox is a dedicated Kubernetes pod with its own filesystem, processes, and network stack.
    • Stable Identity: Each sandbox provides a stable hostname and supports persistent storage for stateful workloads.
    • Performance: Uses SandboxWarmPool to pre-warm pods for fast allocation.

  12. Understand MCP Sandbox architecture and transport

    main

    The MCP Sandbox example uses kubectl exec -i POD -- python3 -u /app/mcp_server.py to create a long-lived bidirectional stdio channel. This channel serves as the MCP stdio transport.

    Architecture Flow:

    • The Host runs an MCP Client.
    • The Sandbox Pod hosts an MCP Server (e.g., using FastMCP).
    • kubectl exec pipes JSON-RPC frames between the host and the pod.
    • The MCP server manages files within a mounted PVC (e.g., at /workspace).

    Note on Latency: Because every request hops through kubectl exec $\rightarrow$ kube-apiserver $\rightarrow$ kubelet $\rightarrow$ pod, latency is higher than a local stdio session. For production-grade throughput, use the agentic-sandbox-client SDK which utilizes a router/gateway path.