Initial push for quickstart example #237

alex-akv · 2026-01-08T16:30:39Z

This quickstart example includes setting up Agent Sandbox with Warmpool and Python SDK using one of the two isolation strategies (gVisor on KIND | Kata Containers on minikube).

netlify · 2026-01-08T16:30:45Z

✅ Deploy Preview for agent-sandbox ready!

Name	Link
🔨 Latest commit	`9502c20`
🔍 Latest deploy log	https://app.netlify.com/projects/agent-sandbox/deploys/696f4be53cecea000848cf0a
😎 Deploy Preview	https://deploy-preview-237--agent-sandbox.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

k8s-ci-robot · 2026-01-08T16:30:49Z

Hi @alex-akv. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

barney-s · 2026-01-08T18:10:00Z

examples/quickstart/README.md

@@ -0,0 +1,875 @@
+# Agent Sandbox Quickstart


I would rename this to Secure Agent Sandbox Quickstart.

We also have a #220 simple example.

Renamed in commit: 979e6a3

barney-s · 2026-01-08T21:04:32Z

examples/quickstart/README.md

+- **Python SDK**: Programmatic sandbox management
+- **Router Service**: HTTP proxy for SDK communication
+
+---


Can this be a separate file instead of being inline here ?
Is there a reason there is a file separator here.

You're right, we don't need separator there. I have removed it in the commit: 979e6a3

Since this is a large file. Would it make sense to split it into 3. The first file acting as a index for

gVisor on KIND << separate file for this
2 Kata Containers on minikube << and this

Split into 3 files in commit: 9502c20

barney-s · 2026-01-08T21:05:12Z

examples/quickstart/README.md

+
+**Continue to "Common Setup Steps" below**
+
+---


same Q about yaml file separator. If this is meant for a doc-processor, would it work with multiple files instead of a single file separated by this ?

We don't need separator there. Addressed it in commit: 979e6a3

barney-s · 2026-01-09T18:26:15Z

if possible can we split it into 3 files ?

index file with common setup/pre-reqs
gVisor on KIND
Kata Containers on minikube

barney-s

Great work on this detailed quickstart! It provides a clear path for users to try out the Agent Sandbox.

My review focuses on:

Robustness: Improving the shell commands and Python script to handle edge cases and race conditions.
Safety: Reducing the risk of aggressive commands like pkill and rm affecting the user's environment.
Maintainability: Avoiding hardcoded version numbers and ensuring instructions don't rot quickly.

barney-s · 2026-01-10T19:56:46Z

examples/quickstart/README.md

+- KIND (0.20+)
+- Python 3.9+
+- Git
+- Linux host (gVisor requires Linux)


wget is used in the installation steps but not listed in the prerequisites. Consider adding it or offering a curl alternative.

Added it as prerequisite in commit: 7a6ea0d

barney-s · 2026-01-10T19:56:46Z

examples/quickstart/README.md

+    ${URL}/containerd-shim-runsc-v1 ${URL}/containerd-shim-runsc-v1.sha512
+  sha512sum -c runsc.sha512 \
+    -c containerd-shim-runsc-v1.sha512
+  rm -f *.sha512


rm -f *.sha512 in the current directory is risky if the user runs this in a directory with other files. Suggest creating a temporary directory for downloads or being more specific with the removal pattern.

Modifed the solution to remove files explicitly in commit: 7a6ea0d

barney-s · 2026-01-10T19:56:46Z

examples/quickstart/README.md

+    -c containerd-shim-runsc-v1.sha512
+  rm -f *.sha512
+  chmod a+rx runsc containerd-shim-runsc-v1
+  sudo mv runsc containerd-shim-runsc-v1 /usr/local/bin


The script uses sudo to move binaries. It's good practice to warn the user that root privileges will be required for this step.

Explained that root privs are required on top of the step in commit: 7a6ea0d

barney-s · 2026-01-10T19:56:47Z

examples/quickstart/README.md

