add guides

Author: volatilemolotov

site/content/en/docs/guides/_index.md

@@ -0,0 +1,10 @@
+---
+title: "Guides"
+linkTitle: "Guides"
+weight: 20
+description: >
+  This page provides a collection of official guides and code examples for integrating the agent sandbox into your projects.
+menu:
+  main:
+    weight: 20
+---

site/content/en/docs/guides/arbitrary_code_execution/_index.md

@@ -0,0 +1,118 @@
+---
+title: "Arbitrary Code Execution"
+linkTitle: "Arbitrary Code Execution"
+weight: 2
+description: >
+  This guide shows how to deploy a simple Python server that executes arbitrary commands in a sandbox container.
+---
+
+The server application includes a FastAPI server that can execute commands that are sent to it through HTTP requests.
+
+## Python Classes of the server app
+
+The `examples/python-runtime-sandbox/main.py` file defines the following Pydantic models to ensure type-safe data for the API endpoints:
+
+### `ExecuteRequest`
+This class models the request body for the `/execute` endpoint.
+- **`command: str`**: The shell command to be executed in the sandbox.
+
+### `ExecuteResponse`
+This class models the response body for the `/execute` endpoint.
+- **`stdout: str`**: The standard output from the executed command.
+- **`stderr: str`**: The standard error from the executed command.
+- **`exit_code: int`**: The exit code of the executed command.
+## Install Agent Sandbox on a local Kind cluster
+
+In this example we will create a [Kind (Kubernetes In Docker)](https://kind.sigs.k8s.io/) cluster to install the Agent Sandbox.
+
+1. Clone the `agent-sandbox` repository if needed:
+
+   ```sh
+   git clone https://github.com/kubernetes-sigs/agent-sandbox.git
+   ```
+
+2. Move to the repository folder:
+
+   ```sh
+   cd agent-sandbox
+   ```
+
+3. Create a Kind cluster and deploy the agent controller by following this [installation tutorial](../../installation/_index.md).
+
+## Deploy Python Runtime Sandbox
+
+1. Go to the Python Runtime example folder:
+
+   ```sh
+   cd examples/python-runtime-sandbox
+   ```
+
+2. Build image with Python Runtime
+
+   ```sh
+   docker build -t sandbox-runtime .
+   ```
+
+3. Load the resulting image into the Kind cluster:
+
+   ```sh
+   kind load docker-image sandbox-runtime:latest --name agent-sandbox
+   ```
+
+4. Apply Python runtime sandbox CRD and deployment:
+
+   ```sh
+   kubectl apply -f sandbox-python-kind.yaml
+   ```
+
+5. Wait for the sandbox pod to be ready:
+
+   ```sh
+   kubectl wait --for=condition=ready pod --selector=sandbox=my-python-sandbox --timeout=60s
+   ```
+
+## Test runtime sandbox
+
+1. Create another terminal session and port-forward sandbox’s pod in order to access it:
+
+   ```sh
+   kubectl port-forward "pod/sandbox-python-example" 8888:8888
+   ```
+
+2. Verify that runtime sandbox’s server is up:
+
+   ```sh
+   curl  127.0.0.1:8888/
+   ```
+
+   The output should be similar to:
+
+   ```log
+   {"status":"ok","message":"Sandbox Runtime is active."}
+   ```
+
+3. Create an environment variable with the command that has to be executed:
+
+   ```sh
+   PAYLOAD="{\"command\": \"echo 'hello world'\"}"
+   ```
+
+4. Execute the command:
+
+   ```sh
+   curl -X POST -H "Content-Type: application/json" -d "${PAYLOAD}" 127.0.0.1:8888/execute
+   ```
+
+   The output should be similar to:
+
+   ```log
+   {"stdout":"hello world\n","stderr":"","exit_code":0}
+   ```
+
+## Cleanup
+
+1. Delete the Kind cluster:
+
+   ```sh
+   kind delete cluster --name agent-sandbox
+   ```

site/content/en/docs/guides/chrome-sandbox/_index.md

@@ -0,0 +1,30 @@
+---
+title: "Chrome in a Sandbox"
+linkTitle: "Chrome in a Sandbox"
+weight: 2
+description: >
+  This guide documents the complete setup and deployment of Chrome in a Sandbox that runs locally on Kubernetes using Kind (Kubernetes in Docker) with the agent-sandbox controller.
+---
+# chrome in a Sandbox
+
+Navigate to the folder with resources by running:
+```bash
+cd examples/chrome-sandbox
+```
+
+This example runs Chrome in a container; we are starting by running it in a Docker container,
+but the plan is to run it in a Sandbox as we stand up the infrastructure there.
+
+Currently you can test it out by running `run-test`; it will build a (local) container image,
+then run it.  The image will capture screenshots roughly every 100ms so you can observe
+the progress as Chrome launches and opens (currently) https://google.com
+
+The screenshots are in an unusual xwg format, so the script depends on the `convert`
+utility to convert those to an animated gif.
+
+Plans:
+
+* Move to Sandbox
+* Implement a better test for readiness
+* Maybe support selenium / playwright to make this a more useful example
+* Incorporate into our e2e tests

site/content/en/docs/guides/composing-sandbox-nw-policies/_index.md

@@ -0,0 +1,120 @@
+---
+title: "Composing Sandbox with Network Policies"
+linkTitle: "Composing Sandbox with Network Policies"
+weight: 2
+description: >
+  This guide documents the complete setup Sandbox with Network Policies that runs locally on Kubernetes using Kind (Kubernetes in Docker) with the agent-sandbox controller.
+---
+
+## Composing Sandbox with Network Policies
+
+The `Sandbox` API is a low-level primitive for creating secure sandboxes. In real-world scenarios, you often want to compose a `Sandbox` with other Kubernetes resources, such as `NetworkPolicy`, `Ingress` and `Service`, to create a more complete and secure "agentic sandbox" environment.
+
+* `Ingress` can be used to expose the Sandbox to Users and Agents outside the cluster.
+* `NetworkPolicy` can be used to control who can connect to the Sandbox and limit the Sandbox outgoing connections to other pods or the internet.
+* `Service` can be used to expose the Sandbox ports for `Ingress`
+
+```bash
+graph TD
+    User --> Ingress
+    Agent --> Ingress
+    Ingress --> Service
+    Service --> NetworkPolicy
+    NetworkPolicy --> Sandbox
+    Sandbox --> NetworkPolicy
+    NetworkPolicy <--> Internet
+    NetworkPolicy <-->  Pods
+```
+
+This composition can be achieved in multiple ways:
+
+*  **Writing a custom controller:** You can write a dedicated Kubernetes controller that watches for a higher-level CRD and creates the `Sandbox`, `NetworkPolicy`, and `Service` resources.
+*  **Using a tool like KRO:** [KRO (Kubernetes Resource Orchestrator)](https://kro.run/docs/overview) allows you to define composite resources declaratively using a `ResourceGraphDefinition` (RGD). This creates a server side CRD that can be consumed by users.
+* **Using Helm:** Similar to KRO, we can use Helm to create a client side composition of resources and use the helm-cli to manage it.
+
+This example demonstrates the second approach, using KRO to define a new `AgenticSandbox` CRD that encapsulates a `Sandbox`, a `NetworkPolicy`, and a `Service`.
+
+The `Service` created here is distinct from the one created by the `agent-sandbox` controller. This layering allows for more complex networking configurations and showcases the value of composing resources.
+
+### Brief introduction to KRO
+
+KRO is a powerful tool for defining and managing composite resources in Kubernetes. At its core, KRO introduces the `ResourceGraphDefinition` (RGD) custom resource. An RGD allows you to declaratively specify a graph of Kubernetes resources that should be created, updated, and deleted together as a single unit. When an RGD is applied to a cluster, KRO automatically generates a new Custom Resource Definition (CRD) based on the RGD's schema. Users can then interact with this new, higher-level CRD, and KRO will handle the orchestration of the underlying resources defined in the RGD. This enables administrators to define complex, opinionated abstractions that users can consume easily, without needing to manage the individual components.
+
+### Example: Using KRO to create an `AgenticSandbox`
+
+#### Install KRO
+
+First, install KRO on your cluster:
+```bash
+dev/tools/install-kro
+```
+
+#### Create RGD
+
+Install the `ResourceGraphDefinition` (RGD) which defines our new `AgenticSandbox` CRD
+
+```bash
+kubectl apply -f examples/composing-sandbox-nw-policies/rgd.yaml
+```
+
+Validate that the RGD is installed correctly:
+
+```bash
+$ kubectl get rgd
+NAME              APIVERSION   KIND             STATE    AGE
+agentic-sandbox   v1alpha1     AgenticSandbox   Active   6m38s
+```
+
+Validate that the new `AgenticSandbox` CRD is installed correctly:
+
+```bash
+$ kubectl get crd
+NAME                                      CREATED AT
+agenticsandboxes.custom.agents.x-k8s.io   2025-09-20T05:03:49Z  # << THIS
+resourcegraphdefinitions.kro.run          2025-09-20T04:35:37Z
+sandboxes.agents.x-k8s.io                 2025-09-19T22:40:05Z
+```
+
+#### Create an `AgenticSandbox`
+
+You can now create an example `AgenticSandbox` resource:
+
+```yaml
+apiVersion: custom.agents.x-k8s.io/v1alpha1
+kind: AgenticSandbox
+metadata:
+  name: demo
+spec:
+  image: nginx
+  service:
+    port: 80
+```
+
+Apply it to the cluster:
+
+```bash
+kubectl apply -f instance.yaml
+```
+
+Check the status of the created resources:
+
+```bash
+kubectl get agenticsandboxes
+kubectl get agenticsandboxes demo -o yaml
+```
+
+The KRO reconciler reconciles `AgenticSandbox` instance and creates the following resources:
+* Sandbox
+* Service
+* NetworkPolicy (if enabled)
+* Ingress (if enbled)
+
+The user/agent can access the Sanbox via the Ingress or the Service as appropriate.
+
+If needed the user can update `AgenticSandbox` instance and reapply.
+
+Once done using the Sandbox, the user can delete the `AgenticSandbox` instance, and KRO will clean up all the resources it created:
+
+```bash
+kubectl delete agenticsandbox demo
+```

site/content/en/docs/guides/gvisor-gke/_index.md

@@ -0,0 +1,72 @@
+---
+title: "gVisor on GKE"
+linkTitle: "gVisor on GKE"
+weight: 2
+description: >
+  This guide shows how to run [Agent Sangbox](https://github.com/kubernetes-sigs/agent-sandbox) with the [gVisor](https://gvisor.dev) runtime using GKE as a cluster.
+---
+
+## Prerequisites
+
+* [gcloud CLI](https://docs.cloud.google.com/sdk/docs/install)
+* [kubectl](https://kubernetes.io/docs/tasks/tools/)
+
+## Create a GKE cluster
+
+Specify your project:
+
+```sh
+export PROJECT_ID=$(gcloud config get project)
+```
+
+Run the following command to create a GKE cluster:
+
+```sh
+gcloud container clusters create demo-gvisor-cluster \
+--location=us-central1-c \
+--project=$PROJECT_ID
+```
+
+Then add a node that supports `gVisor` by running:
+
+```sh
+gcloud container node-pools create gvisor-node-pool \
+--region us-central1-c \
+--cluster=demo-gvisor-cluster \
+--num-nodes=1 \
+--sandbox type=gvisor
+```
+
+To access your cluster run this command:
+
+```sh
+gcloud container clusters get-credentials demo-gvisor-cluster \
+--region us-central1-c \
+--project ${PROJECT_ID}
+```
+
+## Install Sandbox CRD
+
+Run these commands to install `Sandbox CRD`:
+
+```sh
+export VERSION=v0.1.0-rc.0
+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
+```
+
+## Testing
+
+Run this command to create an ampty Sandbox that uses `gVisor` as a RuntimeClass:
+
+```sh
+kubectl apply -f gvisor-empty-sandbox.yaml
+```
+
+## Cleanup
+
+```sh
+gcloud container clusters delete demo-gvisor-cluster \
+		--location=us-central1-c \
+		--project=$PROJECT_ID
+```

site/content/en/docs/guides/gvisor-gke/sandbox-gvisor.yaml

@@ -0,0 +1,42 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: sandbox-ns
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: your-sandbox-sa
+  namespace: sandbox-ns
+---
+apiVersion: agents.x-k8s.io/v1alpha1
+kind: Sandbox
+metadata:
+  name: sandbox-example
+  namespace: sandbox-ns
+spec:
+  podTemplate:
+    metadata:
+      labels:
+        sandbox: my-sandbox
+      annotations:
+        test: "yes"
+    spec:
+      # Each sandboxed pod can use a distinct KSA, then they will have distinct identities
+      runtimeClassName: gvisor
+      serviceAccountName: your-sandbox-sa
+      containers:
+      - name: my-container
+        image: busybox
+        command: ["/bin/sh", "-c", "sleep 3600"]
+        volumeMounts:
+        - name: my-pvc
+          mountPath: /my-data
+  volumeClaimTemplates:
+  - metadata:
+      name: my-pvc
+    spec:
+      accessModes: [ "ReadWriteOnce" ]
+      resources:
+        requests:
+          storage: 1Gi