# Create sandbox URL: https://docs.hanzo.ai/docs/openapi/sandbox/post-sandbox > Leases a sandbox — a real computer — for the caller's org. `POST /v1/sandbox` > [Sandbox →](https://docs.hanzo.ai/docs/openapi/sandbox) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | ------------- | -------------------------------------- | | **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 6 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. | | `cluster` | body | string | — | Cluster names one of the org's attached clusters to run the sandbox on — the fleet-local name it was registered under. | | `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, visor, kata-clh or kata-fc. | | `ttlSec` | body | integer (int64) | — | TTLSec is how long the lease runs before the reaper may take it, in seconds. | ## Response | Status | Body | Meaning | | --------- | --------------- | ------- | | `201` | sandbox.Sandbox | created | | `default` | problem-details | refused | `201` body — 16 fields. | Field | In | Type | Always | Description | | ------------- | ---- | --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `actor` | body | string | — | Actor is the subject who LEASED this sandbox — the validated caller of the act that took the lease, never a value a request supplied. | | `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 project, bounded per org), "dev" for a workspace bound to a project (workdir /work, single-attach), "desktop" for one with a screen. | | `cluster` | body | string | — | Cluster is the attached cluster this sandbox runs on — the fleet-local name the lease named — or empty for the home cluster. | | `connectedAt` | body | integer (int64) | — | ConnectedAt is when somebody was last known to have this sandbox's project OPEN, Unix seconds. | | `createdAt` | body | integer (int64) | — | CreatedAt is when the lease was taken, Unix seconds — by the lease that made the sandbox, and again by each resume, which gives a parked sandbox a new pod on a new lease. | | `error` | body | string | — | Error is why the sandbox could not come up, in plain words. | | `expiresAt` | body | integer (int64) | — | 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 (int64) | — | 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 sandbox can actually have. | | `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, and "parked" when its pod is stopped and its disk kept, until a resume. | | `volume` | body | string | — | Volume is the persistent volume attached to the sandbox, when it has one. | Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors). ## Examples **CLI** ```bash hanzo sandbox create ``` **SDK** **.ts** ```ts import { Configuration, SandboxApi } from 'hanzoai'; const api = new SandboxApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.postSandbox({ class: "", cluster: "" }); ``` **.py** ```python 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="", cluster="") ``` **.go** ```go cfg := hanzoai.NewConfiguration() cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY")) client := hanzoai.NewAPIClient(cfg) resp, _, err := client.SandboxAPI.PostSandbox(context.Background()).Execute() if err != nil { return err } ``` **.rs** ```rust 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::post_sandbox(&cfg, Default::default()).await?; ``` **.java** ```java 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).postSandbox(); ``` **HTTP** ```bash curl -X POST https://api.hanzo.ai/v1/sandbox \ -H "Authorization: Bearer $HANZO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "class": "", "cluster": "" }' ``` **MCP** MCP reaches **sandbox** through the `sandbox` tool, which names its 17 operations with its own verbs — this one among them, under a name only MCP declares. `describe` explains any of them: ```bash 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](https://docs.hanzo.ai/docs/openapi/sandbox) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)