> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Snapshots

> Capture and manage snapshots with the Ruby SDK.

See [Snapshots](/sandboxes/snapshots) for capture behavior and compatibility. Ruby does not expose sandbox restore, branching, or full-capture options.

## SandboxHandle

#### <span className="msb-recv">handle.</span><span className="msb-hn">snapshot()</span>

```ruby theme={null}
handle.snapshot(name) # => Hash
```

<Accordion title="Example">
  ```ruby theme={null}
  handle = Microsandbox::Sandbox.get("worker")
  checkpoint = handle.snapshot("after-build")
  puts checkpoint["reference"]
  ```
</Accordion>

Capture a named snapshot using the selected backend's default capture behavior. Local group members are immutable; choose a new name for each checkpoint.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>name</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Snapshot name.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">Hash</span></div>
    <div className="msb-param-desc">String keys: digest, reference, reference\_kind, and size\_bytes.</div>
  </div>
</div>

## Snapshot

#### <span className="msb-recv">Microsandbox::Snapshot.</span><span className="msb-hn">open()</span>

```ruby theme={null}
Microsandbox::Snapshot.open(reference) # => Snapshot
```

Open a snapshot using the selected backend.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>reference</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Snapshot reference or name.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">Snapshot</span></div>
    <div className="msb-param-desc">Open a snapshot using the selected backend.</div>
  </div>
</div>

#### <span className="msb-recv">Microsandbox::Snapshot.</span><span className="msb-hn">get()</span>

```ruby theme={null}
Microsandbox::Snapshot.get(name) # => SnapshotHandle
```

Look up snapshot metadata using the selected backend.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>name</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Snapshot reference or name.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">SnapshotHandle</span></div>
    <div className="msb-param-desc">Look up snapshot metadata using the selected backend.</div>
  </div>
</div>

#### <span className="msb-recv">Microsandbox::Snapshot.</span><span className="msb-hn">list()</span>

```ruby theme={null}
Microsandbox::Snapshot.list # => Array<SnapshotHandle>
```

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">Array\<SnapshotHandle></span></div>
    <div className="msb-param-desc">List snapshots using the selected backend.</div>
  </div>
</div>

#### <span className="msb-recv">Microsandbox::Snapshot.</span><span className="msb-hn">remove()</span>

```ruby theme={null}
Microsandbox::Snapshot.remove(name, force = false) # => nil
```

Remove a snapshot using the selected backend.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>name</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Snapshot reference or name.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>force</code><span className="msb-type">Boolean</span></div>
    <div className="msb-param-desc">Force removal; optional positional argument, defaults to false.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">nil</span></div>
    <div className="msb-param-desc">No return value.</div>
  </div>
</div>

#### <span className="msb-recv">Microsandbox::Snapshot.</span><span className="msb-hn">save()</span>

