> 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/nextflow/nextflow-config-reference.md).

# Nextflow configuration reference

Reference for nf-fovus Nextflow plugin parameters in nextflow\.config.

Look up every parameter for the `nf-fovus` Nextflow plugin. All configuration lives in `nextflow.config`.

For copy-pasteable examples, see [Prepare inputs and configure Nextflow](/docs/pipeline/nextflow/pipeline-submission/prepare-inputs.md). To submit after configuring, see [Run fully hosted by Fovus](/docs/pipeline/nextflow/pipeline-submission/fovus-hosted-manager.md) or [Local Nextflow manager](/docs/pipeline/nextflow/pipeline-submission/local-hosted-manager.md).

## plugins{}

Declare the nf-fovus plugin so Nextflow loads it before execution.

### id

* **Type:** String
* **Default:** —
* **Description:** Plugin identifier for nf-fovus.

```groovy
plugins {
    id 'nf-fovus'
}
```

Nextflow resolves the [latest published release](https://registry.nextflow.io/plugins/nf-fovus) on first run.

To pin a specific version, append `@` and the release number:

```groovy
plugins {
    id 'nf-fovus@1.0.12'
}
```

See [nf-fovus on the Nextflow plugin registry](https://registry.nextflow.io/plugins/nf-fovus) for all released versions.

***

## fovus{}

Account-level and pipeline-level identity for Fovus.

### pipelineName

* **Type:** String
* **Default:** —
* **Required:** Yes
* **Description:** Display name for this pipeline in the Fovus console. Must be non-empty. Omitting it throws an error and the pipeline will not start.

### cliPath

* **Type:** String
* **Default:** `'fovus'`
* **Description:** Absolute path to the Fovus CLI binary. When omitted, the plugin resolves `fovus` from your system `PATH`.

### projectName

* **Type:** String
* **Default:** —
* **Description:** Optional project name for grouping jobs and pipelines for budget tracking in Fovus.

***

## process{}

### executor

* **Type:** String
* **Default:** —
* **Required:** Yes
* **Description:** Set to `'fovus'` so Nextflow routes task submissions through the Fovus plugin. Without it, tasks run on the local machine.

```groovy
process {
    executor = 'fovus'
}
```

***

## ext.\* parameters

Each Nextflow process runs as a [Fovus Job](/docs/job/overview.md). The `ext.*` fields are **per-process job settings** — Fovus reads them when it provisions compute and selects an optimal instance for that step.

Set them in `process {}` (defaults for every process) or in `withName: 'process_name' {}` (one process only). A `withName` block overrides the outer `process {}` block for that process.

Your [Benchmarking Profile](/docs/job/job-submission/using-fovus-web/task-constraints.md) already defines default **resource constraints** (vCPU, memory, GPU, scratch storage, and related limits). Set `ext.benchmarkingProfileName` first, then add the parameters below only when you need to override profile defaults or tune behavior for a specific process.

### benchmarkingProfileName

* **Type:** String
* **Default:** `'Default CPU'`
* **Required:** Yes
* **Description:** [Benchmarking Profile](/docs/job/job-submission/using-fovus-web/task-constraints.md) for this process. 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 process 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 process. 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.

```groovy
ext.timeToCostPriorityRatio = '0.5/0.5'
```

### 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 are not hosted on a public registry and saved as `tar` or `tar.gz` files 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 Nextflow](/docs/pipeline/nextflow/pipeline-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.

### walltimeHours

* **Type:** Number
* **Default:** `6`
* **Description:** Maximum wall-clock hours before the task is terminated without warning. Any numeric value works (for example `6`, `12`, or `3.5`). Set above expected runtime with headroom.

### Resource constraints (override benchmarking profile defaults)

Use these only when a process needs limits different from its benchmarking profile. Process-scope `ext.*` values override profile defaults.

#### minvCpu

* **Type:** Integer
* **Default:** Determined by the benchmarking profile
* **Description:** Minimum vCPUs required for the task.

#### maxvCpu

* **Type:** Integer
* **Default:** Determined by the benchmarking profile
* **Description:** Maximum vCPUs the task may use.

#### minvCpuMemGiB

* **Type:** Integer
* **Default:** Determined by the benchmarking profile
* **Description:** Minimum memory per vCPU in GiB.

#### minGpu

* **Type:** Integer
* **Default:** Determined by the benchmarking profile
* **Description:** Minimum GPUs required. Use `0` for CPU-only tasks.

#### maxGpu

* **Type:** Integer
* **Default:** Determined by the benchmarking profile
* **Description:** Maximum GPUs the task may use.

#### minGpuMemGiB

* **Type:** Integer
* **Default:** Determined by the benchmarking profile
* **Description:** Minimum GPU memory in GiB per GPU.

#### storageGiB

* **Type:** Integer
* **Default:** Determined by the benchmarking profile
* **Description:** Local scratch storage in GiB. `ext.storageGiB` takes precedence over Nextflow's `disk` directive when both are set.

#### enableHyperthreading

* **Type:** Boolean
* **Default:** Determined by the benchmarking profile
* **Description:** When `true`, Fovus counts each logical thread as a vCPU on supported instance types.

#### supportedCpuArchitectures

* **Type:** List\<String>
* **Default:** Determined by the benchmarking profile
* **Description:** CPU architectures the task supports.

### Inputs and execution

#### remoteInputsForAllTasks

* **Type:** List\<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.

```groovy
process {
  ext.remoteInputsForAllTasks = ['/fovus-storage/files/shared-config.txt']
}
```

#### parallelismConfigFiles

* **Type:** List\<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.

#### outputFileList

* **Type:** List\<String>
* **Default:** Derived from the process `output:` declarations
* **Description:** Additional file patterns (relative to the task folder) to sync back from each task. The plugin already builds this list from the files the process declares as Nextflow outputs — it normalizes each pattern (`**` becomes `*`, brace alternatives are expanded), appends `*` to any pattern that does not already end in one, and adds `.command.*` and `.exitcode`. Patterns you set here are **added to** that list, not substituted for it. Use it for files the process does not declare as outputs, such as logs you still want in Fovus Storage.

```groovy
process {
  withName: 'solve' {
    ext.outputFileList = ['*.log', 'diagnostics/*']
  }
}
```

Only `include` is supported for `outputFileOption`. If you set it to anything else, the plugin logs a warning and uses `include`.

#### 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`.

#### storageConnectors

* **Type:** List\<String>
* **Default:** `[]`
* **Description:** Names of the Fovus storage connectors this process needs. A storage connector grants the job IAM access to an S3 bucket. A name may contain only letters, digits, and hyphens (`^[a-zA-Z0-9-]+$`) — a malformed name fails the run immediately. Whether a connector exists, and whether your account is entitled to it, is checked server side at submission time.

```groovy
process {
  ext.storageConnectors = ['reference-genomes']

  withName: 'publishResults' {
    ext.storageConnectors = ['reference-genomes', 'results-archive']
  }
}
```

Connectors grant IAM access only — they do not mount anything into the task working directory. Read from the bucket with the AWS CLI or an SDK inside your process script.

At the start of a run, the plugin sends each process's resource configuration to Fovus so pipeline resources — including the IAM roles these connectors require — are provisioned before the first job. A process contributes to that step only when its `ext` block also sets `benchmarkingProfileName`.

{% hint style="info" %}
Every nf-fovus process runs as a job in the same pipeline, and connectors are shared across a pipeline: a connector declared on any process is reachable from every job in that pipeline. Do not rely on `ext.storageConnectors` to isolate a bucket to a single process.
{% endhint %}

This grants processes access, not the pipeline manager itself — see [Pipeline host](/docs/storage/storage-connectors/usage/pipeline-host.md) for granting the Fovus-hosted manager its own connector access.

***

## workDir

* **Type:** String
* **Default:** —
* **Required:** Yes
* **Description:** Absolute path to the pipeline scratch directory. **Must end in `/pipelines`.** The plugin enforces this at runtime.

```groovy
workDir = '/fovus-storage/pipelines'
```

***

## Parameter precedence

When the same value is set in multiple places (highest to lowest priority):

1. Command-line arguments to `nextflow run`
2. Params file (`-params-file`)
3. `nextflow.config`
4. Defaults in the pipeline script

Within `nextflow.config`, `withName` overrides `process {}` for the named process. Process-scope `ext.*` overrides benchmarking profile defaults from your Fovus account.

***

## Docker

When processes use containers, enable Docker in Nextflow:

```groovy
docker {
  enabled = true
}
```

The nf-fovus plugin injects container run options and resource values — you do not need to set `runOptions` manually. See [Prepare inputs and configure Nextflow](/docs/pipeline/nextflow/pipeline-submission/prepare-inputs.md) and the [Nextflow Docker documentation](https://www.nextflow.io/docs/latest/docker.html).


---

# 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/nextflow/nextflow-config-reference.md?ask=<question>&goal=<endgoal>
```

`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.