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 storageclassshows 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 } }):/workspaceis 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 defaultREADY 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 DevZeroWith 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 pvcInstall 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.createreturns 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.sizeon the policy) removes most of the wait. -
If it is not ready in time,
createraisesSandboxWaitTimeoutand leaves the sandbox in place: it may still become ready, and until you delete it, it counts against the policy'smaxSandboxes. 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_idis 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.runreturns aCommandResultwithexit_code,stdout,stderr(bytes) andstdout_text,stderr_text. Passbackground=Truefor a long-running process. -
File paths are relative to
/workspace, the sandbox's persistent volume.files.readreturns bytes;files.read_textdecodes 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
- Sandbox images: use your own image instead of
sandbox-base. - Policies and guardrails: lifetimes, warm pools, limits and access.
- Exposure modes: public or internal endpoints and your own ingress.
Install
Prerequisites, the two sandbox Helm charts, turning on the DevZero operator's sandbox relay, setting the endpoint, and checking that every part is ready.
Compatibility
Which Kubernetes versions and which upstream agent-sandbox version each DevZero sandbox release supports, and what the installer refuses.