Tutorial

Sandboxes

One lease, one machine — what it is, what surrounds it, and how it ends

Checked 2026-09-28

A Lease is one isolated machine — a shape, a region, an image — for a bounded time. It is granted immediately, from a warm machine or a cold one, or refused with a typed reason. Sandboxes is the only writer of a lease: you describe the machine you want, and the platform hands you one.

#A lease is granted, not queued

There is no queue. create answers when the guest is ready, and waits at most 60 seconds for that; with skip_wait_ready it answers as soon as the machine is granted. A request that cannot be served now is refused rather than parked, and status.refusal names which refusal it was: no_capacity, no_matching_cell, shape_not_offered, shape_not_entitled, image_not_found or abuse_hold.

The trade is deliberate: nobody waits behind someone else's workload, and the caller owns the retry. A refusal is an answer, not a delay.

#The objects around a lease

A lease names its shape, its image — a Kernel Artifact by digest, or a template: name — its kind, and its ttl. kind decides what the machine serves, and defaults to general; the other three, browser, desktop and android, are the ones with a display.

#The lease ends, and the machine is destroyed

release ends a lease now. So does its ttl, a lease left unused past its idle_timeout, a budget, and a machine the platform loses — and status.end_reason says which of those happened. The end destroys the machine: it is never leased again, and its disk goes with it.

A volume is the way work survives a lease. It is attached by name when the lease is created, detached when the lease ends, and destroyed only by its own Delete. Everything else you leave in a lease belongs to that lease.

#The scopes

• sandboxes:read — the lease, its events, and the shape catalog.
• sandboxes:write — everything that changes a lease: create, renew, pause, resume, release, its network policy, and the pools, volumes and snapshots around it.
• sandboxes:exec — the data plane: exec, the files, the exposed ports, computer actions, the live view, and minting a lease token.

Name

orgs/{org}/projects/{project}/envs/{env}/leases/{lease}

Id

sbx_<cell><ulid>

A lease’s name is a path, and the same path works in the API, the CLI and the console. The id is never reused.