k8s-agent-sandbox-awx

A broker-backed, kubeconfig-free overlay for the Agentic Sandbox client. It adds a BrokerSandboxClient that drives the sandbox control plane (create → wait ready → terminate, commands, and files) through one identity broker service over HTTPS instead of the Kubernetes API or a public router. The broker proxies authorized data operations to its internal router, so client applications need no kubeconfig and no direct Kubernetes or router access.

# Available after the 0.5.0 wheel is published.
pip install k8s-agent-sandbox-awx==0.5.0

from k8s_agent_sandbox_awx import Sandbox

sandbox = Sandbox.create()
result = sandbox.commands.run('echo "Hello from Agent Sandbox!"')
print(result.stdout)
sandbox.kill()

How it works

The client presents an audience-bound Kubernetes or GitLab OIDC token to the broker. The broker cryptographically verifies the caller from that token, creates the SandboxClaim under its own identity, and stamps the verified caller identity onto the claim — attribution the client cannot forge.

Set both broker_url and api_url to the broker URL. The model rejects a different api_url to prevent accidental direct-router bypass.

This package is a purely additive overlay: it builds on k8s-agent-sandbox-base (a seamed re-publish of the upstream client) and edits zero upstream files. The import package is k8s_agent_sandbox_awx.

Configuration

The zero-argument API reads:

Kubernetes normally needs no Python authentication code:

from k8s_agent_sandbox_awx import Sandbox

with Sandbox.create() as sandbox:
    print(sandbox.commands.run("python3 -c 'print(6 * 7)'").stdout)

Mount a projected ServiceAccount token at the configured path with its audience set to the broker URL. The file is re-read on every request so token rotation is honored.

GitLab supplies the same zero-argument API using a native ID token:

job:
  id_tokens:
    AGENT_SANDBOX_TOKEN:
      aud: https://sandbox-broker.example
  variables:
    AGENT_SANDBOX_BROKER_URL: https://sandbox-broker.example
  script:
    - python app.py

Explicit authentication objects are available when environment discovery is not appropriate:

from k8s_agent_sandbox_awx import KubernetesAuth, OIDCTokenAuth, Sandbox

k8s = Sandbox.create(auth=KubernetesAuth("/var/run/secrets/tokens/broker"))
ci = Sandbox.create(auth=OIDCTokenAuth.from_env("MY_ID_TOKEN"))

The SDK deliberately has no provider="gitlab" or provider="kubernetes" switch. It transports the token; the broker derives the provider from the verified issuer and applies the matching policy.

Requirements

• A deployed identity broker service reachable over HTTPS.
• An OIDC token whose audience matches the broker's. Kubernetes projected tokens and GitLab id_tokens: are supported by the broker policy.
• k8s-agent-sandbox-base (installed automatically as a dependency).

License

Apache-2.0 — see LICENSE.