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 canceled.

Name	Link
🔨 Latest commit	`979e6a3`
🔍 Latest deploy log	https://app.netlify.com/projects/agent-sandbox/deploys/6960f31fd0fe1a0008830195

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

[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 assign justinsb for approval. 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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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 canceled.

Uh oh!

k8s-ci-robot commented Jan 8, 2026

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

netlify bot commented Jan 8, 2026 •

edited

Loading