> ## 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.

# Volumes

> Create and manage named volumes with the Ruby SDK.

See [Volumes](/sandboxes/volumes) for storage behavior. Ruby exposes named-volume management but not the complete mount builder available in Rust.

## Volume

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

```ruby theme={null}
Microsandbox::Volume.builder(name) # => VolumeBuilder
```

Configure a named volume.

<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">Volume 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">VolumeBuilder</span></div>
    <div className="msb-param-desc">Configure a named volume.</div>
  </div>
</div>

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

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

Look up a named volume.

<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">Volume 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">VolumeHandle</span></div>
    <div className="msb-param-desc">Look up a named volume.</div>
  </div>
</div>

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

```ruby theme={null}
Microsandbox::Volume.list # => Array<VolumeHandle>
```

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">Array\<VolumeHandle></span></div>
    <div className="msb-param-desc">List named volumes.</div>
  </div>
</div>

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

```ruby theme={null}
Microsandbox::Volume.remove(name) # => nil
```

Remove a named volume.

<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">Volume 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">nil</span></div>
    <div className="msb-param-desc">No return value.</div>
  </div>
</div>

## VolumeBuilder

#### <span className="msb-recv">builder.</span><span className="msb-hn">directory()</span>

```ruby theme={null}
builder.directory # => VolumeBuilder
```

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">VolumeBuilder</span></div>
    <div className="msb-param-desc">Select a directory volume.</div>
  </div>
</div>

#### <span className="msb-recv">builder.</span><span className="msb-hn">disk()</span>

```ruby theme={null}
builder.disk # => VolumeBuilder
```

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">VolumeBuilder</span></div>
    <div className="msb-param-desc">Select a disk volume (local only).</div>
  </div>
</div>

#### <span className="msb-recv">builder.</span><span className="msb-hn">quota()</span>

```ruby theme={null}
builder.quota(mib) # => VolumeBuilder
```

Set quota in MiB.

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>mib</code><span className="msb-type">Integer</span></div>
    <div className="msb-param-desc">Capacity in MiB.</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">VolumeBuilder</span></div>
    <div className="msb-param-desc">Set quota in MiB.</div>
  </div>
</div>

#### <span className="msb-recv">builder.</span><span className="msb-hn">size()</span>

```ruby theme={null}
builder.size(mib) # => VolumeBuilder
```

Set disk size in MiB.

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>mib</code><span className="msb-type">Integer</span></div>
    <div className="msb-param-desc">Capacity in MiB.</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">VolumeBuilder</span></div>
    <div className="msb-param-desc">Set disk size in MiB.</div>
  </div>
</div>

#### <span className="msb-recv">builder.</span><span className="msb-hn">label()</span>

```ruby theme={null}
builder.label(key, value) # => VolumeBuilder
```

Add a string label.

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

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

  <div className="msb-param">
    <div className="msb-param-key"><code>value</code><span className="msb-type">String</span></div>
    <div className="msb-param-desc">Label value.</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">VolumeBuilder</span></div>
    <div className="msb-param-desc">Add a string label.</div>
  </div>
</div>

#### <span className="msb-recv">builder.</span><span className="msb-hn">create()</span>

```ruby theme={null}
builder.create # => VolumeHandle
```

<Accordion title="Example">
  ```ruby theme={null}
  volume = Microsandbox::Volume.builder("build-cache")
    .directory
    .label("purpose", "build")
    .create
  puts volume.name
  ```
</Accordion>

Create the volume; consumes the builder.

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">VolumeHandle</span></div>
    <div className="msb-param-desc">Create the volume; consumes the builder.</div>
  </div>
</div>

## VolumeHandle

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

```ruby theme={null}
volume.name # => 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">Volume name.</div>
  </div>
</div>

#### <span className="msb-recv">volume.</span><span className="msb-hn">kind</span>

```ruby theme={null}
volume.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">dir or disk.</div>
  </div>
</div>

#### <span className="msb-recv">volume.</span><span className="msb-hn">quota\_mib</span>

```ruby theme={null}
volume.quota_mib # => 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">Configured quota.</div>
  </div>
</div>

#### <span className="msb-recv">volume.</span><span className="msb-hn">used\_bytes</span>

```ruby theme={null}
volume.used_bytes # => Integer
```

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

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">Integer</span></div>
    <div className="msb-param-desc">Used bytes.</div>
  </div>
</div>

#### <span className="msb-recv">volume.</span><span className="msb-hn">capacity\_bytes</span>

```ruby theme={null}
volume.capacity_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">Capacity.</div>
  </div>
</div>

#### <span className="msb-recv">volume.</span><span className="msb-hn">labels</span>

```ruby theme={null}
volume.labels # => Hash
```

<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 and values.</div>
  </div>
</div>

#### <span className="msb-recv">volume.</span><span className="msb-hn">created\_at</span>

```ruby theme={null}
volume.created_at # => 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">RFC 3339 creation timestamp.</div>
  </div>
</div>

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

```ruby theme={null}
volume.remove # => nil
```

Remove this volume.

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