Container Images

Maelstrom clients support building job specifications based off of standard OCI container images stored on Docker Hub. This can be done with cargo-maelstrom's image directive field, or cargo-run's image field.

When an image is specified this way, the client will first download it locally into its cache directory. It will then use the internal bits of the OCI image — most importantly the file-system layers — to create the job specification for the job.

Images can be specified with tags. If no tag is provided, the latest tag is used.

For the purposes of reproducable jobs, clients will resolve and "lock" a tag, so that jobs always specify an exact image that doesn't change over time. See this section for more details.

Cached Container Images

Container images are cached on the local file system. Maelstrom uses the $XDG_CACHE_HOME/maelstrom/containers directory if XDG_CACHE_HOME is set and non-empty. Otherwise, it uses ~/.cache/maelstrom/containers. See the XDG Base Directories specification for more information.

Lock File

When a client first resolves a container registry tag, it stores the result in a local lock file. Subsequently, it will use the exact image specified in the lock file instead of resolving the tag again. This guarantees that subsequent runs use the same images as previous runs.

The local lock file is maelstrom-container-tags.lock, stored in the project directory. It is recommended that this file be committed to revision control, so that others in the project, and CI, use the same images when running tests.

To update a tag to the latest version, remove the corresponding line from the lock file and then run the client.