sandboxes

Change a sandbox's name, labels, environment, automatic wake, idle pause, time limit, end action or persistence. Fields left out stay as they are.

idlePauseSeconds set here (10 to 86400) counts from the last activity: a request, a running command or terminal, an open connection, network traffic or CPU use; 0 turns idle pause off. persistent: true keeps the sandbox running until you stop it, while credit lasts, with no idle pause or time limit, its disk billed as any sandbox's; paid sandboxes only. timeoutSeconds sets its time limit from now, sooner or later than before (0 removes it), and onTimeout what its end does: endsAt answers the new end. A change of end action that reaches the server's last paid stretch can end it up to about two minutes after the asked end, never before.

post/v1/sandboxes/{id}:update

Request

  • Base URL: https://api.withruntime.com
  • URL: https://api.withruntime.com/v1/sandboxes/{id}:update
  • Auth: HTTP bearer

Path parameters

idstring required

Resource identifier (UUID).

Headers

Idempotency-Keystring

Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header.

Request body

namestring

Your own handle for the resource. Letters, digits, dot, dash, underscore.

labelsobject

Your own key/value tags, at most 32. Filter lists with label=key:value.

secretsstring[]

Refused: a sandbox's egress secrets are fixed when it is created. Create a new sandbox, or fork this one with a narrower list.

envobject

Change its environment: a value sets a variable, null removes it; the rest stay. Commands started after the change get it; running ones keep what they started with. At most 32 variables and 32768 bytes in all.

autoWakeboolean

Wake it by itself when it is paused and a request needs it (an exec, a file or terminal call, or a visit to a shared port).

idlePauseSecondsinteger

Pause it after this many seconds with no request, no command or terminal still running, no open preview, port, SSH or tunnel connection, no network traffic and no CPU use by its processes, counted from now. 0 is never; otherwise 10 to 86400.

persistentboolean

Keep it running until you stop it, while credit lasts: no time limit even with timeoutSeconds, and no idle pause unless idlePauseSeconds asks for one. Its disk is billed as any sandbox's. Paid only.

maxTotalCostMicrosinteger nullable

The most it may cost over its whole life, in microdollars; null removes the cap.

timeoutSecondsinteger

A new time limit, counted from now: 60 to 86400 seconds, sooner or later than the one it had, and it then ends as onTimeout says; a paused sandbox counts it from its next wake. 0 takes the limit away: it runs while it works and pauses when idle. Not for a persistent sandbox.

onTimeout'pause' | 'stop' | 'delete'

What happens when its timeoutSeconds, its credit or a spending limit ends it: pause (keep memory and files; wake later), stop (keep the files, billed as paused storage; restart later) or delete (when timeoutSeconds runs out, delete it and its files; credit or a spending limit only stops it). Default pause. onLeaseEnd, its older name, is accepted too. Changed for its next end.

onLeaseEnd'pause' | 'stop' | 'delete'

onTimeout's older name.

Example request

{
  "tailscale": {
    "authKeySecret": "TS_AUTHKEY",
    "tags": [
      "tag:ci"
    ]
  }
}

Response

Success

idstring required

Resource identifier (UUID).

kind'sandbox' required
namestring nullable
labelsobject

Your own key/value tags, at most 32. Filter lists with label=key:value.

status'pending' | 'active' | 'paused' | 'stopping' | 'stopped' required

Deprecated: read state. An older, coarser name for it, kept for older clients.

state'starting' | 'running' | 'pausing' | 'paused' | 'resuming' | 'stopping' | 'stopped' required
regionstring required
funding'trial' | 'paid' required
vcpuinteger
memoryMiBinteger
diskMiBinteger
cpu'shared' | 'reserved'
cpuFloorMillisinteger
pausableboolean
timeoutSecondsinteger

Its time limit in seconds, up to 86400 (24 hours); 0 is none: it runs while it works and pauses when idle.

onTimeout'pause' | 'stop' | 'delete'

What happens when its time limit, credit or a spending limit ends it. The same value as onLeaseEnd, its older name.

idlePauseSecondsinteger

Pauses after this many idle seconds; 0 is never.

