# Cua Volume storage and sync

Where the drive keeps its bytes, the volume on this machine and in Spaces, sync across devices, and the block cache.

> Agent discovery: use [the Cua documentation index](https://cua.ai/docs/llms.txt) to find related pages and their Markdown URLs.







Runtime methods of the drive on the `Spaces` registry: Settings > Storage, the mount, sync state and the cache. `volume_sync_status` also lists the volume mounted in each Space. Files: [Cua Volume](</docs/cua-sdk/reference/spaces/volume>).

## Storage, the volume, sync and the cache

Methods of [`Spaces`](</docs/cua-sdk/reference/spaces#spaces>).

### `Spaces.volume_storage`

`volume_storage`: where the drive keeps its bytes.




**Python**



```python
async def volume_storage(self) -> DriveStorage
```






**TypeScript**



```ts
volumeStorage(asyncOpts_?: { signal: AbortSignal }): Promise<DriveStorage>
```






**Swift**



```swift
func volumeStorage() async throws -> DriveStorage
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeStorage(): DriveStorage
```






**Rust**



```rust
pub async fn volume_storage(&self) -> Result<DriveStorage, CuaError>
```






**Returns** [`DriveStorage`](#drivestorage-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_storage_set`

`volume_storage_set`: tests, and unless `dry_run` saves and switches
to, a storage backend (live, no restart).




**Python**



```python
async def volume_storage_set(self, update: DriveStorageUpdate) -> DriveStorageCheck
```






**TypeScript**



```ts
volumeStorageSet(update: DriveStorageUpdate, asyncOpts_?: { signal: AbortSignal }): Promise<DriveStorageCheck>
```






**Swift**



```swift
func volumeStorageSet(update: DriveStorageUpdate) async throws -> DriveStorageCheck
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeStorageSet(update: DriveStorageUpdate): DriveStorageCheck
```






**Rust**



```rust
pub async fn volume_storage_set(&self, update: DriveStorageUpdate) -> Result<DriveStorageCheck, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `update` | [`DriveStorageUpdate`](#drivestorageupdate-record) | required |

**Returns** [`DriveStorageCheck`](#drivestoragecheck-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_mount_status`

`volume_mount_status`: whether the drive is mounted as a volume.




**Python**



```python
async def volume_mount_status(self) -> DriveMountStatus
```






**TypeScript**



```ts
volumeMountStatus(asyncOpts_?: { signal: AbortSignal }): Promise<DriveMountStatus>
```






**Swift**



```swift
func volumeMountStatus() async throws -> DriveMountStatus
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeMountStatus(): DriveMountStatus
```






**Rust**



```rust
pub async fn volume_mount_status(&self) -> Result<DriveMountStatus, CuaError>
```






**Returns** [`DriveMountStatus`](#drivemountstatus-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_mount`

`volume_mount`: turns the mount on (kept across restarts) and mounts.




**Python**



```python
async def volume_mount(self) -> DriveMountStatus
```






**TypeScript**



```ts
volumeMount(asyncOpts_?: { signal: AbortSignal }): Promise<DriveMountStatus>
```






**Swift**



```swift
func volumeMount() async throws -> DriveMountStatus
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeMount(): DriveMountStatus
```






**Rust**



```rust
pub async fn volume_mount(&self) -> Result<DriveMountStatus, CuaError>
```






**Returns** [`DriveMountStatus`](#drivemountstatus-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_unmount`

`volume_unmount`: turns the mount off; pending uploads land first.




**Python**



```python
async def volume_unmount(self) -> DriveMountStatus
```






**TypeScript**



```ts
volumeUnmount(asyncOpts_?: { signal: AbortSignal }): Promise<DriveMountStatus>
```






**Swift**



```swift
func volumeUnmount() async throws -> DriveMountStatus
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeUnmount(): DriveMountStatus
```






**Rust**



```rust
pub async fn volume_unmount(&self) -> Result<DriveMountStatus, CuaError>
```






**Returns** [`DriveMountStatus`](#drivemountstatus-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_sync_status`

`volume_sync_status`: devices, pending uploads and conflicts.




**Python**



```python
async def volume_sync_status(self) -> DriveSyncStatus
```






**TypeScript**



```ts
volumeSyncStatus(asyncOpts_?: { signal: AbortSignal }): Promise<DriveSyncStatus>
```






**Swift**



```swift
func volumeSyncStatus() async throws -> DriveSyncStatus
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeSyncStatus(): DriveSyncStatus
```






**Rust**



```rust
pub async fn volume_sync_status(&self) -> Result<DriveSyncStatus, CuaError>
```






**Returns** [`DriveSyncStatus`](#drivesyncstatus-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_sync_events`

`volume_sync_events`: events after `since_seq`, waiting up to
`wait_ms` (at most 30000) for one.




**Python**



```python
async def volume_sync_events(self, since_seq: Optional[int], wait_ms: Optional[int]) -> DriveSyncEvents
```






**TypeScript**



```ts
volumeSyncEvents(sinceSeq: bigint | undefined, waitMs: number | undefined, asyncOpts_?: { signal: AbortSignal }): Promise<DriveSyncEvents>
```






**Swift**



```swift
func volumeSyncEvents(sinceSeq: UInt64?, waitMs: UInt32?) async throws -> DriveSyncEvents
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeSyncEvents(sinceSeq: ULong?, waitMs: UInt?): DriveSyncEvents
```






**Rust**



```rust
pub async fn volume_sync_events(&self, since_seq: Option<u64>, wait_ms: Option<u32>) -> Result<DriveSyncEvents, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `since_seq` | `Option<u64>` | required |
| `wait_ms` | `Option<u32>` | required |

**Returns** [`DriveSyncEvents`](#drivesyncevents-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_sync_resolve`

`volume_sync_resolve`: clears a conflict from the list (files stay).




**Python**



```python
async def volume_sync_resolve(self, path: str) -> None
```






**TypeScript**



```ts
volumeSyncResolve(path: string, asyncOpts_?: { signal: AbortSignal }): Promise<void>
```






**Swift**



```swift
func volumeSyncResolve(path: String) async throws
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeSyncResolve(path: String)
```






**Rust**



```rust
pub async fn volume_sync_resolve(&self, path: String) -> Result<(), CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `path` | `String` | required |

**Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_cache_stats`

`volume_cache_stats`: the block cache's size, cap and hit rate.




**Python**



```python
async def volume_cache_stats(self) -> DriveCacheStats
```






**TypeScript**



```ts
volumeCacheStats(asyncOpts_?: { signal: AbortSignal }): Promise<DriveCacheStats>
```






**Swift**



```swift
func volumeCacheStats() async throws -> DriveCacheStats
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeCacheStats(): DriveCacheStats
```






**Rust**



```rust
pub async fn volume_cache_stats(&self) -> Result<DriveCacheStats, CuaError>
```






**Returns** [`DriveCacheStats`](#drivecachestats-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_cache_set`

`volume_cache_set`: the cache's size cap (at least 256 MiB).




**Python**



```python
async def volume_cache_set(self, capacity_bytes: int) -> DriveCacheStats
```






**TypeScript**



```ts
volumeCacheSet(capacityBytes: bigint, asyncOpts_?: { signal: AbortSignal }): Promise<DriveCacheStats>
```






**Swift**



```swift
func volumeCacheSet(capacityBytes: UInt64) async throws -> DriveCacheStats
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeCacheSet(capacityBytes: ULong): DriveCacheStats
```






**Rust**



```rust
pub async fn volume_cache_set(&self, capacity_bytes: u64) -> Result<DriveCacheStats, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `capacity_bytes` | `u64` | required |

**Returns** [`DriveCacheStats`](#drivecachestats-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_cache_clear`

`volume_cache_clear`: drops every cached block.




**Python**



```python
async def volume_cache_clear(self) -> DriveCacheStats
```






**TypeScript**



```ts
volumeCacheClear(asyncOpts_?: { signal: AbortSignal }): Promise<DriveCacheStats>
```






**Swift**



```swift
func volumeCacheClear() async throws -> DriveCacheStats
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeCacheClear(): DriveCacheStats
```






**Rust**



```rust
pub async fn volume_cache_clear(&self) -> Result<DriveCacheStats, CuaError>
```






**Returns** [`DriveCacheStats`](#drivecachestats-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

## `DriveStorage` record

Where the drive keeps its bytes (Settings &gt; Storage).

Returned by [`Spaces.volume_storage`](#spacesvolume_storage).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `backend` | `String` |  | `fs` or `s3`. |
| `fs_path` / `fsPath` | `String` |  | Where the `fs` backend keeps bytes. |
| `s3` | [`Option<DriveS3Settings>`](#drives3settings-record) |  |  |
| `has_keys` / `hasKeys` | `bool` |  | S3 keys are saved (they are never returned). |
| `cloud_available` / `cloudAvailable` | `bool` |  | Always false in this release: hide the Cua cloud option. |

## `DriveS3Settings` record

Where an S3-compatible bucket is (no keys).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `endpoint` | `Option<String>` |  | `http://127.0.0.1:9000`, `https://<account>.r2.cloudflarestorage.com`; `None` for AWS. |
| `region` | `String` |  | `us-east-1`; `auto` for R2. |
| `bucket` | `String` |  |  |
| `root` | `String` |  | A key prefix inside the bucket (may be empty). |
| `path_style` / `pathStyle` | `bool` |  | Path-style addressing (MinIO and most self-hosted stores). |

## `DriveStorageUpdate` record

A storage change, or with `dry_run` a connection test.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `backend` | `String` |  | `fs` or `s3` (`cloud` is refused). |
| `s3` | [`Option<DriveS3Settings>`](#drives3settings-record) |  |  |
| `access_key_id` / `accessKeyId` | `Option<String>` |  | With `secret_access_key` (both or neither); saved in the credential store. |
| `secret_access_key` / `secretAccessKey` | `Option<String>` |  |  |
| `dry_run` / `dryRun` | `bool` |  | Only test; change nothing. |

## `DriveStorageCheck` record

What a storage test found.

Returned by [`Spaces.volume_storage_set`](#spacesvolume_storage_set).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `ok` | `bool` |  |  |
| `reachable` | `bool` |  |  |
| `authorized` | `bool` |  |  |
| `versioning` | `bool` |  | Bucket versioning is on (required). |
| `detail` | `Option<String>` |  | A sentence when not ok: what is wrong and how to fix it. |
| `problem` | `Option<String>` |  | What is wrong, to key the UI on: `unreachable`, `bad_keys`, `forbidden`, `bucket_missing`, `versioning_off`, `path_style_needed`. |
| `applied` | `bool` |  | Saved and switched live. |

## `DriveMountStatus` record

The drive as a volume.

Returned by [`Spaces.volume_mount`](#spacesvolume_mount), [`Spaces.volume_mount_status`](#spacesvolume_mount_status), [`Spaces.volume_unmount`](#spacesvolume_unmount).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled` | `bool` |  | The user's opt-in (off by default). |
| `state` | `String` |  | `off`, `mounting`, `mounted`, `needs_approval`, `unsupported`, `error`. |
| `method` | `String` |  | `nfs` (macOS), `fuse` (Linux), `fskit`, `none`. |
| `path` | `Option<String>` |  | The mount point when mounted ("Show in Finder" opens it). |
| `volume_name` / `volumeName` | `String` |  |  |
| `detail` | `Option<String>` |  |  |
| `settings_url` / `settingsUrl` | `Option<String>` |  |  |

## `DriveSyncStatus` record

Sync across devices.

Returned by [`Spaces.volume_sync_status`](#spacesvolume_sync_status).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `device_id` / `deviceId` | `String` |  |  |
| `device_name` / `deviceName` | `String` |  |  |
| `feed` | `String` |  | `live`, `off` (a store on this machine), `offline` (the bucket stopped answering; see `last_error`). |
| `poll_interval_ms` / `pollIntervalMs` | `u64` |  |  |
| `last_poll_ms` / `lastPollMs` | `u64` |  |  |
| `last_remote_change_ms` / `lastRemoteChangeMs` | `u64` |  |  |
| `pending_uploads` / `pendingUploads` | `u32` |  |  |
| `pending_bytes` / `pendingBytes` | `u64` |  |  |
| `conflicts` | [`Vec<DriveConflict>`](#driveconflict-record) |  |  |
| `devices` | [`Vec<DriveDevice>`](#drivedevice-record) |  |  |
| `last_error` / `lastError` | `Option<String>` |  |  |
| `pending` | [`Vec<DrivePendingUpload>`](#drivependingupload-record) |  | The files still uploading, largest first (at most 100). |
| `backend` | `String` |  | `fs` (This Mac) or `s3` (your bucket). |
| `mount` | `String` |  | This machine's mount: `off`, `mounting`, `mounted`, `needs_approval`, `unsupported` or `error`. |
| `cache` | [`Option<DriveCacheStats>`](#drivecachestats-record) |  | The block cache in front of a bucket. |
| `volumes` | [`Vec<DriveSpaceVolume>`](#drivespacevolume-record) |  | The volume mounted in Spaces. |

## `DrivePendingUpload` record

A file waiting to upload.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `String` |  |  |
| `bytes` | `u64` |  |  |

## `DriveSpaceVolume` record

The volume mounted in a Space's guest.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `space` | `String` |  |  |
| `mount_path` / `mountPath` | `String` |  | `/volume` (Linux) or `~/Cua Volume` (macOS), as the guest sees it. |
| `backend` | `String` |  | `fs` (FUSE) or `nfs`. |
| `principal` | `String` |  | Whose view it shows: `space:<folder>`, or `agent:<name>` while a persistent agent runs there. |

## `DriveConflict` record

A write that lost to a later one, kept in history and as a copy.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `String` |  |  |
| `conflict_path` / `conflictPath` | `String` |  |  |
| `winner_device` / `winnerDevice` | `String` |  |  |
| `loser_device` / `loserDevice` | `String` |  |  |
| `winner_version` / `winnerVersion` | `String` |  |  |
| `loser_version` / `loserVersion` | `String` |  |  |
| `ts_ms` / `tsMs` | `u64` |  |  |

## `DriveDevice` record

A device sharing the drive's bucket.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `String` |  |  |
| `name` | `String` |  |  |
| `this_device` / `thisDevice` | `bool` |  |  |
| `last_seen_ms` / `lastSeenMs` | `u64` |  |  |
| `last_change_ms` / `lastChangeMs` | `u64` |  |  |
| `changes` | `u64` |  |  |

## `DriveSyncEvents` record

Events after a sequence number, and the sequence to ask after next.

Returned by [`Spaces.volume_sync_events`](#spacesvolume_sync_events).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `events` | [`Vec<DriveSyncEvent>`](#drivesyncevent-record) |  |  |
| `next_seq` / `nextSeq` | `u64` |  |  |

## `DriveSyncEvent` record

One sync event.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `seq` | `u64` |  |  |
| `ts_ms` / `tsMs` | `u64` |  |  |
| `kind` | `String` |  | `remote_change`, `remote_delete`, `upload_started`, `upload_done`, `upload_failed`, `conflict`, `error`. |
| `path` | `String` |  |  |
| `device` | `String` |  |  |
| `size` | `u64` |  |  |
| `version` | `String` |  |  |
| `detail` | `String` |  |  |

## `DriveCacheStats` record

The block cache in front of a remote store.

Returned by [`Spaces.volume_cache_clear`](#spacesvolume_cache_clear), [`Spaces.volume_cache_set`](#spacesvolume_cache_set), [`Spaces.volume_cache_stats`](#spacesvolume_cache_stats).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `dir` | `String` |  |  |
| `size_bytes` / `sizeBytes` | `u64` |  |  |
| `capacity_bytes` / `capacityBytes` | `u64` |  |  |
| `block_bytes` / `blockBytes` | `u64` |  |  |
| `blocks` | `u64` |  |  |
| `hits` | `u64` |  |  |
| `misses` | `u64` |  |  |
| `hit_rate` / `hitRate` | `f64` |  |  |
| `prefetched_bytes` / `prefetchedBytes` | `u64` |  |  |
| `evictions` | `u64` |  |  |