Ruby SDK Snapshots reference

See Snapshots for capture behavior and compatibility. Ruby does not expose sandbox restore, branching, or full-capture options.

SandboxHandle

handle.snapshot()

handle.snapshot(name) # => Hash

Example

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()

Microsandbox::Snapshot.open(reference) # => Snapshot

Open a snapshot using the selected backend.

Parameters

referenceString

Snapshot reference or name.

Returns

Snapshot

Open a snapshot using the selected backend.

Microsandbox::Snapshot.get()

Microsandbox::Snapshot.get(name) # => SnapshotHandle

Look up snapshot metadata using the selected backend.

Parameters

nameString

Snapshot reference or name.

Returns

SnapshotHandle

Look up snapshot metadata using the selected backend.

Microsandbox::Snapshot.list()

Microsandbox::Snapshot.list # => Array<SnapshotHandle>

Returns

Array<SnapshotHandle>

List snapshots using the selected backend.

Microsandbox::Snapshot.remove()

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()

Microsandbox::Snapshot.save(reference, output_path, **options) # => nil

Export a local snapshot archive. See snapshot exports 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()

snapshot.save_to(output_path, **options) # => nil

Example

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

snapshot.digest # => String

Returns

String

Snapshot digest.

snapshot.size_bytes

snapshot.size_bytes # => Integer | nil

Returns

Integer | nil

Snapshot size.

snapshot.reference

snapshot.reference # => String

Returns

String

Backend-specific reference.

snapshot.reference_kind

snapshot.reference_kind # => String

Returns

String

Kind of reference; preserve it with the value.

SnapshotHandle

handle.digest

handle.digest # => String

Returns

String

Snapshot digest.

handle.size_bytes

handle.size_bytes # => Integer | nil

Returns

Integer | nil

Snapshot size.

handle.reference

handle.reference # => String

Returns

String

Backend-specific reference.

handle.reference_kind

handle.reference_kind # => String

Returns

String

Kind of reference; preserve it with the value.

handle.name

handle.name # => String | nil

Returns

String | nil

Snapshot name.

handle.image_ref

handle.image_ref # => String

Returns

String

Source image reference.

handle.state_kind

handle.state_kind # => String

Returns

String

Captured state kind.

handle.open()

handle.open # => Snapshot

Returns

Snapshot

Open the snapshot through the retained backend.

handle.remove()

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()

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.

Getting Started

SDKs

CLI

Snapshots

SandboxHandle

handle.snapshot()

Snapshot

Microsandbox::Snapshot.open()

Microsandbox::Snapshot.get()

Microsandbox::Snapshot.list()

Microsandbox::Snapshot.remove()

Microsandbox::Snapshot.save()

snapshot.save_to()

snapshot.digest

snapshot.size_bytes

snapshot.reference

snapshot.reference_kind

SnapshotHandle

handle.digest

handle.size_bytes

handle.reference

handle.reference_kind

handle.name

handle.image_ref

handle.state_kind

handle.open()

handle.remove()

handle.save_to()

​SandboxHandle

​handle.snapshot()

​Snapshot

​Microsandbox::Snapshot.open()

​Microsandbox::Snapshot.get()

​Microsandbox::Snapshot.list()

​Microsandbox::Snapshot.remove()

​Microsandbox::Snapshot.save()

​snapshot.save_to()

​snapshot.digest

​snapshot.size_bytes

​snapshot.reference

​snapshot.reference_kind

​SnapshotHandle

​handle.digest

​handle.size_bytes

​handle.reference

​handle.reference_kind

​handle.name

​handle.image_ref

​handle.state_kind

​handle.open()

​handle.remove()

​handle.save_to()

SandboxHandle

handle.snapshot()

Snapshot

Microsandbox::Snapshot.open()

Microsandbox::Snapshot.get()

Microsandbox::Snapshot.list()

Microsandbox::Snapshot.remove()

Microsandbox::Snapshot.save()

snapshot.save_to()

snapshot.digest

snapshot.size_bytes

snapshot.reference

snapshot.reference_kind

SnapshotHandle

handle.digest

handle.size_bytes

handle.reference

handle.reference_kind

handle.name

handle.image_ref

handle.state_kind

handle.open()

handle.remove()

handle.save_to()