# Examples Library Map

> Tour of the examples/ tree: AIO sandbox, Chrome/VSCode/JupyterLab, agent frameworks (Hermes, LangChain, ADK, Ray, Kueue), policy and scaling scenarios.

- Repository: kubernetes-sigs/agent-sandbox
- GitHub: https://github.com/kubernetes-sigs/agent-sandbox
- Human wiki: https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a
- Complete Markdown: https://grok-wiki.com/public/wiki/kubernetes-sigs-agent-sandbox-c3f2597a654a/llms-full.txt

## Source Files

- `examples/README.md`
- `examples/chrome-sandbox`
- `examples/vscode-sandbox`
- `examples/jupyterlab`
- `examples/policy`
- `examples/hpa-swp-scaling`
- `extensions/examples/README.md`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [examples/README.md](examples/README.md)
- [examples/aio-sandbox/README.md](examples/aio-sandbox/README.md)
- [examples/aio-sandbox/aio-sandbox.yaml](examples/aio-sandbox/aio-sandbox.yaml)
- [examples/chrome-sandbox/README.md](examples/chrome-sandbox/README.md)
- [examples/vscode-sandbox/README.md](examples/vscode-sandbox/README.md)
- [examples/jupyterlab/README.md](examples/jupyterlab/README.md)
- [examples/hermes-agent/README.md](examples/hermes-agent/README.md)
- [examples/langchain/README.md](examples/langchain/README.md)
- [examples/code-interpreter-agent-on-adk/README.md](examples/code-interpreter-agent-on-adk/README.md)
- [examples/ray-integration/README.md](examples/ray-integration/README.md)
- [examples/kueue-agent-sandbox/README.md](examples/kueue-agent-sandbox/README.md)
- [examples/hpa-swp-scaling/README.md](examples/hpa-swp-scaling/README.md)
- [examples/hpa-swp-scaling/hpa.yaml](examples/hpa-swp-scaling/hpa.yaml)
- [examples/policy/sandbox-automount-token-policy.yaml](examples/policy/sandbox-automount-token-policy.yaml)
- [examples/policy/sandbox-automount-token-binding.yaml](examples/policy/sandbox-automount-token-binding.yaml)
- [examples/policy/kyverno/README.md](examples/policy/kyverno/README.md)
- [examples/policy/network-policy-management/README.md](examples/policy/network-policy-management/README.md)
- [examples/policy/vap/README.md](examples/policy/vap/README.md)
- [examples/policy/opa-gatekeeper/README.md](examples/policy/opa-gatekeeper/README.md)
- [examples/policy/policy-controller/README.md](examples/policy/policy-controller/README.md)
- [examples/composing-sandbox-nw-policies/README.md](examples/composing-sandbox-nw-policies/README.md)
- [examples/quickstart/README.md](examples/quickstart/README.md)
- [examples/python-sdk-quickstart/README.md](examples/python-sdk-quickstart/README.md)
- [extensions/examples/README.md](extensions/examples/README.md)
- [extensions/examples/sandboxtemplate.yaml](extensions/examples/sandboxtemplate.yaml)
</details>

# Examples Library Map

The `examples/` tree in `kubernetes-sigs/agent-sandbox` is the canonical place where the project demonstrates how its core `Sandbox` CRD (and the `extensions.agents.x-k8s.io` types `SandboxTemplate`, `SandboxClaim`, and `SandboxWarmPool`) compose with real workloads, agent frameworks, isolation runtimes, admission policies, and autoscalers. The README at the root of the directory enumerates roughly twenty self-contained subdirectories, each tuned to a different reader: a platform operator standing up a quickstart cluster, an agent author wiring an SDK into LangGraph or ADK, or a security administrator validating Kyverno/VAP/Gatekeeper guardrails.

This page maps that tree by audience and purpose, links each subdirectory to the representative manifest or script that anchors it, and clarifies the boundary between the core `Sandbox` API (in this repo) and the higher-level extension CRDs that the more sophisticated examples consume.

