NewCompare CPU & GPU pricing across AWS, Azure & GCP
Self-hosted sandboxes

Sandbox quickstart

Create a sandbox policy, then create a sandbox with the Python SDK, run a command, write and read a file, and delete it. Also connects an MCP client.

Sandbox quickstart

This page assumes sandboxes are installed on the cluster: the gateway is ready and the endpoint is set, so its hostname resolves from where you run the code. For an internal endpoint, or one you route to the gateway's ClusterIP Service yourself, that means a machine on the cluster's network or a pod in the cluster; see Exposure modes.

A pod in the cluster gets sandbox URLs on the endpoint hostname too, so the hostname must resolve there as well. If it has no DNS record, add a CoreDNS rewrite of the hostname to devzero-sandbox-gateway.devzero-system.svc.cluster.local, or hostAliases on the pod with that Service's cluster IP; see Set up the endpoint.

You need:

  • the cluster ID (Copy cluster ID on the cluster's page in the dashboard);
  • the name of a DevZero node policy with Sandbox runtime: gVisor that targets the cluster;
  • a default StorageClass backed by a CSI driver: kubectl get storageclass shows one class marked (default) (see Storage). If the cluster has none, name a class in the policy ("storage": { "workspace": { "storageClassName": "<class>" } }), or, for a first try, turn the workspace volume off ("storage": { "workspace": { "enabled": false } }): /workspace is then on the container's own filesystem, and its files are lost whenever the sandbox's pod is recreated;
  • a DevZero token: a personal access token (dzu-…) or a team service-account token (dzs-…). Creating a policy needs the Admin role on the cluster's team; creating sandboxes needs Developer.

Create a policy

A sandbox policy decides the image, resources, lifetime and node pool of a class of sandboxes. See Policies and guardrails for every field.

In Sandbox → Policies, pick the cluster and choose New. Name it default, choose your gVisor node policy, and leave the other fields empty to take the defaults. If DevZero refuses it (for example it exceeds the cluster guardrails), the form says why.

The policy is ready when the cluster reports it so. The policy page refreshes on its own, or check in the cluster:

kubectl get sandboxpolicy default

READY must be True. If it is not, the policy's conditions name the failing check; Check the install lists the common ones.

READY does not cover storage. Check StorageClassReady too:

kubectl get sandboxpolicy default -o jsonpath='{.status.conditions[?(@.type=="StorageClassReady")].status} {.status.conditions[?(@.type=="StorageClassReady")].reason}{"\n"}'

From dz-sandbox 0.1.2 it is False when the workspace volume could never bind. With reason NoDefaultStorageClass, the message reads:

the workspace volume uses the cluster's default StorageClass, but no StorageClass is annotated storageclass.kubernetes.io/is-default-class=true, so its volume claim never binds; annotate one (kubectl annotate storageclass <name> storageclass.kubernetes.io/is-default-class=true), or set spec.storage.workspace.storageClassName in DevZero

With reason CSIDriverNotInstalled, it names the StorageClass and the missing CSI driver, for example StorageClass "gp2" needs the CSI driver ebs.csi.aws.com (in-tree kubernetes.io/aws-ebs is served through CSI migration), and no CSIDriver ebs.csi.aws.com is installed, so its volumes are never provisioned, followed by how to install it. Fix it as in Storage.

Still on dz-sandbox 0.1.1 or earlier? Those releases report StorageClassReady (and READY) True even when the cluster has no default StorageClass. If create below then times out, check for a Pending workspace claim, workspace-<sandbox id>, or upgrade both charts to 0.1.2:

kubectl -n devzero-sandbox get pvc

Install the SDK

The SDK is devzero-sandbox on PyPI (0.1.0 at the time of writing). It needs Python 3.11 or later:

pip install devzero-sandbox
export DEVZERO_TOKEN=dzu-...

It talks to DevZero's API at https://dakr.devzero.io. To use another DevZero API host, set DEVZERO_DAKR_URL or pass Client(api_url=...).

Create a sandbox and use it

from devzero_sandbox import Client

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

result = sbx.commands.run("uname -a && whoami")
print(result.exit_code, result.stdout_text)

sbx.files.write("hello.txt", "hello from the quickstart\n")  # relative to /workspace
print(sbx.files.read_text("hello.txt"))

sbx.delete()
  • client.sandboxes.create returns once the sandbox is ready (up to 5 minutes by default, timeout_s=). A cold start on a new gVisor node takes longer than one on a node that is already up; a warm pool (warmPool.size on the policy) removes most of the wait.

  • If it is not ready in time, create raises SandboxWaitTimeout and leaves the sandbox in place: it may still become ready, and until you delete it, it counts against the policy's maxSandboxes. The exception carries the sandbox ID:

    from devzero_sandbox import errors
    
    try:
        sbx = client.sandboxes.create("default", cluster_id="<cluster id>")
    except errors.SandboxWaitTimeout as e:
        print(e.sandbox_id, e.phase)
        client.sandboxes.get(e.sandbox_id).delete()  # or keep waiting: client.sandboxes.get(e.sandbox_id).wait()
        raise
  • cluster_id is needed only when a policy of that name exists on more than one cluster. client.policies() lists the policies you may use, as does Sandbox → Policies in the dashboard.

  • commands.run returns a CommandResult with exit_code, stdout, stderr (bytes) and stdout_text, stderr_text. Pass background=True for a long-running process.

  • File paths are relative to /workspace, the sandbox's persistent volume. files.read returns bytes; files.read_text decodes them.

  • Every failure raises a typed exception from devzero_sandbox.errors.

If the endpoint's certificate comes from a private CA, pass the CA bundle: Client(gateway_options={"ca_bundle": "/path/to/ca.crt"}). The SDK otherwise uses the system trust store.

See it in DevZero

Sandbox → Sandboxes lists the cluster's sandboxes with their status, policy and shutdown time. Developers and Admins can extend or delete one there. Sandbox tokens are never shown.

Use sandboxes from an MCP client

The SDK ships sandbox-mcp, a stdio MCP server with seven tools: create_sandbox, run_command, read_file, write_file, list_files, upload and delete_sandbox. Sandboxes a session creates are deleted when the session ends.

pip install 'devzero-sandbox[mcp]'

Add it to your MCP client's configuration; most clients use this shape:

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

It reads its configuration from the environment only. DEVZERO_SANDBOX_CA_BUNDLE sets a private CA, DEVZERO_SANDBOX_MCP_UPLOAD_ROOT turns on the upload tool for files under that directory, and sandbox-mcp --help lists the output and timeout limits. Prefer a team service-account token for an agent rather than your own.

From inside the cluster

A pod in the same cluster can use a sandbox without a DevZero token, with its Kubernetes service account, when the policy lists that account in access.serviceAccounts. It mounts a projected token for the gateway's audience and connects with Sandbox.in_cluster(...). See Who can use sandboxes and the SDK's README.

Next steps

On this page