+Configure the KIND cluster's containerd to support the gVisor runtime:
+
+```bash
+docker exec -it agent-sandbox-demo-control-plane bash -c 'cat <<EOF > /etc/containerd/config.toml


Overwriting /etc/containerd/config.toml completely using cat > can break existing KIND configurations (e.g., registry mirrors). While acceptable for a demo, a warning or a sed based approach would be safer.

Added a warning in commit: 7a6ea0d

barney-s · 2026-01-10T19:56:47Z

examples/quickstart/README.md

+# Start minikube with containerd runtime
+minikube start \
+  --driver=kvm2 \
+  --container-runtime=containerd \


8192MB (8GB) of RAM is a significant requirement for a quickstart. If Kata requires this much, please highlight this hard requirement in the prerequisites section so users don't fail halfway through.

Added requirements and explanation in commit: 7a6ea0d

barney-s · 2026-01-10T19:56:47Z

examples/quickstart/README.md

+```bash
+# Check router pods
+kubectl get pods -l app=sandbox-router
+


pkill -f "port-forward ..." is quite aggressive and might terminate other unrelated port-forward sessions running on the user's machine. Consider tracking the specific PID or warning the user.

Modified the approach in commit: 7a6ea0d

barney-s · 2026-01-10T19:56:47Z

examples/quickstart/README.md

+kubectl port-forward svc/sandbox-router-svc 8080:8080 &
+sleep 2
+curl http://localhost:8080/healthz
+# Should return: {"status":"ok"}


Creating the venv in ~/agent-sandbox-venv modifies the user's home directory structure. Standard practice is often to create it in the current directory (e.g., python3 -m venv .venv) or let the user decide the location.

Modified the approach in commit: 7a6ea0d

barney-s · 2026-01-10T19:56:47Z

examples/quickstart/README.md

+
+def setup_portforward():
+    global portforward_proc, local_port
+


time.sleep(3) is brittle. It would be better to read the stdout of the portforward_proc process and wait for the "Forwarding from" line to confirm the tunnel is ready.

Addressed in commit: 7a6ea0d

barney-s · 2026-01-10T19:56:47Z

examples/quickstart/README.md

+  sandboxTemplateRef:
+    name: python-runtime-template
+EOF
+


chmod +x is redundant here since the next instruction runs the script explicitly with python3.

Removed the chmod in commit: 7a6ea0d

barney-s · 2026-01-10T19:56:47Z

examples/quickstart/README.md

+kubectl apply -f - <<EOF
+apiVersion: extensions.agents.x-k8s.io/v1alpha1
+kind: SandboxTemplate
+metadata:


The guide assumes the default namespace everywhere. While fine for a quickstart, explicitly creating a dedicated namespace (e.g., agent-sandbox-demo) makes cleanup easier (just delete the namespace) and avoids cluttering default.

Switched from using default to agent-sandbox-demo dedicated namespace and modified cleanup steps in commit: 7a6ea0d

alex-akv · 2026-01-20T09:34:22Z

if possible can we split it into 3 files ?

index file with common setup/pre-reqs

gVisor on KIND

Kata Containers on minikube

@barney-s Split into 3 files in commit: 9502c20

barney-s · 2026-02-10T18:14:06Z

/lgtm
happy to merge and refine

janetkuo · 2026-02-11T23:57:55Z

examples/quickstart/README.md

+
+```bash
+git clone https://github.com/kubernetes-sigs/agent-sandbox.git
+cd agent-sandbox/examples/python-runtime-sandbox


Users can use prebuilt staging images to avoid the need to build images locally.

us-central1-docker.pkg.dev/k8s-staging-images/python-runtime-sandbox
us-central1-docker.pkg.dev/k8s-staging-images/sandbox-router

janetkuo · 2026-02-11T23:58:55Z

examples/quickstart/README.md

+- `gvisor` if you're using **gVisor on KIND**
+- `kata-qemu` if you're using **Kata Containers on minikube**
+
+```bash


Please turn this into an env var

Suggested change

```bash

```bash

# Set the runtime based on your choice

export RUNTIME_CLASS_NAME=gvisor # or 'kata-qemu'

janetkuo · 2026-02-11T23:59:17Z

examples/quickstart/README.md

+      labels:
+        sandbox: python-sandbox
+    spec:
+      runtimeClassName: <RUNTIME_CLASS_NAME>  # Replace with 'gvisor' or 'kata-qemu'


