feat: Add Python Template and Claim Sandbox Example and Python Code execution Client SDK #88

tomergee · 2025-10-11T07:46:53Z

This PR introduces a complete example for creating sandboxes using the SandboxTemplate and SandboxClaim extension resources for Python code execution.
It includes a new Python client SDK (agentic-sandbox-client) that provides a high-level, context-managed interface for creating, interacting with, and cleaning up sandboxes based on Sandbox templates and claims.
The SDK is currently basic and will be expanded in the future.

The run-test-kind.sh script has been updated to use the new sandbox controller extensions for template/claim and to use the Python client sdk. It deploys and cleans everything in one script.

Due to issues testing the new Sandboxtemplate and claim extension - The core of the work involved fixing two key bugs: enabling the extensions controller by default and correcting a field name mismatch in the SandboxClaim CRD (templateRef):

The sandbox-python-claim.yaml was using a field named templateRef to point to the SandboxTemplate.
In extensions/api/v1alpha1/sandboxclaim_types.go, I found that the corresponding field in the SandboxClaimSpec
struct was named sandboxTemplateRef.
To fix this, I modified the Go code to match the YAML - I renamed the TemplateRef field within the SandboxClaimSpec struct and updated its JSON tag from sandboxTemplateRef to templateRef.
In k8s/deployment.yaml I added:
containers:
- name: agent-sandbox-controller
image: ko://sigs.k8s.io/agent-sandbox/cmd/agent-sandbox-controller
args:
- --extensions
So it starts with the extensions enabled and makes it recognize and process the SandboxClaim resource to create the Sandbox pod.

…x example

The first commit's message is: Created a python sandbox example based on sandboxtemplate and sandboxclaim using the controller extensions which can now create a family of python code execution sandboxes. Due to issues testing the new Sandboxtemplate and claim extension I fixed 2 issues below. The second commit's message is: 1. The sandbox-python-claim.yaml was using a field named templateRef to point to the SandboxTemplate. In extensions/api/v1alpha1/sandboxclaim_types.go, I found that the corresponding field in the SandboxClaimSpec struct was named sandboxTemplateRef. To fix this, I modified the Go code to match the YAML - I renamed the TemplateRef field within the SandboxClaimSpec struct and updated its JSON tag from sandboxTemplateRef to templateRef. 2. In k8s/deployment.yaml I added: containers: - name: agent-sandbox-controller image: ko://sigs.k8s.io/agent-sandbox/cmd/agent-sandbox-controller args: - --extensions So it starts with the extensions enabled and makes it recognize and process the SandboxClaim resource to create the Sandbox pod.

… sandboxes and run python code in them using the agent sandbox controller with Sandboxclaim and Sandboxtemplate extension. Added python packaging files to make the client installable with pip. Added a test script that installs the client and runs it against the sandbox in kind. Updated the run-test-kind.sh script to use the new client Now you have a complete client server python code executor on k8s using the agent sandbox controller.

… showing inner information

k8s-ci-robot · 2025-10-11T07:46:59Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: tomergee
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.

Needs approval from an approver in each of these files:

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 · 2025-10-11T07:47:03Z

Hi @tomergee. 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.

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.

netlify · 2025-10-11T07:47:25Z

✅ Deploy Preview for agent-sandbox canceled.

Name	Link
🔨 Latest commit	`43bafca`
🔍 Latest deploy log	https://app.netlify.com/projects/agent-sandbox/deploys/690a46b63848e50008871343

…sandbox client (the previous version did not show the correct functionality) corrected some previous tests in the python test_client.py that were not pushed to the repo

k8s/crds/extensions.agents.x-k8s.io_sandboxclaims.yaml

k8s/deployment.yaml

k8s/crds/extensions.agents.x-k8s.io_sandboxclaims.yaml

k8s/crds/extensions.agents.x-k8s.io_sandboxtemplates.yaml

examples/python-template-sandbox/run-test-kind.sh

janetkuo · 2025-10-21T16:14:33Z

/ok-to-test

