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

> Rust SDK - Volume API reference

See [Volumes](/sandboxes/volumes) for usage examples and patterns.

## Volume

Named volumes are managed by microsandbox and stored by default under `~/.microsandbox/volumes/<name>/`. They persist independently of any sandbox.

***

#### Volume::builder()

```rust theme={null}
fn builder(name: impl Into<String>) -> VolumeBuilder
```

Create a builder for a new named volume. Directory-backed volumes are the default. Call `.disk().size(...)` to create a disk-backed volume.

**Parameters**

| Name | Type                | Description                      |
| ---- | ------------------- | -------------------------------- |
| name | `impl Into<String>` | Volume name (e.g. `"pip-cache"`) |

**Returns**

| Type                              | Description                                                                    |
| --------------------------------- | ------------------------------------------------------------------------------ |
| [`VolumeBuilder`](#volumebuilder) | Builder with `.directory()`, `.disk()`, `.size()`, `.quota()`, and `.create()` |

***

#### Volume::get()

```rust theme={null}
async fn get(name: &str) -> MicrosandboxResult<VolumeHandle>
```

Get a handle to an existing named volume. Use the handle to access the volume's filesystem from the host or to delete it.

**Parameters**

| Name | Type   | Description |
| ---- | ------ | ----------- |
| name | `&str` | Volume name |

**Returns**

| Type                            | Description                     |
| ------------------------------- | ------------------------------- |
| [`VolumeHandle`](#volumehandle) | Handle for host-side operations |

***

#### Volume::list()

```rust theme={null}
async fn list() -> MicrosandboxResult<Vec<VolumeHandle>>
```

List all named volumes.

**Returns**

| Type                                     | Description        |
| ---------------------------------------- | ------------------ |
| `Vec<`[`VolumeHandle`](#volumehandle)`>` | All volume handles |

***

#### Volume::remove()

```rust theme={null}
async fn remove(name: &str) -> MicrosandboxResult<()>
```

Delete a named volume and its contents from disk. Fails if the volume is currently mounted by a running sandbox.

**Parameters**

| Name | Type   | Description |
| ---- | ------ | ----------- |
| name | `&str` | Volume name |

***

## VolumeBuilder

Builder for creating a named volume.

***

#### create()

```rust theme={null}
async fn create(self) -> MicrosandboxResult<Volume>
```

Create the volume on disk.

**Returns**

| Type     | Description        |
| -------- | ------------------ |
| `Volume` | The created volume |

***

#### quota()

```rust theme={null}
fn quota(self, mib: u64) -> Self
```

Set the recorded quota metadata for a directory-backed volume.

**Parameters**

| Name | Type  | Description  |
| ---- | ----- | ------------ |
| mib  | `u64` | Quota in MiB |

***

#### directory()

```rust theme={null}
fn directory(self) -> Self
```

Create a directory-backed named volume. This is the default.

***

#### disk()

```rust theme={null}
fn disk(self) -> Self
```

Create a raw ext4 disk-backed named volume.

***

#### size()

```rust theme={null}
fn size(self, size: impl Into<Mebibytes>) -> Self
```

Set disk volume capacity. Required after `.disk()`.

***

## MountBuilder

Builder for configuring a volume mount. Used in `SandboxBuilder::volume(path, |v| v...)`.

***

#### bind()

```rust theme={null}
fn bind(self, host_path: impl Into<PathBuf>) -> Self
```

Mount a host directory into the sandbox. Changes in the guest are reflected on the host and vice versa.

**Parameters**

| Name       | Type                 | Description                |
| ---------- | -------------------- | -------------------------- |
| host\_path | `impl Into<PathBuf>` | Directory path on the host |

***

#### named()

```rust theme={null}
fn named(self, name: impl Into<String>) -> Self
```

Mount a named volume. The volume must already exist (create it with [`Volume::builder()`](#volumebuilder)).

**Parameters**

| Name | Type                | Description |
| ---- | ------------------- | ----------- |
| name | `impl Into<String>` | Volume name |

***

#### named\_with()

```rust theme={null}
fn named_with(
    self,
    name: impl Into<String>,
    f: impl FnOnce(NamedVolumeBuilder) -> NamedVolumeBuilder,
) -> Self
```

Mount a named volume with explicit sandbox-time existence behavior. `NamedVolumeMode::Existing` is the default and behaves like [`named()`](#named). `.create()` creates the volume and fails if it already exists. `.ensure_exists()` creates the volume if it is missing or reuses an existing compatible volume.

```rust theme={null}
let sb = Sandbox::builder("worker")
    .image("python")
    .volume("/cache", |v| v.named_with("pip-cache", |n| n.ensure_exists()))
    .volume("/var/lib/docker", |v| {
        v.named_with("docker-data", |n| n.ensure_exists().disk().size(20.gib()))
    })
    .create()
    .await?;
```

The ensure-exists mode validates existing volume metadata. It errors when the existing volume has a different kind, quota, capacity, or explicitly requested labels than the requested configuration; it does not mutate existing volume metadata.

**Named volume builder methods**

| Method              | Description                                                                                                                |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `existing()`        | Require the volume to already exist. This is the default.                                                                  |
| `create()`          | Create the volume and fail if it already exists.                                                                           |
| `ensure_exists()`   | Create the volume if missing or reuse a compatible existing volume.                                                        |
| `directory()`       | Use directory-backed storage. This is the default.                                                                         |
| `disk()`            | Use disk-backed raw ext4 storage. Requires `size(...)` when creating or ensuring a missing volume.                         |
| `size(size)`        | Disk capacity.                                                                                                             |
| `quota(size)`       | Directory volume quota.                                                                                                    |
| `label(key, value)` | Attach a label to newly-created volumes and require matching labels for ensure-existing volumes when labels are requested. |

***

#### readonly()

```rust theme={null}
fn readonly(self) -> Self
```

Mount as read-only. The guest can read but not write, and virtiofs-backed mounts also reject writes in the host filesystem server.

***

#### noexec()

```rust theme={null}
fn noexec(self) -> Self
```

Prevent direct execution from this mount. Interpreters can still read scripts from the mount, such as `sh /mnt/script.sh`.

***

#### disk()

```rust theme={null}
fn disk(self, host_path: impl Into<PathBuf>) -> Self
```

Mount a host disk image as a virtio-blk device. The disk image format defaults from the extension (`.qcow2`, `.raw`, `.vmdk`; otherwise raw).

***

#### format()

```rust theme={null}
fn format(self, format: DiskImageFormat) -> Self
```

Set the disk image format explicitly. Valid only with [`disk()`](#disk).

***

#### fstype()

```rust theme={null}
fn fstype(self, fstype: impl Into<String>) -> Self
```

Set the inner filesystem type for a disk-image volume, for example `"ext4"`. If omitted, agentd probes supported filesystems and uses the first type that mounts cleanly. Empty values and mount-spec separators are rejected.

***

#### size()

```rust theme={null}
fn size(self, mib: impl Into<Mebibytes>) -> Self
```

Set the size limit for a tmpfs mount. Valid only for tmpfs mounts.

**Parameters**

| Name | Type                   | Description       |
| ---- | ---------------------- | ----------------- |
| mib  | `impl Into<Mebibytes>` | Size limit in MiB |

***

#### tmpfs()

```rust theme={null}
fn tmpfs(self) -> Self
```

Use an in-memory filesystem. Contents are discarded when the sandbox stops. Good for scratch space, temp files, and build artifacts.

***

## Types

### VolumeHandle

Handle for interacting with a named volume from the host side.

| Property / Method | Type             | Description                                                                  |
| ----------------- | ---------------- | ---------------------------------------------------------------------------- |
| fs()              | `VolumeFsHandle` | Host-side filesystem access - read and write files without a running sandbox |
| name()            | `&str`           | Volume name                                                                  |
| kind()            | `VolumeKind`     | Volume kind: `Directory` or `Disk`                                           |
| capacity\_bytes() | `Option<u64>`    | Disk capacity in bytes                                                       |
| disk\_format()    | `Option<&str>`   | Disk image format                                                            |
| disk\_fstype()    | `Option<&str>`   | Disk filesystem type                                                         |
| remove()          | `()`             | Delete this volume from disk                                                 |