idlePauseUnusedOnlyboolean

True only for a sandbox created before 27 September 2026 with the old default idle pause, which paused it only while nothing had used it. False when the idle time counts from the last activity.

autoWakeboolean

A request wakes it when paused: an exec, a file or terminal call, or a visit to a shared port.

persistentboolean

It has no time limit and is not paused for being idle unless idlePauseSeconds says so.

diskKeptboolean

Stopped with its disk kept: :restart starts it again from the disk. A stop keeps the disk; only a delete removes it.

lastActiveAtstring date-time nullable

The last exec, file, terminal, desktop or preview request, or open preview connection, to within five seconds (a minute for a sandbox whose idle time counts only while unused).

createdAtstring date-time required
readyAtstring date-time nullable

When its current run became ready to run commands. Null before that, while it is paused, and once a stop that kept its disk has ended the run; endedAt says when it ended.

expiresAtstring date-time required

Paid up to, at most an hour ahead, or when a stopped sandbox ended: kept for older clients. Read endsAt for when it stops or pauses by itself.

endsAtstring date-time nullable

When it stops or pauses by itself: the end of its time limit, which :extend moves, or where its funding ends when credit or a spending limit stops its renewal. null when it never will: no time limit, or not running.

endedAtstring date-time nullable
stopReasonstring nullable

Why it stopped or paused. Yours: requested, time_limit (its timeoutSeconds ran out and it was made to stop rather than pause; lease_expired before 4 October 2026), idle, paused_expired (kept paused past its retention), insufficient_funds (credit ran out), pilot_hours_used (its pilot's sandbox hours are used; credit does not run it, and the account's owner may write to support to extend the pilot or ask for more hours), pilot_ended (its pilot and the pilot's grace are over; credit does not run it, and the account's owner may write to support to extend the pilot), lifetime_cap (this sandbox's own maxTotalCostMicros), spending_limit (an owner-set spending limit, usually this agent's daily limit; see what is left with GET /v1/limits or runtime limits) or authority_revoked (the key that made it lost the right). A fault on our side, not in your code: host_lost (its machine failed; create a new sandbox) and pause_failed (its memory could not be kept; it is paused with its files, and the next wake starts it from its disk, memoryRestored false). operator_stopped: our operator stopped it. startup_failed: it stopped before it was ready to run commands; from your own image, check its start and ready commands. account_busy_here: it can start only on the servers that hold its snapshot or image, and your own sandboxes there were short of CPU, so it did not start and nothing ran; start it again in a minute. service_unready: a service on our side that it needs was unavailable, so it could not keep running; create a new one. host_stopped: its machine ended without a stop being asked for; while it was starting or waking that is our fault, and once it was running it can also be a shutdown or crash inside the sandbox.

pausedAtstring nullable
pausedExpiresAtstring nullable

When a paused or stopped sandbox is deleted. Null while it is kept as long as your account has credit.

memoryRestoredboolean
placementstring nullable

Opaque tag of the server it is on: the same for your sandboxes and snapshots on one server, different on another, never the server's name. Compare tags to see whether two share a server; keep them apart with spreadFrom on create. Null before it is placed.

chargedMicrosinteger

Settled, in microdollars (1,000,000 = $1).

heldMicrosinteger

Deprecated, kept for older clients: read chargedMicros and GET /v1/usage.

ratesobject
envNamesstring[]

The names of its own environment variables (env), sorted, on a create, an update and a read of one sandbox. Values are never shown.

secretsstring[] nullable

The egress secrets it may use, fixed when it was created: only those of your secrets that would otherwise reach it. null: every secret that reaches it. On a create, an update and a read of one sandbox.

secretsEnforcedboolean

On an update with labels by a key that may read secrets, when one of your egress secrets is scoped: true when every server running your sandboxes holds the change, so the next request from this sandbox is rewritten (or no longer is) by the new labels. False when a server has not confirmed yet; it takes the change within 15 seconds. Absent for any other key: its change reaches the servers within 15 seconds.

simulatedboolean
replayedboolean

Present and true when an Idempotency-Key replay answered.

Changes

No recorded changes to this operation across all 1 revision of this API.