Skip to main content

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.

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.

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:

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 }]
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:

{
  "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.

Metadata

Release files for devzero-sandbox 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for devzero-sandbox 0.1.0
File Size Uploaded Provenance Actions
devzero_sandbox-0.1.0.tar.gz 148.9 kB Without provenance Details for devzero_sandbox-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for devzero-sandbox 0.1.0
File Interpreter ABI Platform Actions
devzero_sandbox-0.1.0-py3-none-any.whl Python 3 none any Details for devzero_sandbox-0.1.0-py3-none-any.whl

Total release size: 245.1 kB

Release files / devzero_sandbox-0.1.0.tar.gz

Download URL devzero_sandbox-0.1.0.tar.gz
Size 148.9 kB
Tags Source
SHA-256 checksum
How to use checksums
260d825d1bd550c99dcb1dfc91d1752189a0539b830c4709bd2e9c57992907ec
BLAKE2b-256 checksum
How to use checksums
e86a7aba78341eadf8b73ea37948fc019060e80925006c59d7707a9c200cd245
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / devzero_sandbox-0.1.0-py3-none-any.whl

Download URL devzero_sandbox-0.1.0-py3-none-any.whl
Size 96.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4c844e22616f9061281cf569978cef2d0ad4e4bb04a723892f0a0f1047def855
BLAKE2b-256 checksum
How to use checksums
95a80ee3d42a38d1b2b048650e30d256eebc1b5ee18fb4b0fc0106495a7b6924
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Security for devzero-sandbox 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page