Runtime Configuration

By default, the CLI resolves each plugin action to a Docker image derived from the plugin name:

ghcr.io/cymis/qiime2-plugin-<plugin-name>:2026.1

A runtime config file lets you override that resolution without editing the pipeline itself.

Use a runtime config when you need to:

run a plugin from your own Docker image
pin one plugin to a different tag
run tasks in an existing conda environment
use Apptainer or Singularity on HPC
override one task in an otherwise standard pipeline

Using a config file

Pass a TOML config file with --config:

adagio run \
  --pipeline pipeline.adg \
  --cache-dir /cache \
  --config runtime.toml

Config file format

version = 1

[defaults]
platform = "linux/amd64"

[plugins]
dada2 = { image = "ghcr.io/cymis/qiime2-plugin-dada2:2026.1" }
demux = { image = "ghcr.io/cymis/qiime2-plugin-demux:2026.1" }

[tasks]
"dada2.denoise_single" = { image = "registry.internal/custom-dada2:1.0" }

Settings are resolved in this order, from highest to lowest priority:

[tasks] - overrides for a specific task
[plugins] - overrides for all tasks from a plugin
[defaults] - fallback for anything not explicitly set
built-in defaults

Choosing keys

Use:

plugin names in [plugins]
plugin.action names in [tasks]

plugin.action is usually the most stable task key for exported pipelines.

Common scenarios

Pin a plugin to a specific image version

version = 1

[plugins]
dada2 = { image = "ghcr.io/cymis/qiime2-plugin-dada2:2025.4" }

Use a user-built Docker image for a plugin that is not in the default image set

version = 1

[plugins]
my_plugin = { image = "registry.example.org/qiime2-plugin-my-plugin:dev" }

This is the main way to run a saved pipeline with a container you wrote yourself.

Important:

the pipeline file still refers to the plugin by plugin name
the runtime config tells Adagio which container to launch for that plugin
this works even if the image is not part of Adagio’s default GHCR set

If you also want to build pipelines with that plugin in the Adagio UI, you must register the plugin with Adagio through QAPI submission. See Registering and Submitting a Plugin.

Use a locally built image for one task only

version = 1

[tasks]
"dada2.denoise_single" = { image = "localhost/my-dada2-dev:latest" }

Force a specific Docker platform

Useful on Apple Silicon when the published plugin image only has a linux/amd64 manifest:

version = 1

[defaults]
kind = "docker"
platform = "linux/amd64"

Pass that file with --config when running the pipeline:

adagio run \
  --pipeline pipeline.adg \
  --cache-dir /cache \
  --config runtime.toml

You can check or pre-pull a plugin image with the same platform:

docker pull --platform linux/amd64 ghcr.io/cymis/qiime2-plugin-feature-table:2026.1

Use Apptainer instead of Docker

For HPC environments where Docker is not available, Adagio can run tasks with Apptainer or Singularity using local .sif files:

version = 1

[plugins]
dada2 = { kind = "apptainer", image = "/shared/images/qiime2-plugin-dada2.sif" }
demux = { kind = "apptainer", image = "/shared/images/qiime2-plugin-demux.sif" }

Rules:

kind can be docker or apptainer
for apptainer, image must be a local .sif path
Adagio prefers the apptainer executable and falls back to singularity

Use a conda environment

For local development or shared systems where a QIIME 2 conda environment is already installed, Adagio can run tasks with conda run.

Use environment for a named conda environment:

version = 1

[defaults]
kind = "conda"
environment = "rachis-qiime2-2026.4"

Use prefix instead when the environment should be selected by filesystem path:

version = 1

[defaults]
kind = "conda"
prefix = "/opt/conda/envs/rachis-qiime2-2026.4"

Rules:

kind can be docker, apptainer, or conda
the conda environment must already exist
the conda environment must contain QIIME 2 and the plugins required by the tasks that use it
Adagio enters the environment with conda run; it does not create or update the environment
set conda_executable when conda is not on PATH, or set ADAGIO_CONDA_EXE in the shell

For example:

version = 1

[defaults]
kind = "conda"
environment = "rachis-qiime2-2026.4"
conda_executable = "/opt/conda/bin/conda"

Mix Docker, Apptainer, and conda

version = 1

[defaults]
kind = "docker"

[plugins]
dada2 = { image = "ghcr.io/cymis/qiime2-plugin-dada2:2026.1" }
my_plugin = { kind = "apptainer", image = "/shared/images/my-plugin.sif" }

You can also mix execution environments per task. This config runs demux emp-single in Docker and dada2 denoise-single in the named conda environment:

version = 1

[tasks]
"demux.emp_single" = { kind = "docker", image = "ghcr.io/cymis/qiime2-plugin-demux:2026.4" }
"dada2.denoise_single" = { kind = "conda", environment = "rachis-qiime2-2026.4" }

Task keys use the exported plugin.action names. QIIME 2 action names that are written with hyphens in prose are usually stored with underscores in the pipeline, so emp-single becomes emp_single and denoise-single becomes denoise_single.

What runtime config does not do

Runtime config affects execution only. It does not:

add a plugin to the Adagio UI
change plugin visibility
change the saved pipeline file
publish anything to the shared catalogs

Full config reference

Key	Applies to	Values	Description
`kind`	defaults, plugins, tasks	`docker`, `apptainer`, `conda`	task runner to use
`image`	defaults, plugins, tasks	image ref or `.sif` path	container image to use for Docker or Apptainer
`platform`	defaults, plugins, tasks	e.g. `linux/amd64`	Docker platform override
`environment`	defaults, plugins, tasks	conda environment name	named conda environment to run with `conda run -n`
`prefix`	defaults, plugins, tasks	conda environment path	conda environment path to run with `conda run -p`
`conda_executable`	defaults, plugins, tasks	path to `conda`	conda executable override