Skip to navigation
Modbox APIsandboxes

Provision a sandbox

View as Markdown

Creates a sandbox and returns immediately with a sandbox_id — the container boots in the background, so the sandbox is not usable yet when this call returns.

Next step: call POST /sandboxes/wait to block until it is ready, or poll GET /sandboxes/detail/{sandbox_id} until status is running. The sandbox_url is only populated once the sandbox is running.

Supply either image_id (a registered image, recommended) or image (a raw Docker reference). Set ttl_seconds so the sandbox is reclaimed automatically even if the caller crashes.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Headers

x-workspace-idstring or nullOptional

UUID of the workspace that scopes this request. List the workspaces you belong to with GET /workspaces.

Request

This endpoint expects an object.
task_idstringRequired1-255 characters

Your unique name for this sandbox. Reuse it to destroy, wait on or query the sandbox later. Must be unique among live sandboxes — a UUID or a per-session id works well.

imagestring or nullOptional1-512 characters

Raw Docker image reference. Prefer image_id, which also carries memory, TTL and readiness settings. Ignored when image_id is set.

image_idstring or nullOptionalformat: "uuid"

Id of a registered image from GET /sandbox-images. Recommended: it applies the image's memory, readiness and TTL defaults, and handles private-registry authentication.

If neither image_id nor image is supplied, the deployment's default image is used — pass one explicitly for reproducibility.

env_varsmap from strings to strings or nullOptional

Environment variables injected into the container. Use this to pass configuration, or the standard HTTP_PROXY/HTTPS_PROXY variables to route egress through a proxy.

ttl_secondsinteger or nullOptional60-86400

Destroy the sandbox automatically after this many seconds (60–86400). Overrides the image default. Always set this for agent workloads so a crashed caller cannot leak resources.

Response

Successful Response
successboolean
True when the sandbox was accepted for provisioning.
endpointobject or nullOptional

Where to reach the sandbox and the token to authenticate with. The URL is known immediately, but only answers once status is running.

capabilitiesmap from strings to strings or nullOptional

Absolute URLs for what this sandbox exposes, keyed by capability (exec, files, and depending on the image terminal, vnc, cdp, mcp). Read this instead of assuming paths — they differ between images.

sandbox_idstring or nullOptionalformat: "uuid"

Id of the new sandbox. Poll GET /sandboxes/detail/{sandbox_id} with it.

statusstringOptionalDefaults to provisioning

Lifecycle state at the time of the response. Always provisioning here — the container is still booting.

sandbox_urlstring or nullOptional

Public URL of the sandbox. Null until the status becomes running — read it from GET /sandboxes/detail/{sandbox_id}.

errorstring or nullOptional

Failure reason when success is false.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error