Resize a sandbox
Change the CPU, memory, or disk allocation of a sandbox. Only provided fields change.
- Disk only grows, and grows at once.
- CPU and memory grow live on a running sandbox that supports it. Otherwise they apply on the next reboot.
- Set
modetoliveto fail instead of waiting, or todeferredto always wait for the reboot. - A live resize only grows. To shrink memory, set
force. The change applies on the next reboot.
A refusal carries its cause code in the problem type:
- 409 for
no_capacity,claim_failed,resize_in_flightanddisk_resize_failed. Nothing changed. - 422 for
shrink_unsupported,not_running,no_hotplug_limits,above_hotplug_limitor another runner code. - 502 for
live_resize_unknown: the dispatch came back without a decision, and the change waits as pending.
Authorization
apiKey API key starting with tektona_. Create one at app-dev.tektona.ai under API Keys.
In: header
Path Parameters
Sandbox ID (ULID) or name
Query Parameters
Required when the path names the sandbox by name.
Required when the path names the sandbox by name.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
CPU cores. Limited per installation: read the limits from GET /v1/sandbox-limits.
int641 <= valueTotal root disk in GiB. Limited per installation: read the limits from GET /v1/sandbox-limits.
int641 <= valuePermit downsizing memory, which can disrupt a running workload.
Memory in GiB. Limited per installation: read the limits from GET /v1/sandbox-limits.
int641 <= valueWhen a CPU or memory change applies. live: apply it to the running sandbox now, or fail; a refusal leaves CPU and memory as they are (a disk that the runner grew stays grown), and an unknown outcome (live_resize_unknown) leaves the change for the next reboot. deferred: apply it on the next reboot. Omitted: apply it now when the sandbox can grow live, else on the next reboot; deferred_reason then says why.
Value in
- "live"
- "deferred"
Response Body
application/json
application/problem+json
curl -X PUT "https://example.com/v1/sandboxes/string/resize" \ -H "Content-Type: application/json" \ -d '{}'{ "after": { "cpu": 2, "disk": 10, "memory": 2 }, "applies_immediately": true, "before": { "cpu": 2, "disk": 10, "memory": 2 }, "deferred_reason": "string", "id": "string", "note": "string"}{ "detail": "Property foo is required but is missing.", "errors": [ { "location": "string", "message": "string", "value": null } ], "instance": "https://example.com/error-log/abc123", "status": 400, "title": "Bad Request", "type": "https://example.com/errors/example"}Reset a sandbox PUT
Hard-reset a running sandbox — like pulling the power. Unlike reboot-sandbox the guest gets no shutdown signal and its filesystem is not flushed first, so recently written, un-synced files may be lost. The VM restarts from the same disk on the same node; the disk and IP are preserved. A pending resize applies on reset.
Resume a sandbox PUT
Resume a paused (hibernated or suspended) sandbox. - A hibernated sandbox resumes with its memory only on a runner node whose CPU can restore it. - With `discard_memory`, a hibernated sandbox starts from its disk instead. Its memory image is deleted, and it can run on any node with room. A refusal can carry its cause code in the problem type, all with 503: - `memory_restore_no_capacity`: no node can restore the memory now. The sandbox keeps the memory. To resume now, set `discard_memory`. - `disk_node_unavailable` (with `discard_memory`): the disk is only on the node that paused the sandbox, and that node is unavailable or full. The memory is kept. - `memory_discarded` (with `discard_memory`): the resume failed after the memory was discarded. The sandbox is suspended. To retry, resume without `discard_memory`.