Cua Volume

The versioned volume every Space and agent shares: files, history, grants, requests, audit, storage and sync.

Cua Volume methods on the Spaces registry. Access is checked by the runtime; pass a DriveView to see the drive as a persistent agent does. Grants and approvals ask the user for presence. Guide: Cua Volume.

Drive methods#

Methods of Spaces.

`Spaces.volume_ls`#

volume_ls: a folder's immediate children (default the root).

async def volume_ls(self, path: Optional[str], view: Optional[DriveView]) -> DriveListing

Parameter	Type	Default
`path`	`Option<String>`	required
`view`	`Option<DriveView>`	required

Returns DriveListing · Async · Raises CuaError

`Spaces.volume_read`#

volume_read: a file (or one of its versions).

async def volume_read(self, path: str, version: Optional[str], view: Optional[DriveView]) -> DriveFile

Parameter	Type	Default
`path`	`String`	required
`version`	`Option<String>`	required
`view`	`Option<DriveView>`	required

Returns DriveFile · Async · Raises CuaError

`Spaces.volume_write`#

volume_write: a new version of a file. if_etag makes it a compare-and-swap, create_only makes it create-only.

async def volume_write(self, path: str, content: bytes, if_etag: Optional[str], create_only: bool, view: Optional[DriveView]) -> DriveObject

Parameter	Type	Default
`path`	`String`	required
`content`	`Vec<u8>`	required
`if_etag`	`Option<String>`	required
`create_only`	`bool`	required
`view`	`Option<DriveView>`	required

Returns DriveObject · Async · Raises CuaError

`Spaces.volume_delete`#

volume_delete: a delete marker (history stays).

async def volume_delete(self, path: str, if_etag: Optional[str], view: Optional[DriveView]) -> None

Parameter	Type	Default
`path`	`String`	required
`if_etag`	`Option<String>`	required
`view`	`Option<DriveView>`	required

Async · Raises CuaError

`Spaces.volume_history`#

volume_history: a file's versions, newest first.

async def volume_history(self, path: str, view: Optional[DriveView]) -> List[DriveVersion]

Parameter	Type	Default
`path`	`String`	required
`view`	`Option<DriveView>`	required

Returns Vec<DriveVersion> · Async · Raises CuaError

`Spaces.volume_restore`#

volume_restore: makes an old version current again.

async def volume_restore(self, path: str, version: str, view: Optional[DriveView]) -> DriveObject

Parameter	Type	Default
`path`	`String`	required
`version`	`String`	required
`view`	`Option<DriveView>`	required

Returns DriveObject · Async · Raises CuaError

`Spaces.volume_grant`#

volume_grant: widens principal's access (agent:<name> or space:<id>, mode r or rw). The user confirms with presence.

async def volume_grant(self, principal: str, prefix: str, mode: str, expires_in_secs: Optional[int], note: Optional[str]) -> DriveGrant

Parameter	Type	Default
`principal`	`String`	required
`prefix`	`String`	required
`mode`	`String`	required
`expires_in_secs`	`Option<u64>`	required
`note`	`Option<String>`	required

Returns DriveGrant · Async · Raises CuaError

`Spaces.volume_revoke`#

volume_revoke.

async def volume_revoke(self, grant_id: str) -> DriveGrant

Parameter	Type	Default
`grant_id`	`String`	required

Returns DriveGrant · Async · Raises CuaError

`Spaces.volume_grants`#

volume_grants: live grants (every grant with all).

async def volume_grants(self, all: bool) -> List[DriveGrant]

Parameter	Type	Default
`all`	`bool`	required

Returns Vec<DriveGrant> · Async · Raises CuaError

`Spaces.volume_request_access`#

volume_request_access: agent asks the user for more access.

async def volume_request_access(self, agent: str, prefix: str, mode: str, reason: Optional[str], in_space: Optional[str]) -> DriveAccessRequest

Parameter	Type	Default
`agent`	`String`	required
`prefix`	`String`	required
`mode`	`String`	required
`reason`	`Option<String>`	required
`in_space`	`Option<String>`	required

Returns DriveAccessRequest · Async · Raises CuaError

`Spaces.volume_requests`#

volume_requests: requests waiting for the user.

async def volume_requests(self) -> List[DriveAccessRequest]

Returns Vec<DriveAccessRequest> · Async · Raises CuaError

`Spaces.volume_approve`#

volume_approve: the request becomes a grant (with presence).

