---
title: Volumes
description: 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
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
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
async fn list() -> MicrosandboxResult<Vec<VolumeHandle>>
```

List all named volumes.

**Returns**

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

---

#### Volume::remove()

```rust
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
async fn create(self) -> MicrosandboxResult<Volume>
```

Create the volume on disk.

**Returns**

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

---

#### quota()

```rust
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
fn directory(self) -> Self
```

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

---

#### disk()

```rust
fn disk(self) -> Self
```

Create a raw ext4 disk-backed named volume.

---

#### size()

```rust
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
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
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
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
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
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
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
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
fn format(self, format: DiskImageFormat) -> Self
```

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

---

#### fstype()

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