snapshots

Snapshot a running or paused sandbox, to start new sandboxes from.

A running sandbox is paused for the moment it takes to capture, then woken again, as a fork's source is; the answer comes once the capture is over (up to a minute; one still capturing then leaves the sandbox paused until it is ready, so wake it after). A paused one stays paused; send Prefer: wait=10 to wait for its snapshot to be ready. Start copies with POST /v1/sandboxes and snapshot: <id>. Memory snapshots (the default) continue the saved machine: same files, same running processes, same memory, its own clock and a freshly seeded random number generator. A process that seeded its own generator before the snapshot keeps that seed in every copy. With mode: disk, only files are saved and each copy boots afresh without the old processes. A snapshot keeps the saved state used to start new sandboxes. Retained snapshots are copied off the host after any pending memory compression finishes, encrypted under your organization's own key; backedUp is true once that copy is checked. If the host is lost, the snapshot is restored onto another host from that copy and forks run there (they answer snapshot_restoring meanwhile). Only the root disk is kept, so a sandbox with volumes cannot be snapshotted.

post/v1/sandboxes/{id}:snapshot

Request

  • Base URL: https://api.withruntime.com
  • URL: https://api.withruntime.com/v1/sandboxes/{id}:snapshot
  • 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.

retentionDaysinteger

Days to keep it, 1 to 365, never past a year from when it was taken. Omit it to keep the snapshot while your account has credit, up to a year from when it was taken (seven days without credit).

mode'memory' | 'disk'

memory (default) saves the whole machine; disk saves files for a fresh boot, without old processes.

Response

Success

idstring required
kind'snapshot' required
mode'memory' | 'disk'
statusstring required
state'capturing' | 'ready' | 'failed' | 'deleting' | 'deleted' required
namestring nullable
sourceSandboxIdstring required
placementstring nullable

Opaque tag of the server it is kept on, as a sandbox's placement: its copies start there, or on a server holding a checked copy of it. Keep sources on separate servers with spreadFrom on create.

retentionDaysinteger nullable

Days it is kept, or null: kept while your account has credit, up to a year from when it was taken.

compressionPendingboolean

True while raw fork memory awaits verified compression. Ready snapshots remain startable on their current host. This workspace is unbilled and has no off-host copy until final publication; cross-host copies wait for compression.

storedBytesinteger nullable
meteredBytesinteger nullable

What storage is metered for: the final bytes this snapshot alone stores. Zero while compressionPending is true.

backedUpboolean

Whether its copy off the host is made and checked.

errorstring nullable
createdAtstring
readyAtstring nullable
expiresAtstring nullable required

When it is deleted. Null while it is kept as long as your account has credit.

Changes

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