Create a sandbox, optionally from a template, and optionally queue it

POST /v1/sandboxes

In this build: Works on the simulator or a real VM.

Scope: sandbox.create

CLI: harebox new

Send an Idempotency-Key header. A retry with the same key never repeats the action.

Request: `CreateSandboxRequest`

Field	Type	Notes
`name`	`string`
`size`	`Size`
`tier`	`Tier`
`region`	`Region`
`image`	`string`	One of: `ubuntu-24.04`
`template`	`string`	Template name, name@version, or share code.
`project`	`string`
`fleet`	`string`
`labels`	`Labels`
`environment`	`string`
`no_env`	`boolean`	Pass nothing of yours into the sandbox. Use for third-party tenants.
`env`	`object`
`setup_script`	`string`
`files`	`array`
`sleep`	`SleepPolicy`
`ttl_seconds`	`integer or null`	Auto-stop this long after creation or the last resume. Omit for one hour; null for none. The trial requires 7200 or less. A running agent prompt moves the deadline.
`snapshots`	`boolean`	False for no saved state.
`monitoring`	`boolean`
`visibility`	`string`	One of: `private`, `shared`
`endpoints`	`array`
`placement`	`string`	wait for capacity, answer in about a second, or join the start queue. One of: `wait`, `fail_fast`, `queue`
`queue_deadline_seconds`	`integer`

Sandbox

Field	Type	Notes
`id` (required)	`string`
`name`	`string`
`state` (required)	`LifecycleState`
`conditions` (required)	`array`
`condition_details`	`object`	Why each condition applies, and for sleep, what is keeping the sandbox awake.
`region` (required)	`Region`
`tier` (required)	`Tier`
`size` (required)	`Size`
`image`	`string`	Base image: ubuntu-24.04.
`location`	`object`	Where the sandbox runs now. Read-only: HareBox places sandboxes itself and may move them on resume.
`created_by`	`string`	The API key that created this sandbox. A key's monthly budget counts what it created.
`project`	`string or null`
`fleet`	`string or null`
`labels`	`Labels`
`environment`	`object or null`
`template`	`string or null`
`forked_from`	`string or null`
`ipv4`	`string or null`
`ipv6`	`string or null`
`subdomain`	`string`
`sleep`	`SleepPolicy`
`deadline`	`string or null`	Absolute stop time. Null means none.
`visibility`	`string`	One of: `private`, `shared`
`capabilities` (required)	`object`	What this sandbox can do right now. Agents should check these rather than infer them.
`hydration`	`object or null`
`simulated`	`boolean`	True when the machine is the labelled simulator rather than a real VM.
`fork_ids`	`array`	All new sandboxes, when a fork asked for a count.
`meter`	`object`
`created_at` (required)	`string`
`ready_at`	`string or null`

Errors follow one format.