volume

The volume domain has 13 actions. On the meta surface they are all reached through arcane_volume; on the individual surface each one is its own tool; on the dynamic surface run them with arcane_execute_action and the canonical ID.

Summary

Action	Title	Kind
volume.counts	Get volume usage counts	read
volume.create	Create a volume	write
volume.delete	Remove a volume	destructive
volume.get	Get volume by name	read
volume.list	List volumes	read
volume.prune	Prune unused volumes	destructive
volume.rename	Rename a volume	write
volume.sizes	Get volume sizes	read
volume.usage	Get volume usage	read
volume.workspace_file_download	Download volume workspace file	read
volume.workspace_file_get	Get volume workspace file	read
volume.workspace_get	Get volume workspace	read
volume.workspace_update	Update volume workspace	destructive

Actions

volume.counts

Get volume usage counts

Get counts of volumes in use, unused, and total

• Kind: read
• Required parameters: none
• Meta tool: arcane_volume with "action": "counts"
• Individual tool: arcane_volume_counts
• Arcane route: GET /api/environments/{id}/volumes/counts
• Operation ID: get-volume-usage-counts
• Usage: Returns only the inuse, unused and total volume counts (Arcane’s internal volumes excluded unless includeInternal is true). volume.list returns the same counts with the items.
• Related actions: volume.list, volume.prune

volume.create

Create a volume

Create a new Docker volume

• Kind: write
• Required parameters: name
• Meta tool: arcane_volume with "action": "create"
• Individual tool: arcane_volume_create
• Arcane route: POST /api/environments/{id}/volumes
• Operation ID: create-volume
• Usage: Creates a named Docker volume. Only name is required, driver defaults to Docker’s local driver, driverOpts are passed to the driver (e.g. NFS options) and labels are attached. Returns the created volume. Mount it with container.create or a Compose project, or fill it with volume.workspace_update.
• Related actions: volume.get, volume.workspace_update, container.create

volume.delete

Remove a volume

Remove a Docker volume by name

• Kind: destructive — requires confirm: true
• Required parameters: volumeName
• Meta tool: arcane_volume with "action": "delete"
• Individual tool: arcane_volume_delete
• Arcane route: DELETE /api/environments/{id}/volumes/{volumeName}
• Operation ID: remove-volume
• Usage: Deletes one volume by volumeName (from volume.list) with all its data, and removes its backup policies. Irreversible, so consider volume_backup.create first. Docker refuses while any container, even a stopped one, still uses it: check volume.usage and remove those containers first. force is passed to Docker’s volume remove (like docker volume rm -f). Arcane’s own backup volume cannot be deleted.
• Related actions: volume.usage, volume_backup.create, container.delete, volume.prune

volume.get

Get volume by name

Get a Docker volume by its name

• Kind: read
• Required parameters: volumeName
• Meta tool: arcane_volume with "action": "get"
• Individual tool: arcane_volume_get
• Arcane route: GET /api/environments/{id}/volumes/{volumeName}
• Operation ID: get-volume
• Usage: Inspect data of one volume by volumeName (from volume.list): driver, options, labels, mountpoint, scope, createdAt, inUse and the IDs of the containers that mount it. usageData (size, refCount) is filled only when Docker’s disk-usage data is cached. Fails when the volume does not exist.
• Related actions: volume.list, volume.usage, volume.workspace_get, volume_backup.list

volume.list

List volumes

Get a paginated list of Docker volumes

• Kind: read
• Required parameters: none
• Meta tool: arcane_volume with "action": "list"
• Individual tool: arcane_volume_list
• Arcane route: GET /api/environments/{id}/volumes
• Operation ID: list-volumes
• Usage: Lists Docker volumes with driver, mountpoint, labels, inUse and the IDs of the containers that mount them, plus inuse/unused/total counts. The name of each item is the volumeName other volume actions take. search matches name, driver, mountpoint and scope. inUse=“true”/“false” filters. sort accepts name, driver, mountpoint, scope, created, inUse or size. includeInternal adds Arcane’s own volumes (such as its backup volume). Paginated with start and limit (default 20).
• Related actions: volume.get, volume.counts, volume.sizes, volume.usage

volume.prune

Prune unused volumes

Remove all unused Docker volumes

• Kind: destructive — requires confirm: true
• Required parameters: none
• Meta tool: arcane_volume with "action": "prune"
• Individual tool: arcane_volume_prune
• Arcane route: POST /api/environments/{id}/volumes/prune
• Operation ID: prune-volumes
• Usage: Deletes the unused anonymous volumes of the environment with all their data. Named volumes and Arcane’s internal volumes are kept, and any volume a container (running or stopped) references counts as used. The result lists volumesDeleted and spaceReclaimed in bytes. Backup policies of the deleted volumes are removed too. To also remove unused named volumes use system.prune_all with volumes mode “all”, or volume.delete one by one.
• Related actions: volume.counts, volume.delete, system.prune_all

volume.rename

Rename a volume

Copy an unused Docker volume to a new name and remove the source

• Kind: write
• Required parameters: volumeName, name
• Meta tool: arcane_volume with "action": "rename"
• Individual tool: arcane_volume_rename
• Arcane route: POST /api/environments/{id}/volumes/{volumeName}/rename
• Operation ID: rename-volume
• Usage: Renames volumeName (from volume.list) to name: Arcane creates a new volume with the same driver, options and labels, copies the data with a helper container and then removes the source, moving its backup history and policies to the new name. The volume must be unused (volume.usage lists no containers, remove them with container.delete) and name must not exist yet. It fails with 409 otherwise, with 507 when the disk lacks space for the copy, and with 400 for Arcane’s internal volumes. Compose files that reference the old name are not updated.
• Related actions: volume.usage, container.delete, volume.get

