Metadata-Version: 2.4
Name: k8s-agent-sandbox-awx
Version: 0.5.0
Summary: Broker-backed, kubeconfig-free overlay for the Agentic Sandbox client.
Keywords: kubernetes,sandbox,agent,broker,identity,attribution
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: k8s-agent-sandbox-base==0.5.3.post16
Requires-Dist: requests
Requires-Dist: pydantic
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

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

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

```python
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`](https://pypi.org/project/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:

| Variable | Purpose |
|---|---|
| `AGENT_SANDBOX_BROKER_URL` | Public HTTPS broker endpoint |
| `AGENT_SANDBOX_TOKEN_PATH` | Rotating Kubernetes projected-token file |
| `AGENT_SANDBOX_TOKEN` | GitLab or other OIDC ID token |
| `AGENT_SANDBOX_WARMPOOL` | Approved warm pool; defaults to `python-sandbox-warmpool` |
| `AGENT_SANDBOX_NAMESPACE` | Broker-owned claim namespace; defaults to `agent-sandbox` |
| `AGENT_SANDBOX_TTL_SECONDS` | Optional sandbox shutdown deadline |

Kubernetes normally needs no Python authentication code:

```python
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:

```yaml
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:

```python
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`.
