How to Create a Named Volume in Apple Container

Apple Container creates named volumes through the container volume create command, which validates the name against a regex, generates an EXT4 image, and persists metadata via the VolumesService actor.

The apple/container repository provides a dedicated CLI sub-command for volume management that handles the entire lifecycle from creation to deletion. This guide explains the command syntax, validation rules, and underlying implementation details found in the service source code.

The container volume create Command

Apple Container exposes volume operations through the container volume create sub-command, with syntax documented in docs/command-reference.md. The CLI sends an XPC request—identified as volumeCreate in Sources/Services/ContainerAPIService/Client/XPC+.swift—to the VolumesService actor, which orchestrates directory creation, filesystem initialization, and metadata persistence.

Basic Syntax

To create a named volume with default settings:

container volume create mydata

The command accepts the volume name as the final positional argument. According to the implementation in Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift, the service validates the name using VolumeStorage.isValidVolumeName before proceeding.

Validation Rules

Volume names must match a regular expression enforced by the storage layer that permits only alphanumerics, hyphens (-), and underscores (_). If the name violates these rules, the service throws VolumeError.invalidVolumeName.

Driver Options

Customize the volume capacity and journaling behavior using the --opt flag:

1. Size: Allocate specific capacity with --opt size=<value>

   container volume create --opt size=10g mydata

2. Journaling: Configure the EXT4 journal mode and size with --opt journal=<mode>[:<size>]

   container volume create --opt journal=writeback:64m mydata

Under the Hood: VolumesService Implementation

The actual volume creation logic lives in the VolumesService actor. When the CLI invokes the command, the service executes a strict sequence of operations:

• Validation: Checks the name against the regex and verifies the volume does not already exist. If a volume with the same name exists, the service returns VolumeError.volumeAlreadyExists.
• Directory Creation: Provisions a directory under the resource root for the new volume.
• Image Generation: Builds an EXT4 filesystem image stored as volume.img.
• Metadata Persistence: Writes a JSON entity.json description via FilesystemEntityStore (Sources/ContainerPersistence/FilesystemEntityStore.swift) to record volume configuration and driver options.

Working with Named Volumes

Once created, reference the volume in container runtime operations and maintenance commands.

Mounting in Containers

Attach the named volume to a container filesystem using the -v flag:

container run -v mydata:/var/lib/app docker.io/python:3-alpine

This mounts the volume at /var/lib/app inside the container.

Inspect and List

View detailed metadata including size, labels, and mount point:

container volume inspect mydata

Enumerate all available volumes:

container volume list

Deletion

Remove a volume permanently. This operation fails if the volume is currently attached to any container:

container volume delete mydata

Summary

• Invoke container volume create <name> to provision a named volume in Apple Container.
• Names must satisfy the regex in VolumeStorage.isValidVolumeName to avoid VolumeError.invalidVolumeName.
• Customize capacity and journaling via --opt size=<value> and --opt journal=<mode>[:<size>].
• The VolumesService actor handles creation by generating an EXT4 image and persisting entity.json metadata.
• Mount volumes in containers using the -v syntax; deletion requires the volume to be unattached.

Frequently Asked Questions

What characters are allowed in Apple Container volume names?

Volume names must match the regular expression enforced by VolumeStorage.isValidVolumeName, which restricts input to alphanumerics, hyphens, and underscores. The service throws VolumeError.invalidVolumeName if validation fails.

How do I set a specific size when creating a volume?

Pass the --opt size=<value> flag to container volume create. For example, --opt size=10g allocates 10 GiB. The VolumesService parses this option during the EXT4 image creation phase in VolumesService.swift.

What happens if I try to create a volume that already exists?

The VolumesService actor checks for existing entries before creation. If the name is already in use, it returns VolumeError.volumeAlreadyExists and the CLI reports the conflict without modifying the existing data.

Where does Apple Container store volume metadata on disk?

The system persists volume descriptions in a JSON entity.json file within the volume's directory structure, handled by Sources/ContainerPersistence/FilesystemEntityStore.swift. The actual filesystem data resides in a volume.img file created under the resource root.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}