Create sandbox

Leases a sandbox — a real computer — for the caller's org. The class decides what it is for and therefore its image, working directory and isolation.

POST /v1/sandbox

Sandbox → · All API references → · Get started →


Address	`https://api.hanzo.ai/v1/sandbox`
Method	`POST`
Operation	`post_sandbox`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Leases a sandbox — a real computer — for the caller's org.

The class decides what it is for and therefore its image, working directory and isolation. A dev or desktop sandbox is SINGLE-ATTACH per project, so asking twice for one project resumes the one that exists rather than paying for a second; an exec sandbox carries no project and is bounded per org instead, refused 429 past the ceiling because the caller's correct response is to wait.

Answers 201 with the sandbox as leased, which names the runtime it GOT — not the one that was asked for.

Request

5 fields, body application/json (required).

Field	In	Type	Required	Description
`class`	body	string	—	Class is what the sandbox is FOR: "exec" for a code-interpreter call, "dev" for a workspace bound to a project, "desktop" for one with a screen.
`image`	body	string	—	Image overrides the image the class would pick.
`project`	body	string	—	Project binds the sandbox to one of the org's projects.
`runtime`	body	string	—	Runtime asks for an isolation: runc, gvisor, kata-clh or kata-fc.
`ttlSec`	body	integer	—	TTLSec is how long the lease runs before the reaper may take it, in seconds.

Response

Status	Body	Meaning
`201`	Sandbox	created

201 body — 14 fields.

Field	In	Type	Always	Description
`class`	body	string	—	Class is what the sandbox is FOR, and it decides the image, the working directory and the isolation: "exec" for a code-interpreter call (workdir /mnt/data, no…
`connectedAt`	body	integer	—	ConnectedAt is when somebody was last known to have this sandbox's project OPEN, Unix seconds.
`createdAt`	body	integer	—	CreatedAt is when the lease was first taken, Unix seconds.
`error`	body	string	—	Error is why the sandbox could not come up, in plain words.
`expiresAt`	body	integer	—	ExpiresAt is when the lease ends, Unix seconds.
`id`	body	string	—	ID is the sandbox's server-minted handle and what every operation addresses it by.
`image`	body	string	—	Image is the container image this sandbox is actually running — the one the class chose, or an override the policy admitted.
`kind`	body	string	—	Kind is the resource family this row belongs to.
`lastUsedAt`	body	integer	—	LastUsedAt is when the sandbox last did work, Unix seconds.
`org`	body	string	—	Org is the org that holds the lease — the validated caller's, never a value a request supplied.
`project`	body	string	—	Project is the project this sandbox is bound to.
`runtime`	body	string	—	Runtime is the isolation boundary this sandbox GOT, which is not always the one it asked for: a caller states a preference and runtimeFor answers with what the…
`status`	body	string	—	Status is where the sandbox is in its life: "pending" while the pod is coming up, "running" once it can take work, "error" when it cannot.
`volume`	body	string	—	Volume is the persistent volume attached to the sandbox, when it has one.

Failure carries the platform error shape — see Errors.

Examples

hanzo sandbox create

import { Configuration, SandboxApi } from 'hanzoai';

const api = new SandboxApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postSandbox({ class: "<class>", image: "<image>" });

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).post_sandbox(class="<class>", image="<image>")

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.SandboxAPI.PostSandbox(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::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::post_sandbox(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.SandboxApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new SandboxApi(client).postSandbox();

curl -X POST https://api.hanzo.ai/v1/sandbox \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "class": "<class>",
       "image": "<image>"
     }'

MCP reaches sandbox through the sandboxes tool, which names its 19 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_sandboxes"
         }
       }
     }'

Sandbox API · All Hanzo APIs · Interactive reference

Request

Response

Examples

On this page