---
id: k8s-agent-sandbox
version: "0.5.5"
license: unclear
license_treatment: permissive
maintenance: active
---

# k8s-agent-sandbox — A client library to interact with the Agentic Sandbox on Kubernetes.

License: permissive · Maintenance: active · Downloads: 648.8K/mo

## What it is and what it does

k8s-agent-sandbox is a Python client for the Kubernetes Agent Sandbox Controller, enabling you to programmatically create, configure, and tear down isolated sandbox environments running inside a Kubernetes cluster. It abstracts away the complexity of pod lifecycle management and networking by providing a high-level interface that works as a context manager, ensuring proper resource cleanup.

The client supports four connection modes: Gateway Mode for production cloud deployments with load balancing, Tunnel Mode for local development via kubectl port-forward, In-Cluster Mode for workloads running inside the cluster that connect directly to sandbox pods, and Advanced Mode for custom networking scenarios. It depends on kubernetes, requests, pydantic, and prometheus-client, and includes optional async support for integration with async frameworks like FastAPI.

Use it for:

- Local development and testing of agent code against isolated sandbox environments without needing a public cloud deployment.
- Production agent orchestration on GKE or other managed Kubernetes services using the Gateway Mode for high-scale, load-balanced sandbox provisioning.
- CI/CD pipelines that need to spin up ephemeral, isolated execution environments for testing untrusted or experimental code.
- In-cluster agent workloads that spawn child sandboxes for subtasks, communicating directly via cluster DNS.
- Custom networking scenarios where sandboxes are accessed through a specific domain or manually configured router URL.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A Python client library for creating and managing isolated sandbox environments on Kubernetes clusters, supporting multiple connection modes from local development to production cloud deployments.

Yes. The package is actively maintained with no known vulnerabilities, has low install friction, and fills a clear need for Kubernetes-native sandbox management. Install it if you are building agents or orchestration tools on Kubernetes and need reliable, scalable sandbox lifecycle management. The permissive Apache license and recent release cadence make it a safe production dependency.

## Install

pip install k8s-agent-sandbox
uv add k8s-agent-sandbox
poetry add k8s-agent-sandbox

## Installing k8s-agent-sandbox

Before you install: Low install friction with a pure-Python wheel distribution. The package is actively maintained with a recent release and no known vulnerabilities. Runtime dependencies are standard and widely available (kubernetes, requests, pydantic, prometheus-client).

License in practice: Licensed under Apache Software License (permissive), allowing commercial and private use with minimal restrictions.

Quickstart:

pip install k8s-agent-sandbox

from k8s_agent_sandbox import SandboxClient
from k8s_agent_sandbox.models import SandboxLocalTunnelConnectionConfig

client = SandboxClient(connection_config=SandboxLocalTunnelConnectionConfig())
sandbox = client.create_sandbox(warmpool="python-sandbox-warmpool", namespace="default")
try:
    result = sandbox.commands.run("echo 'Hello'")
finally:
    sandbox.terminate()

Requires a running Kubernetes cluster with the Agent Sandbox Controller installed and a deployed sandbox-router service; kubectl must be configured locally.

Verify before relying:

- Whether optional tracing dependencies (GCP OpenTelemetry integration) are production-ready or experimental.
- Performance characteristics and latency overhead of the four connection modes under load.
- Whether the async client API is feature-complete relative to the synchronous client.

## Package facts

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 648.8K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

kubernetes sandbox client, agent sandbox python, k8s isolated execution environment, containerized sandbox management, kubernetes pod sandbox api, agent runtime sandbox, k8s workload isolation, kubernetes, agent-orchestration, sandbox-isolation

[View on SkillFed](https://skillfed.io/packages/k8s-agent-sandbox) · [View on PyPI](https://pypi.org/project/k8s-agent-sandbox/)