> For the complete documentation index, see [llms.txt](https://help.fovus.co/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.fovus.co/docs/pipeline/miniwdl/miniwdl-config-reference.md). # miniWDL configuration reference Reference for miniwdl-fovus runtime attributes, cfg keys, and troubleshooting. Look up every Fovus Token accepted in `runtime{}`, every `[fovus]` cfg key, and the escape hatch for hand-written job configs. For copy-pasteable submission examples, see [Submit a pipeline (miniWDL)](/docs/pipeline/miniwdl/miniwdl-submission.md). ## runtime{} attributes Any recognized Fovus Token key in a task's `runtime{}` block is captured — the same tokens used as `process{}` attributes elsewhere on Fovus. Everything you omit falls back to the Fovus platform's default job config for the chosen `benchmarkingProfileName`, not to a value baked into the plugin. ### benchmarkingProfileName * **Type:** String * **Default:** `"Default CPU"` (falls back to the `[fovus]` cfg `benchmarkingProfileName` key) * **Description:** [Benchmarking Profile](/docs/job/job-submission/using-fovus-web/task-constraints.md) for this task. The profile must exist in your Fovus account and supplies the baseline resource constraints Fovus uses during cloud strategy optimization. Override individual `minvCpu`, `maxvCpu`, memory, GPU, or `storageGiB` fields only when this task needs stricter or looser limits than the profile provides. ### timeToCostPriorityRatio * **Type:** String * **Description:** [Time-to-cost priority ratio](/docs/job/job-submission/using-fovus-web/objective.md) for this task. Same `"T/C"` format as [job configuration file](/docs/reference/job-configuration-file.md#objective): fractions that sum to 1. `"1.0/0.0"` or `"1/0"` favors minimum runtime; `"0.0/1.0"` or `"0/1"` favors minimum cost; `"0.5/0.5"` balances both. ### imagePath * **Type:** String * **Description:** Path to a container image on Fovus Storage (for example `/fovus-storage/images/my-image.tar.gz`). Required when the image is not hosted on a public registry and is saved as a `tar` or `tar.gz` file on Fovus Storage. ### allowPreemptible * **Type:** Boolean * **Default:** `false` * **Description:** When `true`, Fovus may schedule the task on preemptible (spot) instances to reduce cost. The task may be interrupted and restarted. ### isHybridStrategyAllowed * **Type:** Boolean * **Default:** `false` * **Description:** When `true`, Fovus may automatically scale a workload across multiple HPC strategies when a single strategy cannot provide sufficient capacity. Fovus ranks eligible HPC strategies according to the user-defined time–cost priority ratio and attempts to allocate capacity in ranked order, beginning with the highest-ranked strategy. If multi-region autoscaling is enabled, it takes precedence within each strategy. Fovus first distributes the workload across available regions using the highest-ranked strategy. If those regions cannot provide sufficient capacity, Fovus proceeds to the next-ranked strategy and distributes additional workload across its available regions. This process continues down the ranked strategy list until the workload's capacity requirements are met. Throughout execution, Fovus continues searching for available capacity across all strategies already in use, prioritizing higher-ranked strategies whenever capacity becomes available. When `false`, Fovus uses only the highest-ranked HPC strategy, subject to any enabled multi-region autoscaling. ### isMultiRegionScalingAllowed * **Type:** Boolean * **Default:** `true` * **Description:** When `true`, Fovus may scale the task across multiple regions when a single region cannot meet capacity. ### isMemoryCheckpointingEnabled * **Type:** Boolean * **Default:** `false` * **Description:** When `true`, Fovus Memguard checkpoints task memory periodically and on spot interruption. Requires a valid Docker image with `glibc >= 2.28`. See [Enable Memguard for miniWDL](/docs/pipeline/miniwdl/miniwdl-submission/enable-memguard.md) for setup, and [Fovus Memguard](/docs/memguard/enable-memguard.md) for prerequisites. ### isMemoryAutoRetryEnabled * **Type:** Boolean * **Default:** `false` * **Description:** When `true`, the plugin detects exit code 137 (Linux OOM kill) and re-submits the task on the next memory tier. Fovus re-optimizes within the updated constraint. ### enableHyperthreading * **Type:** Boolean * **Default:** Determined by the benchmarking profile * **Description:** When `true`, Fovus counts each logical thread as a vCPU on supported instance types. ### isResumableWorkload * **Type:** Boolean * **Default:** `false` * **Description:** When `true`, Fovus treats the workload as resumable so a restarted pipeline can skip completed tasks. Often used with `isMemoryCheckpointingEnabled`. ### supportedCpuArchitectures * **Type:** String\[] * **Default:** Determined by the benchmarking profile * **Description:** CPU architectures the task supports. ### walltimeHours * **Type:** Int * **Default:** `6` * **Description:** Maximum wall-clock hours before the task is terminated without warning. Set above expected runtime with headroom. ### minvCpu * **Type:** Int * **Default:** Determined by the benchmarking profile * **Description:** Minimum vCPUs required for the task. ### maxvCpu * **Type:** Int * **Default:** Determined by the benchmarking profile * **Description:** Maximum vCPUs the task may use. ### minvCpuMemGiB * **Type:** Int * **Default:** Determined by the benchmarking profile * **Description:** Minimum memory per vCPU in GiB. ### minGpu / maxGpu * **Type:** Int * **Default:** Determined by the benchmarking profile * **Description:** Minimum / maximum GPUs required. Use `0` for CPU-only tasks. ### minGpuMemGiB * **Type:** Int * **Default:** Determined by the benchmarking profile * **Description:** Minimum GPU memory in GiB per GPU. ### storageGiB * **Type:** Int * **Default:** Determined by the benchmarking profile * **Description:** Local scratch storage in GiB. ### remoteInputsForAllTasks * **Type:** String\[] * **Default:** `[]` * **Description:** Fovus Storage paths copied into every task working directory at startup. For small shared files only — pre-stage large inputs under `/fovus-storage/pipelines/` instead. ### parallelismConfigFiles * **Type:** String\[] * **Default:** `[]` * **Description:** Relative paths to config files where Fovus substitutes [env tokens](/docs/job/advanced/parallelism-and-env-tokens.md) before the task starts. Supports `*` and `?` wildcards. {% hint style="warning" %} All numeric attributes are integers, including `walltimeHours` and the `*GiB` fields — the plugin rejects a non-whole value (e.g. `1.5`) even though Fovus's own schema allows fractional hours/GiB. Round up. {% endhint %} ### Example: values from inputs.json (Recommended) Wire the same attributes to workflow inputs instead of hard-coding them, then set matching keys in `inputs.json` at **both** the workflow-input level (`.`, applied to the task) and the task-scoped level (`..`, used to pre-configure benchmarking): ```wdl version 1.0 workflow smoke { input { File reads File ref String benchmarkingProfileName = "Default CPU" Boolean allowPreemptible = true Int walltimeHours = 6 Int minvCpu = 4 Int maxvCpu = 8 Int minvCpuMemGiB = 16 } call align { input: reads = reads, ref = ref, benchmarkingProfileName = benchmarkingProfileName, allowPreemptible = allowPreemptible, walltimeHours = walltimeHours, minvCpu = minvCpu, maxvCpu = maxvCpu, minvCpuMemGiB = minvCpuMemGiB, } output { File aligned = align.aligned } } task align { input { File reads File ref String benchmarkingProfileName Boolean allowPreemptible Int walltimeHours Int minvCpu Int maxvCpu Int minvCpuMemGiB } command <<< bwa mem -t $FovusNodeVcpu ~{ref} ~{reads} > aligned.sam >>> output { File aligned = "aligned.sam" } runtime { docker: "biocontainers/bwa:latest" benchmarkingProfileName: benchmarkingProfileName allowPreemptible: allowPreemptible walltimeHours: walltimeHours minvCpu: minvCpu maxvCpu: maxvCpu minvCpuMemGiB: minvCpuMemGiB } } ``` ```json { "smoke.reads": "/fovus-storage/pipelines/reads.fastq", "smoke.ref": "/fovus-storage/pipelines/GRCh38.fa", "smoke.benchmarkingProfileName": "Default CPU", "smoke.allowPreemptible": true, "smoke.walltimeHours": 6, "smoke.minvCpu": 4, "smoke.maxvCpu": 8, "smoke.minvCpuMemGiB": 16, "smoke.align.benchmarkingProfileName": "Default CPU", "smoke.align.allowPreemptible": true, "smoke.align.walltimeHours": 6, "smoke.align.minvCpu": 4, "smoke.align.maxvCpu": 8, "smoke.align.minvCpuMemGiB": 16 } ``` The two-segment `smoke.*` keys are ordinary WDL input overrides — they're what actually reaches the `align` task at runtime. The three-segment `smoke.align.*` keys are a separate signal: `miniwdl-fovus run` scans `inputs.json` for that shape before the run starts and uses matches to pre-configure benchmarking, so Fovus has already worked out the cloud strategy by the time the `align` job is submitted — no on-demand provisioning delay. Keep the two sets of values in sync. See [Pre-configuring benchmarking](/docs/pipeline/miniwdl/miniwdl-submission/local-manager.md#pre-configuring-benchmarking) for the full pattern and the naming collision to avoid. ### Example: static values ```wdl task align { input { File reads File ref } command <<< bwa mem -t $FovusNodeVcpu ~{ref} ~{reads} > aligned.sam >>> output { File aligned = "aligned.sam" } runtime { docker: "biocontainers/bwa:latest" benchmarkingProfileName: "Default CPU" allowPreemptible: true walltimeHours: 6 minvCpu: 4 maxvCpu: 8 minvCpuMemGiB: 16 } } ``` Only `docker` and the Fovus Tokens you want to override need to appear in `runtime{}` — anything omitted falls back to the `benchmarkingProfileName` profile's defaults. This works, but unlike the recommended example above, Fovus only learns the task's resource requirements when the job is actually submitted, so it configures the cloud resources on demand — a bit of provisioning latency on top of every job. ### Escape hatch: hand-write the job config Power users can bypass the attribute builder entirely: ```wdl runtime { docker: "biocontainers/custom:latest" configJson: "/fovus-storage/configs/align_job.json" } ``` The referenced file is used verbatim as the Fovus job config; only `workload.runCommand` (and `jobName`, if not already set) are injected if absent. Every other Fovus Token on the same task is ignored when `configJson` is set. *** ## \[fovus] cfg keys Settings live under `[fovus]` in a miniwdl cfg file (the bundled `miniwdl_fovus/fovus.cfg`, used automatically by `miniwdl-fovus run`). Every key can also be set by environment variable as `MINIWDL__FOVUS__` — for example, `MINIWDL__FOVUS__BENCHMARKINGPROFILENAME="Default CPU"`. | key | default | meaning | | ---------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `storage_mount_point` | `/fovus-storage` | Shared Fovus storage mount; the miniwdl run directory must live under it. | | `benchmarkingProfileName` | `Default CPU` | Fallback profile for any task that omits `benchmarkingProfileName`. | | `poll_interval_seconds` | `30` | How often the backend polls `fovus job status`. | | `auto_stop_pipeline_on_exit` | `true` | Stop the Fovus pipeline on Ctrl-C / crash so in-flight jobs don't keep consuming budget. | | `local_bookkeeping` | `true` | Write host-only bookkeeping (`inputs.json`/`outputs.json`) under `~/.cache/miniwdl-fovus/` instead of the (non-POSIX) storage mount. | | `project_name` | *(none)* | Optional Fovus project to tag created jobs/pipeline with. | A few other sections in the bundled cfg matter too: `[scheduler] task_concurrency` (Fovus provisions each task on its own instance, so this can be high — default 22), and `[file_io] copy_input_files` / `skip_output_links`, which the backend forces on regardless, since each Fovus job only binds its own task directory. *** ## Troubleshooting * `error: the fovus CLI is not installed` → `pip install fovus` * `error: not authenticated with Fovus` → `fovus auth login` * `Fovus storage is not mounted at '...'` → `fovus storage mount `, or use `miniwdl-fovus run` * Task ended `WALLTIME_REACHED`, `FAILED`, or `TERMINATED` on the Fovus side but the local `rc` file looked clean — the backend still reports failure; check the job on app.fovus.co with the logged `fovus_job_id`. * Run with `--debug` for a full log of every `fovus` CLI invocation. * A stray Ctrl-C mid-run marks the pipeline `FAILED` and (with `auto_stop_pipeline_on_exit`, the default) stops it, cancelling the in-flight job. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.fovus.co/docs/pipeline/miniwdl/miniwdl-config-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.