--- title: Snapshots "og:title": Ruby SDK Snapshots reference description: Capture and manage snapshots with the Ruby SDK. --- See [Snapshots](/sandboxes/snapshots) for capture behavior and compatibility. Ruby does not expose sandbox restore or full-capture options. See [forking availability](#forking). ## SandboxHandle #### handle.snapshot() ```ruby handle.snapshot(name) # => Hash ``` ```ruby handle = Microsandbox::Sandbox.get("worker") checkpoint = handle.snapshot("after-build") puts checkpoint["reference"] ``` Capture a named snapshot using the selected backend's default capture behavior. Local group members are immutable; choose a new name for each checkpoint.

Parameters

nameString

Snapshot name.

Returns

Hash

String keys: digest, reference, reference_kind, and size_bytes.

## Snapshot #### Microsandbox::Snapshot.open() ```ruby Microsandbox::Snapshot.open(reference) # => Snapshot ``` Open a snapshot using the selected backend.

Parameters

referenceString

Snapshot reference or name.

Returns

Snapshot

The opened snapshot.

#### Microsandbox::Snapshot.get() ```ruby Microsandbox::Snapshot.get(name) # => SnapshotHandle ``` Look up snapshot metadata using the selected backend.

Parameters

nameString

Snapshot reference or name.

Returns

SnapshotHandle

Snapshot metadata and lifecycle handle.

#### Microsandbox::Snapshot.list() ```ruby Microsandbox::Snapshot.list # => Array ```

Returns

Array<SnapshotHandle>

List snapshots using the selected backend.

#### Microsandbox::Snapshot.remove() ```ruby Microsandbox::Snapshot.remove(name, force = false) # => nil ``` Remove a snapshot using the selected backend.

Parameters

nameString

Snapshot reference or name.

forceBoolean

Force removal; optional positional argument, defaults to false.

Returns

nil

No return value.

#### Microsandbox::Snapshot.save() ```ruby Microsandbox::Snapshot.save(reference, output_path, **options) # => nil ``` Export a local snapshot archive. See [snapshot exports](/sandboxes/snapshots#move-snapshots) for parent chains and incremental exports.

Parameters

referenceString

Snapshot reference.

output_pathString

Destination archive path on the host.

with_parentsBoolean

Include parent snapshots; defaults to false.

with_imageBoolean

Include the source image; defaults to false.

plain_tarBoolean

Write an uncompressed tar archive; defaults to false.

sinceString

Optional incremental export boundary; available only on this class method.

last_layersInteger

Optional number of most recent layers to export; available only on this class method.

Returns

nil

No return value.

#### snapshot.save_to() ```ruby snapshot.save_to(output_path, **options) # => nil ``` ```ruby snapshot = Microsandbox::Snapshot.open("after-build") snapshot.save_to("./after-build.tar.zst", with_image: true) ``` Export through the backend retained by this snapshot. Archive export is local-only.

Parameters

output_pathString

Destination archive path on the host.

with_parentsBoolean

Include parent snapshots; defaults to false.

with_imageBoolean

Include the source image; defaults to false.

plain_tarBoolean

Write an uncompressed tar archive; defaults to false.

Returns

nil

No return value.

#### snapshot.digest ```ruby snapshot.digest # => String ```

Returns

String

Snapshot digest.

#### snapshot.size_bytes ```ruby snapshot.size_bytes # => Integer | nil ```

Returns

Integer | nil

Snapshot size.

#### snapshot.reference ```ruby snapshot.reference # => String ```

Returns

String

Backend-specific reference.

#### snapshot.reference_kind ```ruby snapshot.reference_kind # => String ```

Returns

String

Kind of reference; preserve it with the value.

## SnapshotHandle #### handle.digest ```ruby handle.digest # => String ```

Returns

String

Snapshot digest.

#### handle.size_bytes ```ruby handle.size_bytes # => Integer | nil ```

Returns

Integer | nil

Snapshot size.

#### handle.reference ```ruby handle.reference # => String ```

Returns

String

Backend-specific reference.

#### handle.reference_kind ```ruby handle.reference_kind # => String ```

Returns

String

Kind of reference; preserve it with the value.

#### handle.name ```ruby handle.name # => String | nil ```

Returns

String | nil

Snapshot name.

#### handle.image_ref ```ruby handle.image_ref # => String ```

Returns

String

Source image reference.

#### handle.state_kind ```ruby handle.state_kind # => String ```

Returns

String

Captured state kind.

#### handle.open() ```ruby handle.open # => Snapshot ```

Returns

Snapshot

Open the snapshot through the retained backend.

#### handle.remove() ```ruby handle.remove(force) # => nil ``` Remove the snapshot through the retained backend.

Parameters

forceBoolean

Whether to force removal. This positional argument is required.

Returns

nil

No return value.

#### handle.save_to() ```ruby handle.save_to(output_path, **options) # => nil ``` Export through the backend retained by this handle. Archive export is local-only.

Parameters

output_pathString

Destination archive path on the host.

with_parentsBoolean

Include parent snapshots; defaults to false.

with_imageBoolean

Include the source image; defaults to false.

plain_tarBoolean

Write an uncompressed tar archive; defaults to false.

Returns

nil

No return value.

## Forking The Ruby SDK does not currently expose single or batch sandbox forking. For supported APIs and examples, see [TypeScript](/sdk/typescript/snapshots#forking), [Rust](/sdk/rust/snapshots#forking), [Python](/sdk/python/snapshots#forking), or [Go](/sdk/go/snapshots#forking).