Hanzo AIDocs
Sign inAPI key

Create lease

Leases the caller's sandbox, or returns the one it named if that lease is still running, or gives it a pod again if it is parked — with its disk as it was left.

POST /v1/sandbox/lease

Sandbox → · All API references → · Get started →

Addresshttps://api.hanzo.ai/v1/sandbox/lease
MethodPOST
Operationlease_sandbox
AuthAuthorization: Bearer $HANZO_API_KEY

Leases the caller's sandbox, or returns the one it named if that lease is still running, or gives it a pod again if it is parked — with its disk as it was left.

What comes back is a real computer: a pod under a runtime boundary with a toolchain already in it, its own filesystem, and a lease that ends it. Every other op here acts on the one this returns.

Request

7 fields, body application/json (required).

FieldInTypeRequiredDescription
classbodystring—Class is what KIND of computer to lease, and the set is closed: exec a throwaway one that keeps nothing.
clusterbodystring—Cluster names one of the org's ATTACHED clusters to run the lease on — the fleet-local name a BYO cluster was registered under.
diskbodyboolean—Disk gives a sandbox with no Project a disk of its OWN, so what it writes survives a park: small — the size its working directory always had — billed as storage for as long as it exists, and deleted with the lease.
idbodystring—ID names a sandbox to RESUME, and is the id an earlier lease answered with.
projectbodystring—Project names the disk to attach, and is REQUIRED for every class but exec.
runtimebodystring—Runtime is the isolation boundary asked for: gvisor shares a filesystem and holds a project volume, kata-fc is a microVM that boots slower and reads files faster but has no shared filesystem at all.
ttlSecbodyinteger (int64)—TTLSec bounds the lease in seconds.

Response

StatusBodyMeaning
200sandbox.Leasedok
defaultproblem-detailsrefused

200 body — 6 fields.

FieldInTypeAlwaysDescription
classbodystring—Class is what was actually leased, from the closed set LeaseIn.Class names: exec | dev | desktop | android.
clusterbodystring—Cluster is the attached cluster this sandbox runs on, when one was named.
idbodystring—ID names this computer for every later call — run, read, write, stop and end all take it, and a LeaseIn carrying it resumes THIS sandbox instead of leasing a second one.
runtimebodystring—Runtime is the boundary this sandbox GOT, which need not be the one asked for — carried for the same reason Workdir is, that it is a fact only the owner knows and a caller assuming it would be holding a second copy.
statusbodystring—Status is where the pod stands, from the store's three: pending | running | error.
workdirbodystring—Workdir is the absolute directory this sandbox keeps files in, and what a relative path in a later read, write or run resolves against — /work for dev, desktop and android (the project volume's mount point), /mnt/data for exec (the artifact directory the code tool tells the model to write to).

Failure carries the platform error shape — see Errors.

Examples

hanzo sandbox lease
import { Configuration, SandboxApi } from 'hanzoai';

const api = new SandboxApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.leaseSandbox({ class: "<class>", cluster: "<cluster>" });
from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import SandboxApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = SandboxApi(client).lease_sandbox(class="<class>", cluster="<cluster>")
cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.SandboxAPI.LeaseSandbox(context.Background()).Execute()
if err != nil {
	return err
}
use hanzo_client::apis::{configuration::Configuration, sandbox_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = sandbox_api::lease_sandbox(&cfg, Default::default()).await?;
import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.SandboxApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new SandboxApi(client).leaseSandbox();
curl -X POST https://api.hanzo.ai/v1/sandbox/lease \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "class": "<class>",
       "cluster": "<cluster>"
     }'

Tool sandbox, op lease_sandbox — POST the JSON-RPC envelope to https://api.hanzo.ai/v1/mcp.

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "sandbox",
         "arguments": {
           "op": "lease_sandbox",
           "input": {
             "class": "<class>",
             "cluster": "<cluster>"
           }
         }
       }
     }'

Sandbox API · All Hanzo APIs · Interactive reference

Was this page useful?
PreviousList sandboxNextCreate exec