Metadata-Version: 2.5
Name: devzero-sandbox
Version: 0.1.0
Summary: DevZero self-hosted sandboxes SDK (control plane + data plane clients) and MCP server
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: googleapis-common-protos>=1.63
Requires-Dist: httpx-sse>=0.4
Requires-Dist: httpx>=0.27
Requires-Dist: protobuf>=5.29.3
Requires-Dist: pydantic>=2
Requires-Dist: websockets>=13
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
Description-Content-Type: text/markdown

# devzero-sandbox

The Python SDK and MCP server for DevZero self-hosted sandboxes: isolated Linux containers that
run in your own Kubernetes cluster, created through DevZero. Python 3.11+, Apache-2.0.

```bash
pip install devzero-sandbox          # the SDK
pip install 'devzero-sandbox[mcp]'   # the SDK and the sandbox-mcp server
```

## A script

Set `DEVZERO_TOKEN` to a DevZero personal access token (`dzu-...`) or team service-account token
(`dzs-...`) of a Developer on the cluster's team. `DEVZERO_DAKR_URL` points at a DevZero API
other than the default.

```python
from devzero_sandbox import Client

client = Client()  # DEVZERO_TOKEN, DEVZERO_DAKR_URL
sbx = client.sandboxes.create("default", cluster_id="<cluster id>")  # waits until ready

result = sbx.commands.run("echo hello")
print(result.exit_code, result.stdout_text)

sbx.files.write("data.bin", b"\x00\x01 any bytes")
assert sbx.files.read("data.bin") == b"\x00\x01 any bytes"

sbx.delete()
```

`cluster_id` is needed only when the policy name exists on more than one cluster;
`client.policies()` lists the policies you can use. When the cluster's gateway endpoint serves a
certificate from a private CA (a bring-your-own endpoint), pass it:
`Client(gateway_options={"ca_bundle": "/path/to/ca.crt"})`.

The same calls run against preproduction in `make real-cp-run`
(`operators/sandbox-operator/hack/lib/real_cp_sdk.py script`).

More: `sbx.commands.run(cmd, background=True)` returns a `Process` you can `attach` to again from
any process, `sbx.terminal()` opens an interactive terminal, `sbx.extend(ttl)` keeps the sandbox
longer, `sbx.tokens.mint(scope=[...])` / `.revoke(jti)` manage its tokens. Every failure is a
typed exception from `devzero_sandbox.errors`.

## In the cluster

A pod in the cluster reaches a sandbox without a DevZero credential, with its ServiceAccount, when
the sandbox's policy lists that ServiceAccount in `access.serviceAccounts`. Mount a projected token
for the gateway's audience and the CA bundle the sandbox operator publishes into the pod's
namespace:

```yaml
volumes:
  - name: dz-sandbox
    projected:
      sources:
        - serviceAccountToken: { audience: sandbox-gateway.devzero.io, expirationSeconds: 3600, path: token }
        - configMap: { name: devzero-sandbox-ca, items: [{ key: ca.crt, path: ca.crt }] }
# containers[].volumeMounts: [{ name: dz-sandbox, mountPath: /var/run/dz-sandbox, readOnly: true }]
```

```python
from devzero_sandbox import Sandbox

# reads /var/run/dz-sandbox/{token,ca.crt}
sbx = Sandbox.in_cluster("<policy>", "<sandbox id>")
print(sbx.commands.run("echo hello").stdout_text)
```

The sandbox id is the `sandbox.devzero.io/sandbox-id` label of the `SandboxClaim` the pod's
ServiceAccount created in the policy's namespace.

## MCP server

`sandbox-mcp` is a stdio MCP server with seven tools: `create_sandbox`, `run_command`,
`read_file`, `write_file`, `list_files`, `upload` and `delete_sandbox`. Sandboxes a session created
are deleted when it ends, and it writes nothing to disk. It is configured from its environment only:

```json
{
  "mcpServers": {
    "devzero-sandbox": {
      "command": "sandbox-mcp",
      "env": {
        "DEVZERO_TOKEN": "dzu-...",
        "DEVZERO_SANDBOX_POLICY": "default",
        "DEVZERO_SANDBOX_CLUSTER_ID": "<cluster id>"
      }
    }
  }
}
```

The other variables (`DEVZERO_SANDBOX_CA_BUNDLE`, `DEVZERO_SANDBOX_MCP_UPLOAD_ROOT`, which turns
`upload` on, and the output and timeout limits) are listed by `sandbox-mcp --help` and in
`devzero_sandbox/mcp/config.py`.
