One versioned volume per user. Every write is a new version; deletes keep history. The same files appear on the user's Mac (Finder) and in every Space, within seconds.
Where it is
| Where you run | Path |
|---|---|
| A Linux Space | /volume (or ~/Cua Volume when /volume is absent) |
| A macOS Space | ~/Cua Volume |
| No mount (Windows for now, or the Space has none) | use the volume_* tools below |
Check that it is mounted, not just present: mountpoint -q /volume on Linux,
ls ~/"Cua Volume" on macOS. A /volume holding only
CUA-VOLUME-UNAVAILABLE.txt (read-only) is not the volume: the file says
why (for example, a container without /dev/fuse). If it is not mounted, use
the tools; nothing written to an unmounted folder is saved.
Layout and what you may do
| Folder | You (an agent in a Space) |
|---|---|
public/ |
read only: shared reference from the user |
agents/<you>/ |
read and write: your home (memory, outputs/, inbox/) |
spaces/<this space>/ |
read and write: this Space's scratch and outputs |
| another agent's home, another Space | not visible; ask with volume_request_access |
Put results the user should see in agents/<you>/outputs/ (or this Space's
folder) and tell them the path. A refused write means the folder is not
yours: do not retry elsewhere to get around it, ask.
Tools (the cua MCP server)
| Tool | Use |
|---|---|
volume_ls, volume_read, volume_write |
The same files without the mount; each file's sync state |
volume_delete, volume_history, volume_restore |
Where offered: delete, old versions, restore one |
volume_request_access |
Ask the user for more (a folder, r or rw, and why); they approve in Cua |
volume_sync_status |
Sync health, each device's last sync, your files still uploading, conflicts |
Inside a Space these tools answer from the user's machine, so they show its view of sync, not only this Space's.
Sync and conflicts
- A file another device just wrote can take a few seconds to arrive. Before
relying on one, check
volume_sync_status:feedislive(syncing),off(storage on this machine only: nothing to wait for) oroffline(the bucket is unreachable, seelast_error: say so rather than trust a stale file).devicesshows when each device last synced. volume_lsandvolume_readmark a file withsyncwhen it matters:pending_upload(not yet stored, other devices cannot see it yet),conflict(a write lost to a later one; kept atconflict_path),conflict_copy, andwritten_bywhen another device wrote it last.- Your own writes through the mount upload when you close the file (or after a moment without writes). Close files before telling the user they are ready.
- When two devices change the same file, the later write wins and the other
is kept next to it as
name (conflict from <device> <date>).ext. Nothing is lost. Do not delete a conflict copy yourself: tell the user, or merge the two into the current file if the task asks for it.
Never put secrets in the volume
API keys, tokens, passwords and private keys belong in the user's Keyvault.
Writes to agent homes are scanned; a write with a secret is refused
(secret_detected) and logged. Do not work around the refusal: remove the
secret.