Sandboxes

POST /public/sandboxes requires name and either templateId or template. CPU is measured in cores and memory in MB. Omitted values use the selected template. The region is bremen today. Drivers are firecracker and cloud-hypervisor, with firecracker as the default.

Attach existing volumes with volumeIds or create and attach them in one request with createVolumes. Attach an organization network with networkId. Labels are useful for run correlation; metadata is accepted as create-time input and merged into labels.

A create request can declare raw_l4 ingress for TCP or UDP and can configure secretInjection. The create operation is idempotent when you reuse the same Idempotency-Key for the same logical request.

1curl -X POST https://api.zei.sh/api/v1/public/sandboxes   -H "X-API-Key: $ZEISH_API_KEY"   -H "Idempotency-Key: run-123"   -H "Content-Type: application/json"   -d '{2    "name": "agent-workspace",3    "templateId": "TEMPLATE_ID",4    "cpu": 4,5    "memory": 4096,6    "volumeIds": ["VOLUME_ID"],7    "ingress": [8      {"mode":"raw_l4","protocol":"tcp","internalPort":3000}9    ]10  }'

Sandbox statuses include initialized, pending, running, pausing, paused, resuming, stopping, stopped, suspending, cloning, destroying, failed, and destroyed. Actions are asynchronous. Refresh the detail response before using a runtime-dependent feature.

Creating a sandbox normally starts its runtime. createAndStartSandbox handles the common agent path: create, wait for running, destroy a failed attempt, and retry. Its defaults are three attempts, a 90 second ready timeout, and a two second poll interval.

Use pause and resume when you want to keep state. Stop releases the running runtime while preserving the sandbox record. kill force-stops a stuck runtime. Clone creates a new sandbox from an existing one. Delete is permanent.

1import {2  createZeishApi,3  createAndStartSandbox,4  isTerminalSandboxStatus,5} from "@zeish/computesdk-provider";67const api = createZeishApi({8  apiKey: process.env.ZEISH_API_KEY!,9  baseUrl: "https://api.zei.sh/api/v1",10});1112const sandbox = await createAndStartSandbox(api, {13  name: "agent-run",14  templateId: process.env.ZEISH_TEMPLATE_ID!,15});1617const current = await api.getSandbox(sandbox.id);18if (isTerminalSandboxStatus(current.status)) {19  throw new Error("sandbox is no longer usable");20}2122await api.pauseSandbox(sandbox.id);23await api.resumeSandbox(sandbox.id);

A snapshot captures the sandbox runtime state for reuse. Create it only after the sandbox has a live runtime. A new snapshot is initially pending and becomes ready before it can be used as a source.

The public REST API and first-party session client support create, list, and delete for sandbox-scoped snapshots. The ComputeSDK standard interface supports snapshot creation, but its list and delete methods are not sandbox-scoped, so use the Zeish API for those operations.

Snapshot and sandbox deletion are irreversible. Use descriptive names such as before-deploy or dependencies-v4, and keep a stable source sandbox when you need repeatable fan-out.

1const snapshot = await sandbox.createSnapshot("dependencies-v4");2const snapshots = await sandbox.listSnapshots();34await sandbox.deleteSnapshot(snapshot.id);56// REST routes7// POST   /public/sandboxes/:sandboxId/snapshots8// GET    /public/sandboxes/:sandboxId/snapshots9// DELETE /public/sandboxes/:sandboxId/snapshots/:snapshotId