Sources: [examples/README.md:1-20](), [extensions/examples/README.md:1-3](), [extensions/examples/sandboxtemplate.yaml:1-44]()

## Top-Level Layout

The two example roots in the repository serve different layers of the API:

| Path | Purpose | API surface |
| --- | --- | --- |
| `examples/` | End-to-end scenarios that consume the controller. Each subdirectory pairs a `README.md` with `.yaml` manifests and (often) Python/Go test drivers. | Mixed: core `Sandbox` plus, where useful, the extension CRDs and Python SDK. |
| `extensions/examples/` | Minimal reference manifests for the extension CRDs — one `SandboxTemplate`, one `SandboxClaim`, one `SandboxWarmPool`, plus a `SecurityContext`-locked-down variant. | `extensions.agents.x-k8s.io/v1alpha1` only. |

The split is intentional: `extensions/examples/` is a starter pack of canonical CRD shapes, while `examples/` shows how a sandbox is wired into a real agent or platform.

```text
examples/
├── README.md                        # index of all examples
├── quickstart/                      # end-to-end walkthrough (KIND default)
├── python-sdk-quickstart/           # SDK-first variant
├── hello-world-sandbox/             # smallest possible Sandbox
├── aio-sandbox/                     # All-in-One runtime (VNC/VSCode/Jupyter)
├── chrome-sandbox/                  # headless Chrome, used by e2e tests
├── vscode-sandbox/                  # code-server + kustomize overlays
├── jupyterlab/                      # JupyterLab + PVC + HF models
├── analytics-tool/                  # ADK analytics tool on GKE
├── hermes-agent/                    # Hermes agent with custom skills
├── langchain/                       # LangGraph coding agent + local model
├── code-interpreter-agent-on-adk/   # ADK + Sandbox SDK as a tool
├── ray-integration/                 # Ray + warm pool + gVisor proxy exec
├── kueue-agent-sandbox/             # Admission control via Kueue
├── hpa-swp-scaling/                 # HPA scaling a SandboxWarmPool
├── manual-pdb/                      # PodDisruptionBudget recipe
├── composing-sandbox-nw-policies/   # KRO composition: Sandbox+Service+NetPol
├── policy/                          # VAP, Kyverno, OPA, Policy Controller
├── python-runtime-sandbox/          # FastAPI runtime image used by SDK
├── gemini-cu-sandbox/               # Gemini Computer Use sandboxed runtime
├── openclaw-sandbox/                # OpenClaw inside Sandbox
├── kata-gke-sandbox/                # Kata Containers on GKE node pools
└── sandbox-ksa/                     # Sandbox bound to a custom ServiceAccount

extensions/examples/                 # canonical CRD shapes
├── sandboxtemplate.yaml             # SandboxTemplate
├── sandbox-claim.yaml / sandboxclaim.yaml
├── sandboxwarmpool.yaml
├── secure-sandboxtemplate.yaml
└── llm.yaml
```

Sources: [examples/README.md:1-20](), [extensions/examples/README.md:1-3]()

## Onboarding Path: Quickstarts and Hello World

These examples are entry points: they require no agent framework and validate the controller, runtime, and SDK are working before moving on.

- **`quickstart/`** is the full walkthrough. It enumerates the resource set a new user will encounter — `Sandbox`, `SandboxTemplate`, `SandboxClaim`, `SandboxWarmPool`, the Python SDK, and the Router Service — and branches off to `gvisor.md` or `kata-containers.md` if the reader wants hardened isolation rather than a vanilla KIND cluster. It is the only example that explicitly enumerates all the public types up front.
- **`python-sdk-quickstart/`** flips the same flow around the SDK. It documents the three connection modes the client supports (`SandboxLocalTunnelConnectionConfig` for tunneled local development, `SandboxGatewayConnectionConfig` for a public Kubernetes Gateway, `SandboxDirectConnectionConfig` for in-cluster agents) and requires that a `python-sandbox-template` already exists from the Python Runtime example.
- **`hello-world-sandbox/`** is the smallest example: a Dockerfile, a Sandbox manifest, and instructions to push to Artifact Registry. Useful for sanity checks against a fresh cluster.

