Volumes

Volumes provide persistent storage for containers. MacTain volume commands cover creating, listing, inspecting, removing, pruning, browsing files, backing up, and restoring volumes.

Command Reference

Command	Description	Typical use
`mactain volume create <name>`	Creates a new named volume.	Prepare durable storage before attaching it to a container or Blueprint.
`mactain volume list`	Lists volumes.	See local volume inventory.
`mactain volume inspect <name>`	Shows volume metadata and references.	Confirm whether a workflow still depends on a volume.
`mactain volume remove <name>`	Removes a volume.	Delete storage you have confirmed is no longer needed.
`mactain volume prune`	Prunes unused volumes.	Clean up unused volume storage after inspection.
`mactain volume filesystem list <name> <path>`	Lists files at a volume path.	Inspect data without starting a container.
`mactain volume filesystem read <name> <path>`	Reads file content from a volume.	Check app data or metadata.
`mactain volume filesystem write <name> <path>`	Writes file content into a volume.	Repair or seed small files after checking help syntax.
`mactain volume backup <name>`	Creates a backup archive.	Protect data before risky changes.
`mactain volume restore --input <path>`	Restores a backup archive.	Recover or copy volume data.
`mactain volume docs`	Shows built-in volume examples.	Get installed-release examples from the CLI.

Defaults And Behavior

mactain volume backup <name> defaults to a dated ./<name>-YYYY-MM-DD.mactain-volume-backup.tar archive. When restoring, omit --name to use the volume name from metadata.json.

volume create, list, inspect, remove, prune, backup, restore, and filesystem commands support --json where source-backed CLI help exposes it.
Use --force only when you intentionally want to overwrite an existing backup archive or restore target.
A volume can outlive every container that has used it.
Named volumes are Engine-owned ext4 disk images attached to containers.
A named volume can be attached to at most one running container at a time.
A container definition must mount the intended volume or the app may write data into the container filesystem instead of durable storage.
Inspect before removing or pruning; volume commands are storage operations, not just container lifecycle operations.
Use bind mounts for host project files, named volumes for durable Engine-owned app data, and tmpfs mounts for temporary in-memory files.

Practical Use Cases

Use case: inspect a volume before changing it

Use this before removing, pruning, or restoring data.

mactain volume list
mactain volume inspect media-cache

Inspect first when you are not sure whether a container still depends on a volume.

Use case: attach a named volume to a container

Use this when the application writes durable state such as database files, uploads, caches, or package indexes.

mactain volume create media-cache
mactain container start \
  --name media-app \
  --image ghcr.io/acme/media:latest \
  --mount type=volume,source=media-cache,target=/var/lib/media \
  --detach

The target path must match where the application writes data. If the target is wrong, the app may write into the container filesystem instead of the named volume.

Use case: use a bind mount for project files

Use this when a local project directory should appear inside a development container.

mactain container start \
  --name dev-shell \
  --image docker.io/library/node:22 \
  --mount type=bind,source="$PWD",target=/workspace \
  --workdir /workspace \
  --detach

Bind mounts are host-path dependent. Prefer named volumes for data that should survive outside a specific checkout path.

Use case: browse files in a volume

Use this when an app is running but data appears missing or in the wrong path.

mactain volume fs list media-cache /
mactain volume fs read media-cache /metadata.json

Use volume filesystem --help for write support and exact path syntax before changing files.

Use case: write a small file into a volume

Use this for small seed files or notes after confirming the target path.

printf 'hello\n' | \
  mactain volume filesystem write media-cache /notes.txt --content-stdin
mactain volume filesystem read media-cache /notes.txt

Use containers or backup/restore workflows for larger data changes.

Use case: prune unused volumes after inspection

Use this only after reviewing volume inventory and confirming the data is no longer needed.

mactain volume list
mactain volume prune

Back up important data first. A pruned volume is storage, not just a container reference.

Use case: back up and restore persistent data

Use this before a risky change or when moving data between local workflows.

mactain volume backup media-cache --output ./media-cache-backup.tar
mactain volume restore --input ./media-cache-backup.tar --name media-cache-restored

Use --force only when you intentionally want to overwrite an existing backup archive or restore target.

Avoid Data Loss

Use volumes for data that should outlive a container.
Inspect a volume before removing it.
Back up important volume data before pruning or replacing workflows.

Troubleshooting Entry Points

Missing files: confirm the container is using the intended volume or mount.
Restore goes to an unexpected name: check whether --name was provided.
Disk usage is high: review Resource management.

Next Steps

Continue to Resource Management for cleanup and runtime storage guidance.