Cua Volume
Read and write the volume every Space and agent shares, decide who may reach what, and see where it is stored and how it syncs.
Read and write the volume every Space and agent shares, decide who may reach what, and see where it is stored and how it syncs.
| Tool | Description |
|---|---|
volume_ls | List a folder of the Cua Volume. |
volume_read | Read a file from the Cua Volume. |
volume_write | Write a file to the Cua Volume. |
volume_delete | Delete a file from the Cua Volume. |
volume_history | List a Cua Volume file's versions. |
volume_restore | Restore an old version of a Cua Volume file. |
volume_grant | Grant an agent or Space more Cua Volume access. |
volume_revoke | Revoke a Cua Volume grant. |
volume_grants | List Cua Volume grants. |
volume_request_access | Ask the user for more Cua Volume access. |
volume_requests | List Cua Volume access requests waiting for the user. |
volume_approve | Approve a Cua Volume access request. |
volume_deny | Decline a Cua Volume access request. |
volume_audit | Read the Cua Volume audit log. |
volume_storage | Show where the Cua Volume keeps its bytes. |
volume_storage_set | Test or change where the Cua Volume keeps its bytes. |
volume_mount_status | Show whether the Cua Volume is mounted as a volume. |
volume_mount | Mount the Cua Volume as a volume. |
volume_unmount | Unmount the Cua Volume volume. |
volume_sync_status | Show the Cua Volume's sync state across devices. |
volume_sync_events | Wait for Cua Volume sync events. |
volume_sync_resolve | Mark a Cua Volume sync conflict as seen. |
volume_cache_stats | Show the Cua Volume block cache. |
volume_cache_set | Set the Cua Volume block cache's size cap. |
volume_cache_clear | Clear the Cua Volume block cache. |
List a folder of the Cua Volume.
Cua Volume is one versioned drive per account, shared by every Space and agent: public/ (shared reference, read by everyone), agents/<agent>/ (a persistent agent's home: memory, outputs, inbox) and spaces/<space>/ (per-Space scratch). As the user (the default) you see everything. With as_agent (and in_space) you see exactly what that agent sees: it reads public/, writes its own home and its Space's folder, and anything wider needs a grant the user approves.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_ls, in spaces:readonly; read-only, idempotent |
| Swift SDK | spaces.volumeLs(path:asAgent:inSpace:) |
| Rust | cua_volume::Session::ls |
| Parameter | Type | Default | Description |
|---|---|---|---|
as_agent | string | none | See the drive as this persistent agent does (ada). Only narrows: the agent's defaults and grants apply. Default: the user (the whole drive). |
in_space | string | none | With as_agent: the Space id the agent is in, whose spaces/<space>/ folder it may write. |
path | string | none | Folder, for example agents/ada/ or public/. Default: the root. |
JSON: path, principal and entries (each path, name, folder, size, modified_ms, etag, mode, and sync when a file has something to say: state pending_upload, conflict (with conflict_path) or conflict_copy, and written_by when another device wrote it last).
invalid_argument, forbidden, volume_backend
Read a file from the Cua Volume.
Reads at most 8 MiB. Text comes back as utf8, anything else as base64.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_read, in spaces:readonly; read-only, idempotent |
| Swift SDK | spaces.volumeRead(path:version:asAgent:inSpace:) |
| Rust | cua_volume::Session::read |
| Parameter | Type | Default | Description |
|---|---|---|---|
as_agent | string | none | See volume_ls. |
in_space | string | none | See volume_ls. |
path | string | required | File path, for example agents/ada/memory/MEMORY.md. |
version | string | none | A version id from volume_history. Default: the current version. |
JSON: path, size, etag, version, modified_ms, encoding (utf8 or base64), content, and sync while the drive's services run (state synced, pending_upload, conflict or conflict_copy; written_by, conflict_path).
invalid_argument, forbidden, volume_backend
Write a file to the Cua Volume.
Every write is a new version (history is kept). if_etag makes it a compare-and-swap, create_only makes it create-only. Writes under agents/ are scanned for secrets and refused by kind and line; keep credentials in the Keyvault.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_write; destructive |
| Swift SDK | spaces.volumeWrite(path:content:encoding:ifEtag:createOnly:asAgent:inSpace:) |
| Rust | cua_volume::Session::write |
| Parameter | Type | Default | Description |
|---|---|---|---|
as_agent | string | none | See volume_ls. |
content | string | required | The content, as text or base64 (see encoding). At most 8 MiB. |
create_only | boolean | false | Write only if nothing is at path yet. Default false. |
encoding | string | utf8 | utf8 or base64. Default utf8. |
if_etag | string | none | Write only if the current version has this etag (from volume_read or volume_ls): a compare-and-swap. |
in_space | string | none | See volume_ls. |
path | string | required | File path. |
JSON: the new version's key, size, etag, version and modified_ms.
invalid_argument, forbidden, precondition_failed, secret_detected, volume_backend
Delete a file from the Cua Volume.
Adds a delete marker; volume_history and volume_restore still reach the old versions.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_delete; destructive |
| Swift SDK | spaces.volumeDelete(path:ifEtag:asAgent:inSpace:) |
| Rust | cua_volume::Session::delete |
| Parameter | Type | Default | Description |
|---|---|---|---|
as_agent | string | none | See volume_ls. |
if_etag | string | none | Delete only if the current version has this etag. |
in_space | string | none | See volume_ls. |
path | string | required | File path. |
JSON: {"deleted": <path>}.
invalid_argument, forbidden, precondition_failed, volume_backend
List a Cua Volume file's versions.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_history, in spaces:readonly; read-only, idempotent |
| Swift SDK | spaces.volumeHistory(path:asAgent:inSpace:) |
| Rust | cua_volume::Session::history |
| Parameter | Type | Default | Description |
|---|---|---|---|
as_agent | string | none | See volume_ls. |
in_space | string | none | See volume_ls. |
path | string | required | File path. |
JSON: path and versions (each version, size, modified_ms, deleted, latest), newest first.
invalid_argument, forbidden, volume_backend
Restore an old version of a Cua Volume file.
Writes the old version's content as a new version, so the restore itself can be undone.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_restore; destructive |
| Swift SDK | spaces.volumeRestore(path:version:asAgent:inSpace:) |
| Rust | cua_volume::Session::restore |
| Parameter | Type | Default | Description |
|---|---|---|---|
as_agent | string | none | See volume_ls. |
in_space | string | none | See volume_ls. |
path | string | required | File path. |
version | string | required | The version id to restore (from volume_history). |
JSON: the new current version's key, size, etag, version and modified_ms.
invalid_argument, forbidden, secret_detected, volume_backend
Grant an agent or Space more Cua Volume access.
Only for the user: widens an agent's or a Space's access past the defaults (an agent reads public/ and writes its own home and its Space's folder). The user confirms with presence (Touch ID, the login password or the vault passphrase) before anything widens; a grant that widens nothing is refused.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_grant; destructive |
| Swift SDK | spaces.volumeGrant(principal:prefix:mode:expiresInSecs:note:) |
| Rust | cua_volume::Drive::grant |
| Parameter | Type | Default | Description |
|---|---|---|---|
expires_in_secs | integer | none | Lifetime in seconds. Default: until revoked. At least 0. |
mode | string | required | r (read) or rw (read and write). |
note | string | none | A note shown next to the grant. |
prefix | string | required | A folder (agents/writer/outputs/) or one file. |
principal | string | required | agent:<name> or space:<id>. |
JSON: the grant (id, principal, prefix, mode, created_ms, expires_ms, revoked, note).
invalid_argument, not_confirmed, forbidden
Revoke a Cua Volume grant.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_revoke; mutating, idempotent |
| Swift SDK | spaces.volumeRevoke(grantId:) |
| Rust | cua_volume::Drive::revoke |
| Parameter | Type | Default | Description |
|---|---|---|---|
grant_id | string | required | The grant id (from volume_grants). |
JSON: the revoked grant.
List Cua Volume grants.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_grants, in spaces:readonly; read-only, idempotent |
| Swift SDK | spaces.volumeGrants(all:) |
| Rust | cua_volume::Drive::grants |
| Parameter | Type | Default | Description |
|---|---|---|---|
all | boolean | false | Include expired and revoked grants. Default false. |
JSON: {"grants": [...]}, live grants only unless all.
Ask the user for more Cua Volume access.
Files a request the user sees in Cua; it grants nothing by itself. Poll volume_ls or volume_read to see when access arrives.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_request_access; destructive |
| Swift SDK | spaces.volumeRequestAccess(prefix:mode:reason:asAgent:inSpace:) |
| Rust | cua_volume::Drive::request_access |
| Parameter | Type | Default | Description |
|---|---|---|---|
as_agent | string | none | The agent asking. |
in_space | string | none | See volume_ls. |
mode | string | required | r or rw. |
prefix | string | required | The folder or file wanted. |
reason | string | none | Why (shown to the user as the agent's words). |
JSON: the request (id, principal, prefix, mode, reason, created_ms).
List Cua Volume access requests waiting for the user.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_requests, in spaces:readonly; read-only, idempotent |
| Swift SDK | spaces.volumeRequests() |
| Rust | cua_volume::Drive::requests |
No parameters.
JSON: {"requests": [...]}.
Approve a Cua Volume access request.
Only for the user, with presence.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_approve; destructive |
| Swift SDK | spaces.volumeApprove(requestId:expiresInSecs:) |
| Rust | cua_volume::Drive::approve |
| Parameter | Type | Default | Description |
|---|---|---|---|
expires_in_secs | integer | none | Lifetime in seconds. Default: until revoked. At least 0. |
request_id | string | required | The request id (from volume_requests). |
JSON: the grant the request became.
invalid_argument, not_confirmed, forbidden
Decline a Cua Volume access request.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_deny; destructive |
| Swift SDK | spaces.volumeDeny(requestId:) |
| Rust | cua_volume::Drive::deny |
| Parameter | Type | Default | Description |
|---|---|---|---|
request_id | string | required | The request id. |
JSON: {"denied": <request id>}.
Read the Cua Volume audit log.
Every grant, revocation, request, refusal, blocked secret, sync, lease and agent access, from a hash-chained log; an edited or truncated log reports verified=false.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_audit, in spaces:readonly; read-only, idempotent |
| Swift SDK | spaces.volumeAudit(limit:) |
| Rust | cua_volume::audit::AuditLog::tail |
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 50 | How many. Default 50, at most 1000. At least 0. |
JSON: events (each seq, ts_ms, principal, action, path, detail), newest first, and verified (with error when the hash chain does not verify).
Show where the Cua Volume keeps its bytes.
Only for the user. Keys are never returned; has_keys says whether the credential store holds them.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_storage, in spaces:readonly; read-only, idempotent |
| Swift SDK | spaces.volumeStorage() |
| Rust | cua_volume::service::DriveService::storage |
No parameters.
JSON: backend (fs or s3), fs_path, s3 (endpoint, region, bucket, root, path_style), has_keys, cloud_available.
Test or change where the Cua Volume keeps its bytes.
Only for the user. Tests the storage first (bucket versioning, list, then write, read back and delete a probe object; retries path-style addressing to tell when a self-hosted store needs it); with dry_run nothing else happens. Otherwise, when the test passes, saves the setting and the keys (credential store) and switches the running drive to it without a restart. The bucket must have versioning on. cloud is refused.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_storage_set; mutating, idempotent |
| Swift SDK | spaces.volumeStorageSet(update:) |
| Rust | cua_volume::service::DriveService::set_storage |
| Parameter | Type | Default | Description |
|---|---|---|---|
access_key_id | string | none | The access key id (with the secret; both or neither). Saved in the credential store, never in a file. |
backend | string | required | fs (this machine) or s3 (an S3-compatible bucket: AWS S3, R2, MinIO). cloud is refused. |
dry_run | boolean | false | Only test the connection; change nothing. Default false. |
s3 | object | none | The bucket, for s3. |
s3.bucket | string | required | |
s3.endpoint | string | null | http://127.0.0.1:9000, https://<account>.r2.cloudflarestorage.com; absent for AWS. |
s3.path_style | boolean | null | Path-style addressing (MinIO and most self-hosted stores). |
s3.region | string | null | us-east-1; auto for R2. Default us-east-1. |
s3.root | string | null | A key prefix inside the bucket. Default none. |
secret_access_key | string | none | The secret access key. |
JSON: ok, reachable, authorized, versioning, detail (a sentence when not ok saying how to fix it), problem (unreachable, bad_keys, forbidden, bucket_missing, versioning_off, path_style_needed) and applied (saved and switched live).
Show whether the Cua Volume is mounted as a volume.
Only for the user. The drive can appear as a volume (Finder on macOS, a FUSE mount on Linux); it is off until the user turns it on with volume_mount.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_mount_status, in spaces:readonly; read-only, idempotent |
| Swift SDK | spaces.volumeMountStatus() |
| Rust | cua_volume::service::DriveService::mount_status |
No parameters.
JSON: enabled, state (off, mounting, mounted, needs_approval, unsupported, error), method (nfs, fuse, fskit, none), path, volume_name, detail, settings_url.
Mount the Cua Volume as a volume.
Only for the user. Turns the mount on (kept across restarts) and mounts. Idempotent.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_mount; mutating, idempotent |
| Swift SDK | spaces.volumeMount() |
| Rust | cua_volume::service::DriveService::mount |
No parameters.
JSON: the mount status after the attempt (see volume_mount_status).
Unmount the Cua Volume volume.
Only for the user. Turns the mount off; files still uploading land first.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_unmount; mutating, idempotent |
| Swift SDK | spaces.volumeUnmount() |
| Rust | cua_volume::service::DriveService::unmount |
No parameters.
JSON: the mount status after unmounting.
invalid_argument, forbidden, volume_backend
Show the Cua Volume's sync state across devices.
Devices sharing one bucket learn each other's changes through a change log in the bucket itself. A write that lost to a later one is never dropped: it stays in the file's history and as the visible conflict copy. A persistent agent may call it too (through its bridge): it sees the pending uploads and conflicts of files it can read and its own Space's volume. In a Space it reports this machine's view.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_sync_status, in spaces:readonly; read-only, idempotent |
| Swift SDK | spaces.volumeSyncStatus() |
| Rust | cua_volume::service::DriveService::sync_status |
No parameters.
JSON: device_id, device_name, feed (live, off for a store on this machine, offline when the bucket stops answering, with last_error), poll_interval_ms, last_poll_ms, last_remote_change_ms, pending_uploads, pending_bytes, conflicts (each path, conflict_path, winner_device, loser_device, winner_version, loser_version, ts_ms), devices (each id, name, this_device, last_seen_ms, last_change_ms, changes), last_error, pending (each path, bytes: files still uploading), backend (fs or s3), mount (this machine's mount: off, mounting, mounted, needs_approval, unsupported, error), cache (a bucket's block cache, when there is one) and volumes (the volume mounted in Spaces: each space, mount_path, backend, principal).
Wait for Cua Volume sync events.
Only for the user. A long poll: answers at once when events newer than since_seq exist, else waits up to wait_ms for one. Kinds: remote_change, remote_delete, upload_started, upload_done, upload_failed, conflict, error.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_sync_events, in spaces:readonly; read-only, idempotent |
| Swift SDK | spaces.volumeSyncEvents(sinceSeq:waitMs:) |
| Rust | cua_volume::service::DriveService::sync_events |
| Parameter | Type | Default | Description |
|---|---|---|---|
since_seq | integer | none | Return events after this seq (default 0: all kept). At least 0. |
wait_ms | integer | none | Wait up to this long for one when none is newer (default 0, at most 30000). At least 0. |
JSON: events (each seq, ts_ms, kind, path, device, size, version, detail) and next_seq.
Mark a Cua Volume sync conflict as seen.
Only for the user. Clears the conflict from the list; both files stay.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_sync_resolve; mutating, idempotent |
| Swift SDK | spaces.volumeSyncResolve(path:) |
| Rust | cua_volume::service::DriveService::sync_resolve |
| Parameter | Type | Default | Description |
|---|---|---|---|
path | string | required | The file (or its conflict copy). |
JSON: {"resolved": <path>}.
invalid_argument, forbidden, not_found
Show the Cua Volume block cache.
Only for the user. Reads of a remote store go through a local block cache; counters are since the runtime started.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_cache_stats, in spaces:readonly; read-only, idempotent |
| Swift SDK | spaces.volumeCacheStats() |
| Rust | cua_volume::service::DriveService::cache_stats |
No parameters.
JSON: dir, size_bytes, capacity_bytes, block_bytes, blocks, hits, misses, hit_rate, prefetched_bytes, evictions.
Set the Cua Volume block cache's size cap.
Only for the user. Evicts down to the new cap at once; kept across restarts.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_cache_set; mutating, idempotent |
| Swift SDK | spaces.volumeCacheSet(capacityBytes:) |
| Rust | cua_volume::service::DriveService::cache_set |
| Parameter | Type | Default | Description |
|---|---|---|---|
capacity_bytes | integer | required | Bytes (at least 268435456, 256 MiB). At least 0. |
JSON: the cache stats after the change.
Clear the Cua Volume block cache.
Only for the user. Drops every cached block; files stay in the drive.
| Providers | all (cloud, local, direct, relay) |
| Platforms | all (macos, windows, linux) |
| Metering | free |
| Approval | permission spaces:volume_cache_clear; mutating, idempotent |
| Swift SDK | spaces.volumeCacheClear() |
| Rust | cua_volume::service::DriveService::cache_clear |
No parameters.
JSON: the cache stats after clearing.