async def volume_approve(self, request_id: str, expires_in_secs: Optional[int]) -> DriveGrant

Parameter	Type	Default
`request_id`	`String`	required
`expires_in_secs`	`Option<u64>`	required

Returns DriveGrant · Async · Raises CuaError

`Spaces.volume_deny`#

volume_deny.

async def volume_deny(self, request_id: str) -> None

Parameter	Type	Default
`request_id`	`String`	required

Async · Raises CuaError

`Spaces.volume_audit`#

volume_audit: the newest events (default 50) and whether the log verified.

async def volume_audit(self, limit: Optional[int]) -> DriveAudit

Parameter	Type	Default
`limit`	`Option<u32>`	required

Returns DriveAudit · Async · Raises CuaError

Named volumes#

Methods of Spaces.

`Spaces.volumes`#

The named volumes of Cua Volume, by name, with the Spaces that mount each. Needs Cua Spaces (the Cua Volume).

async def volumes(self) -> List[NamedVolume]

Returns Vec<NamedVolume> · Async · Raises CuaError

`Spaces.create_volume`#

Creates the empty named volume name (1 to 63 of a-z, 0-9, ., _, -). Fails when it exists. Mount it with SpaceCreateOptions.volumes; read and write its files with Spaces.volume_ls and friends under volumes/<name>/.

async def create_volume(self, name: str) -> NamedVolume

Parameter	Type	Default
`name`	`String`	required

Returns NamedVolume · Async · Raises CuaError

`Spaces.delete_volume`#

Deletes the named volume name and its files (their history stays in the Cua Volume). Refused while Spaces mount it unless force. Returns how many files went.

async def delete_volume(self, name: str, force: bool = False) -> int

Parameter	Type	Default
`name`	`String`	required
`force`	`bool`	`false`

Returns u64 · Async · Raises CuaError

`VolumeMount` record#

A named volume of Cua Volume mounted in a Space: the folder volumes/<name>/ (or subpath inside it) appears at path.