Sources: [examples/quickstart/README.md:1-60](), [examples/python-sdk-quickstart/README.md:1-30](), [examples/hello-world-sandbox/README.md:1-30]()

## Interactive Workspaces

This cluster of examples shows the `Sandbox` CRD wrapping general-purpose interactive runtimes — what an end user might think of as "a remote dev environment for an agent."

### AIO Sandbox

`aio-sandbox/` deploys the All-in-One image from `agent-infra/sandbox`, which bundles VNC, VSCode, Jupyter, and a terminal behind a single port. The manifest is minimal and demonstrates the bare-minimum hardened `securityContext`:

```yaml
# examples/aio-sandbox/aio-sandbox.yaml
spec:
  podTemplate:
    spec:
      containers:
        - name: aio-sandbox
          image: ghcr.io/agent-infra/sandbox:1.0.0.152
          securityContext:
            allowPrivilegeEscalation: false
          ports:
          - containerPort: 8080
          resources:
            limits:
              memory: "4Gi"
              cpu: "2000m"
```

The README distinguishes the in-pod `agent-sandbox` Python SDK (which drives tools inside the running sandbox — browser, shell, files) from the `agentic-sandbox-client` SDK that provisions sandboxes via the CRDs. They are designed to compose.

### Chrome Sandbox

`chrome-sandbox/` runs a headless Chrome inside a `Sandbox`, exposing the DevTools port `9222`. It doubles as the foundation for the project's e2e tests; the README points at `test/e2e/chromesandbox_test.go` as the authoritative consumer.

### VSCode Sandbox

`vscode-sandbox/` is the most layered of the workspace examples. It ships a base kustomization plus three overlays — `overlays/gvisor`, `overlays/kata`, `overlays/kata-mshv` — that inject the corresponding `runtimeClassName`. The README explains the access pattern carefully: when a hardened runtime is used, direct `kubectl port-forward` to the Pod is incompatible, so traffic must be routed through the Sandbox Router using the `X-Sandbox-ID` / `X-Sandbox-Port` headers (or a Gateway in production).

### JupyterLab

`jupyterlab/` offers two deployment shapes — a single-file `jupyterlab-full.yaml` or the modular `jupyterlab.yaml` plus a `kubectl create configmap` step from `files/` — and demonstrates init-container patterns: the `setup-environment` init container downloads Python deps and HuggingFace models into a `volumeClaimTemplates` PVC before the JupyterLab container starts. The README also covers force-re-init by removing `/home/jovyan/.initialized`.

Sources: [examples/aio-sandbox/README.md:1-92](), [examples/aio-sandbox/aio-sandbox.yaml:1-22](), [examples/chrome-sandbox/README.md:1-95](), [examples/vscode-sandbox/README.md:1-258](), [examples/jupyterlab/README.md:1-90]()

## Agent Framework Integrations

These examples show how to plug the sandbox primitives into common agent frameworks. They are the cleanest reference for "how do I make my agent run untrusted code in a sandbox?"

```mermaid
flowchart LR
    subgraph Local["Local / Trusted process"]
        Agent[Agent code<br/>LangGraph / ADK / Ray Actor]
        SDK[k8s-agent-sandbox SDK<br/>SandboxClient]
    end
    subgraph Cluster["Kubernetes cluster"]
        Router[sandbox-router<br/>Service]
        subgraph WarmPool["SandboxWarmPool"]
            Pod1[Pod<br/>runtime image]
            Pod2[Pod<br/>runtime image]
        end
        Template[SandboxTemplate]
    end

    Agent --> SDK
    SDK -->|Tunnel / Gateway / Direct| Router
    Router -->|X-Sandbox-ID / X-Sandbox-Port| Pod1
    WarmPool -.references.-> Template
```