volume.sizes

Get volume sizes

Get disk usage sizes for all volumes (slow operation)

• Kind: read
• Required parameters: none
• Meta tool: arcane_volume with "action": "sizes"
• Individual tool: arcane_volume_sizes
• Arcane route: GET /api/environments/{id}/volumes/sizes
• Operation ID: get-volume-sizes
• Usage: Returns name, size in bytes and refCount for every volume from Docker’s disk-usage API. It is slow on hosts with many or large volumes, so prefer volume.get for one volume. A volume just created or written may appear only after Docker refreshes its disk-usage data.
• Related actions: volume.list, volume.prune

volume.usage

Get volume usage

Get containers using a specific volume

• Kind: read
• Required parameters: volumeName
• Meta tool: arcane_volume with "action": "usage"
• Individual tool: arcane_volume_usage
• Arcane route: GET /api/environments/{id}/volumes/{volumeName}/usage
• Operation ID: get-volume-usage
• Usage: Tells whether volumeName (from volume.list) is in use and returns the IDs of the containers that mount it. Pass them to container.get. Check it before volume.delete or volume.rename, which need the volume unused.
• Related actions: container.get, volume.delete, volume.rename

volume.workspace_file_download

Download volume workspace file

• Kind: read
• Required parameters: volumeName
• Meta tool: arcane_volume with "action": "workspace_file_download"
• Individual tool: arcane_volume_workspace_file_download
• Arcane route: GET /api/environments/{id}/volumes/{volumeName}/workspace/file/download
• Operation ID: download-volume-workspace-file
• Usage: Downloads the raw bytes of one regular file of a volume, including binary files and files too large for volume.workspace_file_get. relativePath comes from volume.workspace_get. Text arrives in content, binary data as an embedded base64 resource. The result is capped at ARCANE_MCP_MAX_DOWNLOAD_BYTES, 4 MiB by default (truncated is true for text over it, and a larger binary file is not returned). Prefer volume.workspace_file_get to read a small text file.
• Related actions: volume.workspace_get, volume.workspace_file_get

volume.workspace_file_get

Get volume workspace file

• Kind: read
• Required parameters: volumeName
• Meta tool: arcane_volume with "action": "workspace_file_get"
• Individual tool: arcane_volume_workspace_file_get
• Arcane route: GET /api/environments/{id}/volumes/{volumeName}/workspace/file
• Operation ID: get-volume-workspace-file
• Usage: Reads one file of a volume. relativePath comes from volume.workspace_get (e.g. “conf/app.ini”). content is returned only for editable text files. For binary, too large (over VOLUME_WORKSPACE_MAX_FILE_SIZE_MB, 10 MB by default), symlink or special files it is empty and readOnlyReason says why. Fetch binary or too large files with volume.workspace_file_download. A directory path fails.
• Related actions: volume.workspace_get, volume.workspace_file_download, volume.workspace_update

volume.workspace_get

Get volume workspace

• Kind: read
• Required parameters: volumeName
• Meta tool: arcane_volume with "action": "workspace_get"
• Individual tool: arcane_volume_workspace_get
• Arcane route: GET /api/environments/{id}/volumes/{volumeName}/workspace
• Operation ID: get-volume-workspace
• Usage: Lists the files and folders inside volumeName (from volume.list) through a helper container: each entry has relativePath, isDirectory, size, modTime, editable and readOnlyReason (too_large, symlink or special, while binary files show up as editable here and are only detected by volume.workspace_file_get). Returns fileTreeRevision, required by volume.workspace_update, and fileTreeTruncated when the tree exceeded the entry limit. Fails for volumes backed by a bind mount (type none or o=bind).
• Related actions: volume.workspace_file_get, volume.workspace_file_download, volume.workspace_update

volume.workspace_update

Update volume workspace

• Kind: destructive — requires confirm: true
• Required parameters: volumeName, manifest
• Meta tool: arcane_volume with "action": "workspace_update"
• Individual tool: arcane_volume_workspace_update
• Arcane route: PUT /api/environments/{id}/volumes/{volumeName}/workspace
• Operation ID: update-volume-workspace
• Usage: Applies up to 500 file changes inside a volume. manifest is a JSON string {“fileTreeRevision”: <from volume.workspace_get>, “fileChanges”: [{“operation”: “create_file”|“update_file”, “relativePath”: “dir/a.txt”, “uploadIndex”: 0} | {“operation”: “create_folder”|“delete”, “relativePath”, “recursive”?} | {“operation”: “rename”, “relativePath”, “newName”} | {“operation”: “move”, “relativePath”, “newParentPath”} | {“operation”: “restore_file”, “relativePath”, “backupId”: <from volume_backup.list>}]}. uploadIndex points into files (objects with filename and content or contentBase64, each file at most VOLUME_WORKSPACE_MAX_FILE_SIZE_MB, 10 MB by default, else 413), and deleting a non-empty folder needs recursive true. A stale revision fails with 409 (re-read volume.workspace_get), a failed change rolls the batch back, and the result is the new tree with its new fileTreeRevision. create_file/create_folder/update_file need the volumes upload permission, delete the volumes delete permission, rename/move both upload and delete, restore_file the volumes backup permission.
• Related actions: volume.workspace_get, volume.workspace_file_get, volume_backup.list, volume_backup.restore_files