Agent Sandbox

Python Runtime Sandbox

This guide documents the complete setup and deployment of a Python Runtime that runs locally on Kubernetes using Kind (Kubernetes in Docker) with the agent-sandbox controller.

This example implements a simple Python server in a sandbox container. It includes a FastAPI server that can execute commands and a Python script to test it (tester.py).

Test it out by running run-test-docker: It will build a (local) container image containing the python server,run it, then execute tester.py to test the running container and a cleanup.

The tester.py script acts as a client to interact with the python API server, sending a command to the /execute endpoint and printing the standard output, standard error, and exit code from the response.

Usage: python tester.py [ip] [port]

Python Classes in main.py

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

Configuration

  • SANDBOX_EXEC_TIMEOUT_SECONDS: Maximum time, in seconds, a command submitted to /execute is allowed to run before it (and any processes it spawned) are killed and the request reports a failed execution. Defaults to 300. If set to a value that isn’t a finite number greater than 0, the default is used instead and a warning is logged.

Testing on a local kind cluster using agent-sandbox

To test the sandbox on a local kind cluster, you can use the run-test-kind.sh script. This script will:

  1. Create a kind cluster (if it doesn’t exist).
  2. Build and deploy the agent sandbox controller to the cluster.
  3. Build the python runtime sandbox image.
  4. Load the image into the kind cluster.
  5. Deploy the sandbox and run the tests using examples/python-runtime-sandbox/sandbox-python-kind.yaml
  6. Clean up all the resources.

To run the script:

./run-test-kind.sh
Last modified April 2, 2026: Website reorg + fixing all the links (#257) (c3c9f03)