- **`langchain/`** wires a LangGraph coding agent to a sandboxed Python runtime. The init container caches a HuggingFace model (`Salesforce/codegen-350M-mono` by default) on a PVC; the agent's execution loop generates code, sends it into the sandbox, captures errors, and retries up to three times. The README documents memory tuning and how to swap models.
- **`code-interpreter-agent-on-adk/`** is the lightest framework integration: a six-line ADK `Agent` whose only tool wraps `SandboxClient` to create a sandbox, write `run.py`, execute `python3 run.py`, and tear the sandbox down. It is the recommended pattern for "ADK + execute_python."
- **`hermes-agent/`** runs the Hermes agent inside a sandbox with a ConfigMap-mounted custom "Kubernetes Developer" skill (`hermes-skills` ConfigMap from `k8s-developer.md`). It includes `test_hermes.py` for automated verification and `chat_hermes.py` for interactive sessions on port 8642.
- **`ray-integration/`** is the most architecturally explicit example. It documents the **Proxy Execution Model**: a Ray rollout actor stays inside the trusted cluster, and every untrusted code execution is proxied via `SandboxClient` into a gVisor-isolated pod claimed from a `SandboxWarmPool`. The README provides `rl_poc_local.py` (using `SandboxLocalTunnelConnectionConfig`) and `rl_poc_prod.py` (using `SandboxGatewayConnectionConfig` with `gateway_name: "external-http-gateway"`).
- **`kueue-agent-sandbox/`** is admission control rather than a framework. It shows the `kueue.x-k8s.io/queue-name` label being attached to the `podTemplate.metadata.labels` of a `Sandbox`, so Kueue queues pod admission until cluster-queue quota is available. The README is explicit about scope: Kueue controls *when* a sandbox starts, not how long it runs.

Sources: [examples/langchain/README.md:1-90](), [examples/code-interpreter-agent-on-adk/README.md:1-70](), [examples/hermes-agent/README.md:1-105](), [examples/ray-integration/README.md:1-220](), [examples/kueue-agent-sandbox/README.md:1-109]()

## Scaling and Disruption

Two examples target the operational lifecycle of sandbox pools rather than the workloads inside them.

`hpa-swp-scaling/` is GKE-specific: it scales a `SandboxWarmPool` with a stock Kubernetes `HorizontalPodAutoscaler` that consumes a Prometheus counter (`agent_sandbox_claim_creation_total`) exposed through the GKE Managed Service for Prometheus and the Custom Metrics Adapter. The HPA spec scales the warm pool itself rather than a Deployment:

```yaml
# examples/hpa-swp-scaling/hpa.yaml
scaleTargetRef:
  apiVersion: extensions.agents.x-k8s.io/v1alpha1
  kind: SandboxWarmPool
  name: python-sdk-warmpool
minReplicas: 10
maxReplicas: 100
metrics:
- type: External
  external:
    metric:
      name: "prometheus.googleapis.com|agent_sandbox_claim_creation_total|counter"
    target:
      type: Value
      value: "0.5"
```

`create-claim.py` is the load generator and `pod-monitoring.yaml` exposes the metric to Managed Prometheus. The README contains a real `kubectl get hpa -w` trace showing the warm pool scaling from 10 to 100 and back down as claim rate rises and falls.

`manual-pdb/` shows the opt-in `PodDisruptionBudget` pattern: a shared PDB selects pods carrying `sandbox-disruption-policy: "manual-protection"`, set on the `SandboxTemplate`. Sandboxes without that label are unprotected from voluntary disruptions. The README warns specifically against `minAvailable: 1` on a shared PDB.

Sources: [examples/hpa-swp-scaling/README.md:1-97](), [examples/hpa-swp-scaling/hpa.yaml:1-23](), [examples/manual-pdb/README.md:1-40]()