```ruby theme={null}
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.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>reference</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Snapshot reference.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>output\_path</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Destination archive path on the host.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>with\_parents</code><span className="msb-type">Boolean</span></div>
    <div className="msb-param-desc">Include parent snapshots; defaults to false.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>with\_image</code><span className="msb-type">Boolean</span></div>
    <div className="msb-param-desc">Include the source image; defaults to false.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>plain\_tar</code><span className="msb-type">Boolean</span></div>
    <div className="msb-param-desc">Write an uncompressed tar archive; defaults to false.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>since</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Optional incremental export boundary; available only on this class method.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>last\_layers</code><span className="msb-type">Integer</span></div>
    <div className="msb-param-desc">Optional number of most recent layers to export; available only on this class method.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">nil</span></div>
    <div className="msb-param-desc">No return value.</div>
  </div>
</div>

#### <span className="msb-recv">snapshot.</span><span className="msb-hn">save\_to()</span>

```ruby theme={null}
snapshot.save_to(output_path, **options) # => nil
```

<Accordion title="Example">
  ```ruby theme={null}
  snapshot = Microsandbox::Snapshot.open("after-build")
  snapshot.save_to("./after-build.tar.zst", with_image: true)
  ```
</Accordion>

Export through the backend retained by this snapshot. Archive export is local-only.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>output\_path</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Destination archive path on the host.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>with\_parents</code><span className="msb-type">Boolean</span></div>
    <div className="msb-param-desc">Include parent snapshots; defaults to false.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>with\_image</code><span className="msb-type">Boolean</span></div>
    <div className="msb-param-desc">Include the source image; defaults to false.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>plain\_tar</code><span className="msb-type">Boolean</span></div>
    <div className="msb-param-desc">Write an uncompressed tar archive; defaults to false.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">nil</span></div>
    <div className="msb-param-desc">No return value.</div>
  </div>
</div>

#### <span className="msb-recv">snapshot.</span><span className="msb-hn">digest</span>

```ruby theme={null}
snapshot.digest # => String
```

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Snapshot digest.</div>
  </div>
</div>

#### <span className="msb-recv">snapshot.</span><span className="msb-hn">size\_bytes</span>

```ruby theme={null}
snapshot.size_bytes # => Integer | nil
```

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">Integer | nil</span></div>
    <div className="msb-param-desc">Snapshot size.</div>
  </div>
</div>

#### <span className="msb-recv">snapshot.</span><span className="msb-hn">reference</span>

```ruby theme={null}
snapshot.reference # => String
```

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Backend-specific reference.</div>
  </div>
</div>

#### <span className="msb-recv">snapshot.</span><span className="msb-hn">reference\_kind</span>

```ruby theme={null}
snapshot.reference_kind # => String
```

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Kind of reference; preserve it with the value.</div>
  </div>
</div>

## SnapshotHandle

#### <span className="msb-recv">handle.</span><span className="msb-hn">digest</span>

```ruby theme={null}
handle.digest # => String
```

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Snapshot digest.</div>
  </div>
</div>

#### <span className="msb-recv">handle.</span><span className="msb-hn">size\_bytes</span>

```ruby theme={null}
handle.size_bytes # => Integer | nil
```

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">Integer | nil</span></div>
    <div className="msb-param-desc">Snapshot size.</div>
  </div>
</div>

#### <span className="msb-recv">handle.</span><span className="msb-hn">reference</span>

```ruby theme={null}
handle.reference # => String
```

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Backend-specific reference.</div>
  </div>
</div>

#### <span className="msb-recv">handle.</span><span className="msb-hn">reference\_kind</span>

```ruby theme={null}
handle.reference_kind # => String
```

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Kind of reference; preserve it with the value.</div>
  </div>
</div>

#### <span className="msb-recv">handle.</span><span className="msb-hn">name</span>

```ruby theme={null}
handle.name # => String | nil
```

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">String | nil</span></div>
    <div className="msb-param-desc">Snapshot name.</div>
  </div>
</div>

#### <span className="msb-recv">handle.</span><span className="msb-hn">image\_ref</span>

```ruby theme={null}
handle.image_ref # => String
```

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Source image reference.</div>
  </div>
</div>

#### <span className="msb-recv">handle.</span><span className="msb-hn">state\_kind</span>

```ruby theme={null}
handle.state_kind # => String
```

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Captured state kind.</div>
  </div>
</div>

#### <span className="msb-recv">handle.</span><span className="msb-hn">open()</span>

```ruby theme={null}
handle.open # => Snapshot
```

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">Snapshot</span></div>
    <div className="msb-param-desc">Open the snapshot through the retained backend.</div>
  </div>
</div>

#### <span className="msb-recv">handle.</span><span className="msb-hn">remove()</span>

```ruby theme={null}
handle.remove(force) # => nil
```

Remove the snapshot through the retained backend.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>force</code><span className="msb-type">Boolean</span></div>
    <div className="msb-param-desc">Whether to force removal. This positional argument is required.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">nil</span></div>
    <div className="msb-param-desc">No return value.</div>
  </div>
</div>

#### <span className="msb-recv">handle.</span><span className="msb-hn">save\_to()</span>

```ruby theme={null}
handle.save_to(output_path, **options) # => nil
```

Export through the backend retained by this handle. Archive export is local-only.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>output\_path</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Destination archive path on the host.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>with\_parents</code><span className="msb-type">Boolean</span></div>
    <div className="msb-param-desc">Include parent snapshots; defaults to false.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>with\_image</code><span className="msb-type">Boolean</span></div>
    <div className="msb-param-desc">Include the source image; defaults to false.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>plain\_tar</code><span className="msb-type">Boolean</span></div>
    <div className="msb-param-desc">Write an uncompressed tar archive; defaults to false.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">nil</span></div>
    <div className="msb-param-desc">No return value.</div>
  </div>
</div>