Managing Sandbox Snapshots

Render Sandboxes is in public beta.

APIs, defaults, and limits might change during the beta period.

After you create a sandbox, you can capture its state in a snapshot. You can restore from a snapshot to create new sandboxes with the same prepared filesystem or resume a process from a saved state.

Snapshots are useful for reusing installed packages, preparing environments for agents, and saving progress before a sandbox terminates.

A sandbox must be actively running to capture a snapshot. Creating a snapshot does not terminate the sandbox.

Kinds of snapshots

Render supports two kinds of sandbox snapshots:

Capturing a snapshot

The following example captures a filesystem snapshot and waits until it's available. Replace sbx-abc123 with your sandbox's ID:

To capture a runtime snapshot instead, set the kind to runtime or omit the kind option.

The wait option waits up to five minutes for capture to complete. If you omit it, creation returns before the snapshot is available. If the wait times out, capture continues. Check the snapshot's current status before starting another capture.

Restoring from a snapshot

Restore from a snapshot by providing its ID when you create a sandbox. Each restore creates a new sandbox, preserving the snapshot for reuse.

Snapshots always belong to the same sandbox group as their source sandbox. Provide that group's ID when restoring. You can restore from a snapshot only into another sandbox in the same group.

These examples wait until the restored sandbox is running and set a five-minute runtime timeout. You can then execute commands or manage files inside it.

Restored state and configuration

Restoring from a snapshot preserves some aspects of the source sandbox, while other settings come from the new create request or their defaults. See Configuring sandbox behavior for how to provide these settings with the CLI or SDKs.

Restoring by name

You can name a snapshot when you capture it, then restore from it by name instead of ID:

Names are case-sensitive and scoped to a sandbox group. If you reuse a name, restoring by that name uses the most recently available snapshot with that name in the selected sandbox group.

A snapshot's name must be between 1 and 64 characters and cannot begin with snp-.

Retrieving snapshot details

You can retrieve a snapshot to check its status, capture error, expiration time, and other details:

Lookup, listing, and deletion methods all require the snapshot's sandbox group ID.

Snapshot status

A snapshot has one of the following statuses:

Waiting for an existing snapshot

If you captured a snapshot without waiting, you can wait for it to become available with the following approaches:

The SDK methods wait up to five minutes by default and raise an error if capture fails or the wait times out.

Snapshot expiration

By default, snapshots expire 30 days after capture. This expiration time does not change if you use the snapshot to restore a sandbox.

Check expiresAt (TypeScript) or expires_at (Python) for an individual snapshot's expiration time. The CLI displays this value in snapshot details.

You can set an expiration time when capturing a snapshot with either SDK. The following example sets it to 24 hours from now:

The expiration time must be in the future. After a snapshot expires, you can no longer retrieve it or restore from it. Sandboxes already restored from an expired snapshot are unaffected.

Listing snapshots

List snapshots in a sandbox group to find their IDs and statuses. The following example lists snapshots that are available to restore from:

Results are ordered newest first. Omit the status filter to include snapshots with any status. Deleted and expired snapshots are excluded.

The SDKs return one page at a time. Use the cursor from the last entry (TypeScript) or next_cursor (Python) to retrieve additional pages. For pagination options, see the TypeScript and Python references.

Deleting a snapshot

Delete a snapshot when you no longer need to restore from it:

You cannot delete a snapshot while its status is creating. Deletion prevents future restores and does not affect sandboxes already restored from the snapshot.