## Policy and Admission

`examples/policy/` is the largest single sub-tree and demonstrates how the project layers cluster admission controllers on top of the `Sandbox` CRD. Each subdirectory targets a different policy engine but solves the same family of problems: prevent privilege escalation, enforce isolation defaults, and lock down the ServiceAccounts a `Sandbox` references.

| Subdirectory | Engine | Headline rule |
| --- | --- | --- |
| `vap/` | Kubernetes `ValidatingAdmissionPolicy` (built-in, v1.30+) | Enforces a "Secure by Default" posture across containers/initContainers/ephemeralContainers via CEL — `runtimeClassName: gvisor`, `hostNetwork/hostPID/hostIPC: false`, `automountServiceAccountToken: false`, `privileged: false`, `capabilities.drop: ["ALL"]`, resource limits, and GKE-specific `nodeSelector`/`tolerations`. |
| `kyverno/` | Kyverno `ValidatingPolicy` | Denies `RoleBinding`/`ClusterRoleBinding` creates or updates that grant permissions to a ServiceAccount used by a `Sandbox`-owned Pod, including indirect references via `system:serviceaccounts[:ns]` groups. Includes Chainsaw tests in `.chainsaw-tests/`. |
| `opa-gatekeeper/` | OPA Gatekeeper | Same goal, Rego implementation. |
| `policy-controller/` | Google Cloud Policy Controller (Anthos) | Same goal, fleet-managed on GKE. |
| (top-level) `sandbox-automount-token-{policy,binding}.yaml` | Plain VAP | A single rule: every `Sandbox` must explicitly set `spec.podTemplate.spec.automountServiceAccountToken == false`. |
| `network-policy-management/` | Controller-managed `NetworkPolicy` | Documents the Template-Level Shared Network Policy model and the Secure-by-Default ingress/egress posture (allow only the Sandbox Router; block RFC1918, link-local metadata, cluster DNS). |

The standalone `sandbox-automount-token-policy.yaml` is a useful read because it is small and concrete:

```yaml
# examples/policy/sandbox-automount-token-policy.yaml
spec:
  failurePolicy: Fail
  matchConstraints:
    resourceRules:
      - apiGroups:   ["agents.x-k8s.io"]
        apiVersions: ["v1alpha1"]
        operations:  ["CREATE", "UPDATE"]
        resources:   ["sandboxes"]
  validations:
    - expression: "object.spec.podTemplate.spec.automountServiceAccountToken == false"
```

The binding scopes the policy to every namespace except `kube-system`. Together these two files are the minimal hardening pattern the repo recommends.

`composing-sandbox-nw-policies/` complements the policy directory by demonstrating composition with **KRO** (`ResourceGraphDefinition`). It bundles a `Sandbox`, a `Service`, and a `NetworkPolicy` into a single higher-level `AgenticSandbox` CRD, illustrating one of three composition strategies the README discusses (custom controller, KRO, Helm).

Sources: [examples/policy/vap/README.md:1-46](), [examples/policy/kyverno/README.md:1-90](), [examples/policy/opa-gatekeeper/README.md:1-60](), [examples/policy/policy-controller/README.md:1-60](), [examples/policy/sandbox-automount-token-policy.yaml:1-15](), [examples/policy/sandbox-automount-token-binding.yaml:1-15](), [examples/policy/network-policy-management/README.md:1-90](), [examples/composing-sandbox-nw-policies/README.md:1-40]()

## Runtime Hardening Scenarios

A subset of examples is dedicated to providing a stronger isolation boundary under the `Sandbox` CRD by changing the container runtime. They all converge on `spec.podTemplate.spec.runtimeClassName`.

