Volumes

Volumes are directories of files uploaded independently of your project code. The manifest links them to project versions, and the daemon mounts them inside the container when a job runs.

Uploading a volume

cycle volume upload ./data

Linking volumes to a project

Add volume names to the volumes field in .cycleswap/manifest.toml:

[main]
name = "my-experiment"
volumes = ["training-data", "validation-data"]

The volumes are linked when you run cycle project upload. Editing the manifest and uploading again creates a new version with the updated volume list.

Accessing volumes inside the container

Each volume is mounted read-only at /volumes/<name> inside the container. For the example above:

/volumes/training-data/   # contents of the training-data volume
/volumes/validation-data/ # contents of the validation-data volume

Reference these paths directly from your code:

import os

data_dir = "/volumes/training-data"
files = os.listdir(data_dir)

Volumes are read-only. Write output to /artifacts instead (see Job Outputs).

Built-in volumes

Some volumes are provided by the platform itself (model weights, datasets, etc.). These show up in the Built-in tab on the Volumes page and are available to every organization without uploading anything.

To reference a built-in volume in your manifest, prefix the name with builtin/:

[main]
name = "my-experiment"
volumes = ["my-data", "builtin/stable-diffusion-v1-5"]

my-data is an org volume you uploaded and mounts at /volumes/my-data. builtin/stable-diffusion-v1-5 is a platform-provided volume and mounts at /volumes/builtin/stable-diffusion-v1-5. The mount path matches the manifest name.

Built-in volumes are mounted under /volumes/builtin/, not directly under /volumes/. They cannot be deleted or modified by users. The builtin/ prefix is reserved; you cannot create an org volume whose name contains /.

Listing volumes

List every volume in your organization with its size and owner:

cycle volume ls

You can also browse volumes on the Volumes page in the web UI, which shows each volume's size, file count, format, and owner.

Browsing volume contents

On the Volumes page, click Browse next to any volume to explore its file tree in the browser.

Downloading a volume locally

cycle volume download <name>

By default the files land in a local volumes directory. Pass --download-dir <path> to choose a different destination:

cycle volume download training-data --download-dir ./local-data

Deleting a volume

On the Volumes page, click the delete icon next to any volume you own. Admins and owners can delete any volume in the organization.