Linux Spaces of every kind (containers, microVMs, VMs) bind-mount it; a macOS Space gets a symbolic link to the folder (its writes are refused when read_only, by the volume's access rules, though the link itself is not read-only). The Space sees only the volumes it mounted.

Field	Type	Default	Description
`name`	`String`		The volume's name (`Spaces.create_volume`): 1 to 63 of `a-z`, `0-9`, `.`, `_`, `-`.
`path`	`String`		Where it appears in the Space (absolute, for example `/mnt/shared`).
`read_only` / `readOnly`	`bool`	`false`	Mounted read-only: writes fail.
`subpath`	`String`	`""`	A folder inside the volume to mount instead of all of it (relative).

`NamedVolume` record#

A named volume of Cua Volume (Spaces.volumes).

Returned by Spaces.create_volume, Spaces.volumes.

Field	Type	Default	Description
`name`	`String`		The name.
`mounted_in` / `mountedIn`	`Vec<String>`		Ids of the Spaces that mount it.

`DriveView` record#

Whose view of the drive a call takes: the user (the default, the whole drive) or a persistent agent in a Space. It only ever narrows.

Field	Type	Default	Description
`as_agent` / `asAgent`	`Option<String>`	`None`	A persistent agent's name (`ada`).
`in_space` / `inSpace`	`Option<String>`	`None`	The Space id the agent is in (`local:work`).

`DriveListing` record#

A folder's listing.

Returned by Spaces.volume_ls.

Field	Type	Description
`path`	`String`
`principal`	`String`	`user` or `agent:<name>`.
`entries`	`Vec<DriveEntry>`

`DriveEntry` record#

One row of a drive listing.

Field	Type	Description
`path`	`String`	Key (folders end in `/`).
`name`	`String`
`folder`	`bool`
`size`	`u64`
`modified_ms` / `modifiedMs`	`u64`
`etag`	`String`
`mode`	`String`	`r` or `rw`: what this view may do there.
`sync`	`Option<DriveFileSync>`	A file's sync state, when it has something to say (uploading, conflicted, or last written by another device).

`DriveFile` record#

A file's content and version.

Returned by Spaces.volume_read.

Field	Type	Description
`path`	`String`
`size`	`u64`
`etag`	`String`
`version`	`String`
`modified_ms` / `modifiedMs`	`u64`
`content`	`Vec<u8>`
`sync`	`Option<DriveFileSync>`	Its sync state, while the drive's services run.

`DriveObject` record#

A written version.

Returned by Spaces.volume_restore, Spaces.volume_write.

Field	Type	Default	Description
`key`	`String`
`size`	`u64`
`etag`	`String`
`version`	`String`
`modified_ms` / `modifiedMs`	`u64`

`DriveVersion` record#

One version in a file's history.

Returned by Spaces.volume_history.

Field	Type	Default	Description
`version`	`String`
`size`	`u64`
`modified_ms` / `modifiedMs`	`u64`
`deleted`	`bool`
`latest`	`bool`

`DriveGrant` record#

A widening of an agent's or a Space's access.

Returned by Spaces.volume_approve, Spaces.volume_grant, Spaces.volume_grants, Spaces.volume_revoke.

Field	Type	Description
`id`	`String`
`principal`	`String`
`prefix`	`String`
`mode`	`String`	`r` or `rw`.
`created_ms` / `createdMs`	`u64`
`expires_ms` / `expiresMs`	`Option<u64>`
`revoked`	`bool`
`note`	`String`

`DriveAccessRequest` record#

An agent's request for more access, waiting for the user.

Returned by Spaces.volume_request_access, Spaces.volume_requests.

Field	Type	Default	Description
`id`	`String`
`principal`	`String`
`prefix`	`String`
`mode`	`String`
`reason`	`String`
`created_ms` / `createdMs`	`u64`

`DriveAudit` record#

The newest audit events and whether the hash chain verified.

Returned by Spaces.volume_audit.

Field	Type	Default	Description
`events`	`Vec<DriveAuditEvent>`
`verified`	`bool`
`error`	`Option<String>`

`DriveAuditEvent` record#

One audit event.

Field	Type	Default	Description
`seq`	`u64`
`ts_ms` / `tsMs`	`u64`
`principal`	`String`
`action`	`String`
`path`	`String`
`detail`	`String`

`DriveFileSync` record#

One file's sync state.

Field	Type	Description
`state`	`String`	`synced`, `pending_upload` (not yet in storage: other devices do not see it), `conflict` (a write lost to a later one, kept at `conflict_path`) or `conflict_copy` (the kept copy of a losing write).
`written_by` / `writtenBy`	`Option<String>`	The device that last wrote it, when another one did.
`conflict_path` / `conflictPath`	`Option<String>`

Cua Volume storage and sync#

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.

Storage, the volume, sync and the cache#

Methods of Spaces.

`Spaces.volume_storage`#

volume_storage: where the drive keeps its bytes.

async def volume_storage(self) -> DriveStorage

Returns DriveStorage · Async · Raises CuaError

`Spaces.volume_storage_set`#

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

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

Parameter	Type	Default
`update`	`DriveStorageUpdate`	required

Returns DriveStorageCheck · Async · Raises CuaError

`Spaces.volume_mount_status`#

volume_mount_status: whether the drive is mounted as a volume.

async def volume_mount_status(self) -> DriveMountStatus

Returns DriveMountStatus · Async · Raises CuaError

`Spaces.volume_mount`#

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

async def volume_mount(self) -> DriveMountStatus

Returns DriveMountStatus · Async · Raises CuaError

`Spaces.volume_unmount`#

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

async def volume_unmount(self) -> DriveMountStatus

Returns DriveMountStatus · Async · Raises CuaError

`Spaces.volume_sync_status`#

volume_sync_status: devices, pending uploads and conflicts.

async def volume_sync_status(self) -> DriveSyncStatus

Returns DriveSyncStatus · Async · Raises CuaError

`Spaces.volume_sync_events`#

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

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

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

Returns DriveSyncEvents · Async · Raises CuaError

`Spaces.volume_sync_resolve`#

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

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

Parameter	Type	Default
`path`	`String`	required

Async · Raises CuaError

`Spaces.volume_cache_stats`#

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

async def volume_cache_stats(self) -> DriveCacheStats

Returns DriveCacheStats · Async · Raises CuaError

`Spaces.volume_cache_set`#

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

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

Parameter	Type	Default
`capacity_bytes`	`u64`	required

Returns DriveCacheStats · Async · Raises CuaError

`Spaces.volume_cache_clear`#

volume_cache_clear: drops every cached block.

async def volume_cache_clear(self) -> DriveCacheStats

Returns DriveCacheStats · Async · Raises CuaError

`DriveStorage` record#

Where the drive keeps its bytes (Settings > Storage).

Returned by Spaces.volume_storage.

Field	Type	Description
`backend`	`String`	`fs` or `s3`.
`fs_path` / `fsPath`	`String`	Where the `fs` backend keeps bytes.
`s3`	`Option<DriveS3Settings>`
`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	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	Description
`backend`	`String`	`fs` or `s3` (`cloud` is refused).
`s3`	`Option<DriveS3Settings>`
`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.

Field	Type	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, Spaces.volume_mount_status, Spaces.volume_unmount.

Field	Type	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.

Field	Type	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>`
`devices`	`Vec<DriveDevice>`
`last_error` / `lastError`	`Option<String>`
`pending`	`Vec<DrivePendingUpload>`	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>`	The block cache in front of a bucket.
`volumes`	`Vec<DriveSpaceVolume>`	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	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.

Field	Type	Default	Description
`events`	`Vec<DriveSyncEvent>`
`next_seq` / `nextSeq`	`u64`

`DriveSyncEvent` record#

One sync event.

Field	Type	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, Spaces.volume_cache_set, Spaces.volume_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`

Cua Volume

Drive methods#

Spaces.volume_ls#

Spaces.volume_read#

Spaces.volume_write#

Spaces.volume_delete#

Spaces.volume_history#

Spaces.volume_restore#

Spaces.volume_grant#

Spaces.volume_revoke#

Spaces.volume_grants#

Spaces.volume_request_access#

Spaces.volume_requests#

Spaces.volume_approve#

Spaces.volume_deny#

Spaces.volume_audit#

Named volumes#

Spaces.volumes#

Spaces.create_volume#

Spaces.delete_volume#

VolumeMount record#

NamedVolume record#

DriveView record#

DriveListing record#

DriveEntry record#

DriveFile record#

DriveObject record#

DriveVersion record#

DriveGrant record#

DriveAccessRequest record#

DriveAudit record#

DriveAuditEvent record#

DriveFileSync record#

Cua Volume storage and sync#

Storage, the volume, sync and the cache#

Spaces.volume_storage#

Spaces.volume_storage_set#

Spaces.volume_mount_status#

Spaces.volume_mount#

Spaces.volume_unmount#

Spaces.volume_sync_status#

Spaces.volume_sync_events#

Spaces.volume_sync_resolve#

Spaces.volume_cache_stats#

Spaces.volume_cache_set#

Spaces.volume_cache_clear#

DriveStorage record#

DriveS3Settings record#

DriveStorageUpdate record#

DriveStorageCheck record#

DriveMountStatus record#

DriveSyncStatus record#

DrivePendingUpload record#

DriveSpaceVolume record#

DriveConflict record#

DriveDevice record#

DriveSyncEvents record#

DriveSyncEvent record#

DriveCacheStats record#

`Spaces.volume_ls`#

`Spaces.volume_read`#

`Spaces.volume_write`#

`Spaces.volume_delete`#

`Spaces.volume_history`#

`Spaces.volume_restore`#

`Spaces.volume_grant`#

`Spaces.volume_revoke`#

`Spaces.volume_grants`#

`Spaces.volume_request_access`#

`Spaces.volume_requests`#

`Spaces.volume_approve`#

`Spaces.volume_deny`#

`Spaces.volume_audit`#

`Spaces.volumes`#

`Spaces.create_volume`#

`Spaces.delete_volume`#

`VolumeMount` record#

`NamedVolume` record#

`DriveView` record#

`DriveListing` record#

`DriveEntry` record#

`DriveFile` record#

`DriveObject` record#

`DriveVersion` record#

`DriveGrant` record#

`DriveAccessRequest` record#

`DriveAudit` record#

`DriveAuditEvent` record#

`DriveFileSync` record#

`Spaces.volume_storage`#

`Spaces.volume_storage_set`#

`Spaces.volume_mount_status`#

`Spaces.volume_mount`#

`Spaces.volume_unmount`#

`Spaces.volume_sync_status`#

`Spaces.volume_sync_events`#

`Spaces.volume_sync_resolve`#

`Spaces.volume_cache_stats`#

`Spaces.volume_cache_set`#

`Spaces.volume_cache_clear`#

`DriveStorage` record#

`DriveS3Settings` record#

`DriveStorageUpdate` record#

`DriveStorageCheck` record#

`DriveMountStatus` record#

`DriveSyncStatus` record#

`DrivePendingUpload` record#

`DriveSpaceVolume` record#

`DriveConflict` record#

`DriveDevice` record#

`DriveSyncEvents` record#

`DriveSyncEvent` record#

`DriveCacheStats` record#