| Example | Runtime | Cluster target |
| --- | --- | --- |
| `vscode-sandbox/overlays/gvisor` | gVisor | Any cluster with the `gvisor` RuntimeClass |
| `vscode-sandbox/overlays/kata` | Kata Containers (QEMU) | Local minikube with nested virtualization |
| `vscode-sandbox/overlays/kata-mshv` | Kata + Microsoft Hypervisor | Azure AKS Pod Sandboxing |
| `kata-gke-sandbox/` | Kata Containers on GKE | Requires N2 Intel + Ubuntu node pool, via `setup.sh` |
| `quickstart/gvisor.md`, `quickstart/kata-containers.md` | Either | KIND/minikube introductory paths |

Each of these examples emphasizes that direct pod port-forward stops working under non-default runtimes; access must go through the Sandbox Router service or a Kubernetes Gateway.

Sources: [examples/vscode-sandbox/README.md:20-150](), [examples/kata-gke-sandbox/README.md:1-50](), [examples/quickstart/README.md:1-60]()

## Runtime Images and Specialized Workloads

The remaining examples package container images and surrounding glue for specific workloads.

- **`python-runtime-sandbox/`** is the FastAPI image with `/execute` that the Python SDK and the Ray integration consume. It defines two Pydantic models, `ExecuteRequest` and `ExecuteResponse`, and ships `run-test-docker.sh` and `run-test-kind.sh` for local validation.
- **`gemini-cu-sandbox/`** wraps the `computer-use-preview` agent (Gemini Computer Use) in a sandboxed FastAPI server, requiring `GEMINI_API_KEY`.
- **`openclaw-sandbox/`** runs OpenClaw (formerly Moltbot) inside a `Sandbox`; the README documents the gVisor + port-forward incompatibility and points at the Router as the workaround.
- **`analytics-tool/`** packages an ADK analytics tool image for GKE and shows the Service/JupyterLab integration on top.
- **`sandbox-ksa/`** is the canonical pattern for binding a `Sandbox` to a custom Kubernetes ServiceAccount — useful for per-sandbox identity and RBAC scoping.

Sources: [examples/python-runtime-sandbox/README.md:1-40](), [examples/gemini-cu-sandbox/README.md:1-40](), [examples/openclaw-sandbox/README.md:1-45](), [examples/analytics-tool/README.md:1-40](), [examples/sandbox-ksa/README.md:1-40]()

## Choosing An Example

The decision tree most readers follow is roughly:

1. **Just trying it out?** Start with `quickstart/` (or `python-sdk-quickstart/` for the SDK-centric path). Use `hello-world-sandbox/` as a smoke test.
2. **Wiring an agent framework?** Pick the framework-aligned example: `code-interpreter-agent-on-adk/` for ADK, `langchain/` for LangGraph, `hermes-agent/` for Hermes, `ray-integration/` for Ray RL.
3. **Need an interactive environment for a human or model to inhabit?** `aio-sandbox/`, `vscode-sandbox/`, `jupyterlab/`, or `chrome-sandbox/` depending on the tool surface.
4. **Operating at scale?** `hpa-swp-scaling/` for autoscaling warm pools, `manual-pdb/` for disruption control, `kueue-agent-sandbox/` for admission quotas.
5. **Securing the platform?** Start with `examples/policy/vap/` for the headline VAP, then layer `examples/policy/network-policy-management/` and one of `kyverno/`, `opa-gatekeeper/`, or `policy-controller/` depending on your engine.
6. **Hardening the runtime?** Pick a `vscode-sandbox/overlays/*` overlay or `kata-gke-sandbox/` matching your cluster.

The `extensions/examples/` directory is the place to look when you only need the raw CRD shapes for `SandboxTemplate`, `SandboxClaim`, and `SandboxWarmPool` without surrounding application code — it is referenced by `manifest.yaml`/`extensions.yaml` installation flows discussed in the higher-level examples.

Sources: [examples/README.md:1-20](), [extensions/examples/README.md:1-3](), [extensions/examples/sandboxtemplate.yaml:1-44]()