examples/python-template-sandbox/agentic-sandbox-client/agentic_sandbox.egg-info/PKG-INFO

Reverted templateRef and fixed refrences to sandboxTemplateRef in k8s/crds/extensions.agents.x-k8s.io_sandboxclaims.yaml sandboxclaim_types.go and sandbox.py client

…he Sandbox controller as an extention to Gemini CLI. Updated license to Apache-2.0 in several files.

…ment file reverted deployment file changes to allow deploying controller without extentions

…tes.yaml after pending bug fix in PR kubernetes-sigs#122 which will support copying over labels and annotations from Sandboxtemplate

k8s/extensions.deployment.yaml

janetkuo

Given that the SDK uses a bunch of extensions features, please move examples/python-template-sandbox/* to be under extensions/examples

janetkuo

@tomergee

Given the upcoming KubeCon announcement, it would be great to get the Python SDK merged and released as quickly as possible. I'd like to suggest splitting this pull request into smaller, more focused PRs:

Python SDK PR: only includes the agentic-sandbox-client/. This is the core piece of functionality that we need for the announcement.
Clear README.md: Update the README.md in the agentic-sandbox-client/ to be more focused on the SDK's usage, with a clear example. The current README.md is a bit dense, and a simpler version would be more user-friendly for people learning about the project at KubeCon, such as:

# Agentic Sandbox Python Client

This Python client provides a simple, high-level interface for creating and interacting with sandboxes managed by the Agent Sandbox controller.

## Usage

### Prerequisites

*   A running Kubernetes cluster (e.g., `kind`).
*   The Agent Sandbox controller must be deployed with the extensions feature enabled. (--> point to the Sandbox installation guide)
*   A `SandboxTemplate` resource must be created in the cluster.

### Installation

Install the client ...

### Example 

(some Python example usage of the SDK)

For more detailed examples, please see test_client.py.

(Move the detailed "How It Works" and "Testing" sections to the end of README.)

Follow-up PRs: The python-runtime-sandbox and tools/run_in_sandbox can be submitted as separate pull requests after the client is merged. These don't need to be merged before KubeCon.

justinsb · 2025-11-05T18:18:07Z

examples/python-template-sandbox/agentic-sandbox-client/.gitignore

@@ -0,0 +1 @@
+build/\nvenv/\n


Should those \n be newlines?

justinsb · 2025-11-05T18:19:33Z

examples/python-template-sandbox/agentic-sandbox-client/README.md

@@ -0,0 +1,114 @@
+# Agentic Sandbox Python Client


So this is duplicated into egg-info (I believe). I'm not very familiar with checking in egg-info. Which one is the source of truth? Can we use a symlink or a script to avoid them drifting? (Or some other approach?)

justinsb · 2025-11-05T18:21:49Z

examples/python-template-sandbox/python-runtime-sandbox/tester.py

+    port = sys.argv[2]
+    base_url = f"http://{ip}:{port}"
+
+    test_health_check(base_url)


Is there a python testing library we use in kube? (Not a blocker)

justinsb · 2025-11-05T18:23:31Z

examples/python-template-sandbox/main.py

+from fastapi.responses import FileResponse, JSONResponse
+from pydantic import BaseModel
+
+class ExecuteRequest(BaseModel):


This file looks very similar to examples/python-template-sandbox/python-runtime-sandbox/main.py, what's the difference?

justinsb · 2025-11-05T18:24:52Z

examples/python-template-sandbox/run-test-kind.sh

@@ -0,0 +1,62 @@
+#!/bin/bash


Can we make sure that we actually run this test in prow?

justinsb · 2025-11-05T18:25:14Z

examples/python-template-sandbox/tester.py

@@ -0,0 +1,66 @@
+# Copyright 2025 The Kubernetes Authors.


Is this file a dup also?

justinsb · 2025-11-05T18:26:46Z

I did read through the PR, it seems fine to me particularly if we can plug it in to prow or github actions testing. I do think there are some duplicated files though, which I think might be accidental, and I would like to figure out if we can avoid duplicating files into egg-info.

tomergee added 4 commits October 11, 2025 06:22

feat(python-template-sandbox): add and fix the python-template-sandbo…

09e0844

…x example

Added a more meaningful python test with introspection on the sandbox…

58f4f34

… showing inner information

k8s-ci-robot requested a review from justinsb October 11, 2025 07:46

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Oct 11, 2025

k8s-ci-robot requested a review from soltysh October 11, 2025 07:46

k8s-ci-robot added the needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. label Oct 11, 2025

k8s-ci-robot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Oct 11, 2025

Fixed issues in run-test-kind.sh to show the correct workflow of the …

f75886b

…sandbox client (the previous version did not show the correct functionality) corrected some previous tests in the python test_client.py that were not pushed to the repo

vicentefb reviewed Oct 20, 2025

View reviewed changes

k8s/crds/extensions.agents.x-k8s.io_sandboxclaims.yaml Outdated Show resolved Hide resolved

tomergee requested a review from vicentefb October 20, 2025 21:45

vicentefb suggested changes Oct 21, 2025

View reviewed changes

k8s-ci-robot 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 Oct 21, 2025

janetkuo reviewed Oct 21, 2025

View reviewed changes

examples/python-template-sandbox/agentic-sandbox-client/agentic_sandbox.egg-info/PKG-INFO Outdated Show resolved Hide resolved

tomergee added 5 commits October 22, 2025 05:50

Applied license boilerplate and updated to Apache-2.0 in several files.

806c05e

Reverted templateRef and fixed refrences to sandboxTemplateRef in k8s/crds/extensions.agents.x-k8s.io_sandboxclaims.yaml sandboxclaim_types.go and sandbox.py client

Merge branch 'kubernetes-sigs:main' into python-template-sandbox

5a47f92

Gemini CLI extention - Added tools folder with run_in_sandbox using t…

2664ae8

…he Sandbox controller as an extention to Gemini CLI. Updated license to Apache-2.0 in several files.

created extentions deployment file instead of editing existing deploy…

495b00a

…ment file reverted deployment file changes to allow deploying controller without extentions

Reverted changes to k8s/crds/extensions.agents.x-k8s.io_sandboxtempla…

eb0e440

…tes.yaml after pending bug fix in PR kubernetes-sigs#122 which will support copying over labels and annotations from Sandboxtemplate

janetkuo reviewed Nov 4, 2025

View reviewed changes

k8s/extensions.deployment.yaml Show resolved Hide resolved

janetkuo reviewed Nov 4, 2025

View reviewed changes

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Nov 4, 2025

tomergee added 2 commits November 4, 2025 09:59

Delete k8s/extensions.deployment.yaml

cf194e5

Delete k8s/deployment.yaml

a29b636

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Nov 4, 2025

Merge branch 'kubernetes-sigs:main' into python-template-sandbox

43bafca

janetkuo reviewed Nov 5, 2025

View reviewed changes

justinsb reviewed Nov 5, 2025

View reviewed changes

janetkuo mentioned this pull request Nov 5, 2025

feat: Agentic Sandbox Client Python #134

Merged

		@@ -0,0 +1 @@
		build/\nvenv/\n

feat: Add Python Template and Claim Sandbox Example and Python Code execution Client SDK #88

Are you sure you want to change the base?

feat: Add Python Template and Claim Sandbox Example and Python Code execution Client SDK #88

Conversation

tomergee commented Oct 11, 2025

Uh oh!

k8s-ci-robot commented Oct 11, 2025

Uh oh!

k8s-ci-robot commented Oct 11, 2025

Uh oh!

netlify bot commented Oct 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for agent-sandbox canceled.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

janetkuo commented Oct 21, 2025

Uh oh!

Uh oh!

Uh oh!

janetkuo left a comment

Choose a reason for hiding this comment

Uh oh!

janetkuo left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

justinsb Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

justinsb Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

justinsb Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

justinsb Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

justinsb Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

justinsb Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

justinsb commented Nov 5, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

netlify bot commented Oct 11, 2025 •

edited

Loading

janetkuo left a comment •

edited

Loading