Images

Ringleader downloads the OS image a vz, lima, qemu or hcs workstation boots from once, and keeps it on this computer, so the next workstation of that image starts without a download. rl image shows those images, how much disk each takes and what uses it, and deletes the ones nothing uses.

rl image list                  # every cached image, its size, last use and what uses it
rl image delete <name>...      # delete the named images
rl image delete --unused       # delete every image nothing uses

If that is all you need, you are done. The rest of this page says where the images are kept, what each command prints, and when an image counts as in use.

Where the images are

Ringleader keeps downloaded images in one cache directory for your account, and every data directory (--home) shares it:

When the cache passes 50 GiB, Ringleader deletes the images it downloaded longest ago as it downloads new ones. rl image does not list the images wsl2 workstations are created from.

On Windows, each hcs workstation’s disk is layered on a base disk, which the Ringleader VM Service builds from a download once for each image your Windows account uses. A base disk stays after you delete the last workstation that uses it, until the service needs its room or you delete it. The hcs provider says when the service makes room. Deleting a base disk needs no administrator rights.

rl image list

List every image in the download cache and, on Windows, every base disk the Ringleader VM Service keeps for your account.

rl image list
rl image list -o json     # the same rows, to read in a script

NAME                                                 CACHE      SIZE        LAST USED   USED BY
debian-13-generic-amd64.qcow2                        download   415.2 MiB   2d          -
debian-13-generic-amd64.qcow2.435355648-1791440058   base       1.1 GiB     3h          a workstation

Each row has these columns:

-o json and -o yaml print the same rows, with the fields name, cache, bytes, lastUsed (a timestamp), usedBy (left out when nothing uses the image) and inUse (true or false).

If the Ringleader VM Service is not running, or is older than rl, the command lists the downloads, prints a warning that says what to do, and exits 0. Any other failure to list the base disks exits 1, after the downloads are listed.

rl image delete

Delete each image you name, or every image nothing uses with --unused. A name is one that rl image list prints in its NAME column.

rl image delete debian-13-generic-amd64.qcow2
rl image delete --unused

The command tries every name you give it. For each image it deletes, it prints the name and the space it freed:

debian-13-generic-amd64.qcow2: deleted, 415.2 MiB freed

For each image it does not delete, it prints the reason, such as <name>: not deleted: the image is in use by a workstation or <name>: no cached image has this name, and the command then exits 1. Giving names and --unused together, or neither, is a usage error, and the command exits 2. With --unused, if the base disks cannot be listed, the command still deletes the unused downloads, and it prints and exits as rl image list does.

An image is in use, and the command does not delete it, while any of these is true:

• Ringleader is downloading it, or a workstation is being created or started from it.
• A qemu workstation or edge VM of this data directory boots from it.
• A lima instance has not copied it into its own directory yet.
• It is a base disk, and a workstation uses it, a workstation is being created from it, or the Ringleader VM Service is still building it.

An image also counts as in use when a workstation that could use it has a record Ringleader cannot read. The USED BY column of rl image list names what uses each image.