Suggested change

runtimeClassName: <RUNTIME_CLASS_NAME> # Replace with 'gvisor' or 'kata-qemu'

runtimeClassName: ${RUNTIME_CLASS_NAME}

janetkuo · 2026-02-12T00:00:39Z

examples/quickstart/gvisor.md

+```bash
+# WARNING: This overwrites the entire containerd config.
+# If you have existing KIND configurations (e.g., registry mirrors),
+# consider backing up /etc/containerd/config.toml first.


While there's a warning, overwriting a system-critical file in a docker exec session is an anti-pattern for Kubernetes infrastructure automation. It can lead to NodeNotReady status if KIND-specific networking or mirror configurations are lost. Instead of a manual docker exec and systemctl restart, use the KIND-native way to configure runtimes during cluster creation, via containerdConfigPatches in the initial KIND cluster configuration file.

janetkuo · 2026-02-12T00:02:09Z

examples/quickstart/gvisor.md

+(
+  set -e
+  ARCH=$(uname -m)
+  URL=https://storage.googleapis.com/gvisor/releases/release/latest/${ARCH}


It's better to pin to a specific version for a reproducible quickstart

janetkuo · 2026-02-12T00:03:07Z

examples/quickstart/README.md

+    import threading
+    def read_output():
+        for line in portforward_proc.stdout:
+            if "Forwarding from" in line:


There's no mechanism to stop the loop if the process fails to start or outputs an error. This could lead to orphaned threads if the port-forward fails.

janetkuo · 2026-02-12T00:05:03Z

examples/quickstart/gvisor.md

+[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc]
+  runtime_type = "io.containerd.runc.v2"
+[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runsc]
+  runtime_type = "io.containerd.runsc.v1"


Why is runsc.v1 specified, instead of shim-v2?

janetkuo · 2026-02-12T00:06:33Z

examples/quickstart/gvisor.md

+Cleaning up port-forward...
+```
+
+**Note:** Test 4 is optional and may occasionally fail if port-forward becomes unstable. Tests 1-3 are the critical validations - they prove WarmPool and SDK work correctly.


Test 4 waits for the tunnel to be ready. Does this note need to be updated?

k8s-ci-robot · 2026-02-12T00:06:48Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: alex-akv
Once this PR has been reviewed and has the lgtm label, please ask for approval from barney-s. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

examples/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

Initial push for quickstart example

7d8b48d

k8s-ci-robot requested review from janetkuo and justinsb January 8, 2026 16:30

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Jan 8, 2026

k8s-ci-robot added the size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. label Jan 8, 2026

barney-s reviewed Jan 8, 2026

View reviewed changes

Minor changes to the docs

979e6a3

barney-s reviewed Jan 10, 2026

View reviewed changes

alex-akv added 3 commits January 13, 2026 21:41

Modifying the guide for PR comment resolution

7a6ea0d

Adding helm as prerequisite

9800580

Splitting the guide

9502c20

k8s-ci-robot added size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. and removed size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Jan 20, 2026

janetkuo added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Jan 30, 2026

k8s-ci-robot assigned barney-s Feb 10, 2026

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Feb 10, 2026

janetkuo requested changes Feb 12, 2026

View reviewed changes

-```bash
+```bash
+# Set the runtime based on your choice
+export RUNTIME_CLASS_NAME=gvisor  # or 'kata-qemu'

	runtimeClassName: <RUNTIME_CLASS_NAME> # Replace with 'gvisor' or 'kata-qemu'
	runtimeClassName: ${RUNTIME_CLASS_NAME}

Initial push for quickstart example #237

Are you sure you want to change the base?

Initial push for quickstart example #237

Conversation

alex-akv commented Jan 8, 2026

Uh oh!

netlify bot commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for agent-sandbox ready!

Uh oh!

k8s-ci-robot commented Jan 8, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

barney-s commented Jan 9, 2026

Uh oh!

barney-s left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alex-akv commented Jan 20, 2026

Uh oh!

barney-s commented Feb 10, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

netlify bot commented Jan 8, 2026 •

edited

Loading