Fixes agent sandbox python connection failure when using runtime=runsc (#159)

* Fixes agent sandbox python connection failure when using runtime=runsc

* Updates READMEs

* the client accepts api url for internal traffic and devs, namespace isolation and retries

* added back _start_and_wait_for_port_forward for dev mode

updated README

* Updates the Readme

Breaks out the Gateway Resources from the Router resources

---------

Co-authored-by: Vicente Ferrara <[email protected]>

Author: igooch

.gitignore

@@ -7,4 +7,8 @@ bin/
 .netlify
 # Added by goreleaser init:
 dist/
-release_assets/
+release_assets/
+
+# Temporary folders
+tmp/
+temp/

clients/python/agentic-sandbox-client/README.md

@@ -1,92 +1,137 @@
 # Agentic Sandbox Client Python
 
-This Python client provides a simple, high-level interface for creating and interacting with sandboxes managed by the Agent Sandbox controller. It's designed to be used as a context manager, ensuring that sandbox resources are properly created and cleaned up.
+This Python client provides a simple, high-level interface for creating and interacting with
+sandboxes managed by the Agent Sandbox controller. It's designed to be used as a context manager,
+ensuring that sandbox resources are properly created and cleaned up.
 
-## Usage
+It supports a **scalable, cloud-native architecture** using Kubernetes Gateways and a specialized
+Router, while maintaining a convenient **Developer Mode** for local testing.
 
-### Prerequisites
+## Architecture
 
-- A running Kubernetes cluster (e.g., `kind`).
-- The Agent Sandbox controller must be deployed with the extensions feature enabled.
-- A `SandboxTemplate` resource must be created in the cluster.
-- The `kubectl` command-line tool must be installed and configured to connect to your cluster.
+The client operates in two modes:
 
-### Installation
+1.  **Production (Gateway Mode):** Traffic flows from the Client -> Cloud Load Balancer (Gateway)
+    -> Router Service -> Sandbox Pod. This supports high-scale deployments.
+2.  **Development (Tunnel Mode):** Traffic flows from Localhost -> `kubectl port-forward` -> Router
+    Service -> Sandbox Pod. This requires no public IP and works on Kind/Minikube.
+3.  **Advanced / Internal Mode**: The client connects directly to a provided api_url, bypassing
+    discovery. This is useful for in-cluster communication or when connecting through a custom domain.
+
+## Prerequisites
+
+- A running Kubernetes cluster.
+- The **Agent Sandbox Controller** installed.
+- `kubectl` installed and configured locally.
+
+## Setup: Deploying the Router
+
+Before using the client, you must deploy the `sandbox-router`. This is a one-time setup.
+
+1.  **Build and Push the Router Image:**
+
+    For both Gateway Mode and Tunnel mode, follow the instructions in [sandbox_router](sandbox_router/README.md)
+    to build, push, and apply the router image and resources.
+
+2.  **Create a Sandbox Template:**
+
+    Ensure a `SandboxTemplate` exists in your target namespace. The [test_client.py](test_client.py)
+    uses the [python-runtime-sandbox](../../../examples/python-runtime-sandbox/) image.
 
-1.  **Create a virtual environment:**
     ```bash
-    python3 -m venv .venv
+    kubectl apply -f python-sandbox-template.yaml
     ```
-2.  **Activate the virtual environment:**
+
+## Installation
+
+1.  **Create a virtual environment:**
+
     ```bash
+    python3 -m venv .venv
     source .venv/bin/activate
     ```
-3. **Option 1: Install from source via git:**
-    ```bash
-    # Replace "main" with a specific version tag (e.g., "v0.1.0") from 
-    # https://github.com/kubernetes-sigs/agent-sandbox/releases to pin a version tag.
-    export VERSION="main"
 
-    pip install "git+https://github.com/kubernetes-sigs/agent-sandbox.git@${VERSION}#subdirectory=clients/python/agentic-sandbox-client"
-    ```
-4. **Option 2: Install from source in editable mode:**
+2.  **Install the package:**
     ```bash
-    git clone https://github.com/kubernetes-sigs/agent-sandbox.git
-    cd agent-sandbox/clients/agentic-sandbox-client-python
-    cd ~/path_to_venv
     pip install -e .
     ```
 
-### Example:
+## Usage Examples
+
+### 1. Production Mode (GKE Gateway)
+
+Use this when running against a real cluster with a public Gateway IP. The client automatically
+discovers the Gateway.
 
 ```python
 from agentic_sandbox import SandboxClient
 
-with SandboxClient(template_name="sandbox-python-template", namespace="default") as sandbox:
-    result = sandbox.run("echo 'Hello, World!'")
-    print(result.stdout)
+# Connect via the GKE Gateway
+with SandboxClient(
+    template_name="python-sandbox-template",
+    gateway_name="external-http-gateway",  # Name of the Gateway resource
+    namespace="default"
+) as sandbox:
+    print(sandbox.run("echo 'Hello from Cloud!'").stdout)
 ```
 
-## How It Works
+### 2. Developer Mode (Local Tunnel)
 
-The `SandboxClient` client automates the entire lifecycle of a temporary sandbox environment:
+Use this for local development or CI. If you omit `gateway_name`, the client automatically opens a
+secure tunnel to the Router Service using `kubectl`.
 
-1.  **Initialization (`with SandboxClient(...)`):** The client is initialized with the name of the `SandboxTemplate` you want to use and the namespace where the resources should be created:
+```python
+from agentic_sandbox import SandboxClient
 
-    -   **`template_name` (str):** The name of the `SandboxTemplate` resource to use for creating the sandbox.
-    -   **`namespace` (str, optional):** The Kubernetes namespace to create the `SandboxClaim` in. Defaults to "default". 
-    -   When you create a `SandboxClient` instance within a `with` block, it initiates the process of creating a sandbox.
-2.  **Claim Creation:** It creates a `SandboxClaim` Kubernetes resource. This claim tells the agent-sandbox controller to provision a new sandbox using a predefined `SandboxTemplate`.
-3.  **Waiting for Readiness:** The client watches the Kubernetes API for the corresponding `Sandbox` resource to be created and become "Ready". This indicates that the pod is running and the server inside is active.
-4.  **Port Forwarding:** Once the sandbox pod is ready, the client automatically starts a `kubectl port-forward` process in the background. This creates a secure tunnel from your local machine to the sandbox pod, allowing you to communicate with the server running inside.
-5.  **Interaction:** The `SandboxClient` object provides three main methods to interact with the running sandbox:
-    *   `run(command)`: Executes a shell command inside the sandbox.
-    *   `write(path, content)`: Uploads a file to the sandbox.
-    *   `read(path)`: Downloads a file from the sandbox.
-6.  **Cleanup (`__exit__`):** When the `with` block is exited (either normally or due to an error), the client automatically cleans up all resources. It terminates the `kubectl port-forward` process and deletes the `SandboxClaim`, which in turn causes the controller to delete the `Sandbox` pod.
+# Automatically tunnels to svc/sandbox-router-svc
+with SandboxClient(
+    template_name="python-sandbox-template",
+    namespace="dev"
+) as sandbox:
+    print(sandbox.run("echo 'Hello from Local!'").stdout)
+```
 
+### 3. Advanced / Internal Mode
 
-## How to Test the Client
+Use `api_url` to bypass discovery entirely. Useful for:
 
-A test script, `test_client.py`, is included to verify the client's functionality.
-You should see output indicating that the tests for command execution and file operations have passed.
+- **Internal Agents:** Running inside the cluster (connect via K8s DNS).
+- **Custom Domains:** Connecting via HTTPS (e.g., `https://sandbox.acme.com`).
 
-## Packaging and Installation
+```python
+with SandboxClient(
+    template_name="python-sandbox-template",
+    # Connect directly to a URL
+    api_url="[http://sandbox-router-svc.default.svc.cluster.local:8080](http://sandbox-router-svc.default.svc.cluster.local:8080)",
+    namespace="dev"
+) as sandbox:
+    sandbox.run("ls -la")
+```
 
-This client is configured as a standard Python package using `pyproject.toml`.
+### 4. Custom Ports
 
-### Prerequisites
+If your sandbox runtime listens on a port other than 8888 (e.g., a Node.js app on 3000), specify `server_port`.
 
--   Python 3.7+
--   `pip`
--   `build` (install with `pip install build`)
+```python
+with SandboxClient(
+    template_name="node-sandbox-template",
+    server_port=3000
+) as sandbox:
+    # ...
+```
 
-### Building the Package
+## Testing
 
-To build the package from the source, navigate to the `agentic-sandbox-client` directory and run the following command:
+A test script is included to verify the full lifecycle (Creation -> Execution -> File I/O -> Cleanup).
 
-```bash
-python -m build
+### Run in Dev Mode:
+
+```
+python test_client.py --namespace default
 ```
 
-This will create a `dist` directory containing the packaged distributables: a `.whl` (wheel) file and a `.tar.gz` (source archive).
+### Run in Production Mode:
+
+```
+python test_client.py --gateway-name external-http-gateway
+```