Configuration | NVIDIA BioNeMo NIM Documentation

This section describes how to configure the MSA Search NIM container using environment variables, GPU selection, and volume mounting.

GPU Selection

By default, Docker uses all available GPUs on the system when started with the NVIDIA Container Runtime:

docker run --runtime=nvidia ...

To expose only specific GPUs to the container, use the --gpus flag:

docker run --gpus='"device=1"' ...

The device IDs are listed in the output of nvidia-smi -L. For more information on GPU selection, refer to the NVIDIA Container Toolkit documentation.

Environment Variables

The following environment variables can be passed to the NIM using the -e flag with docker run:

ENV	Required?	Default	Notes
`NGC_API_KEY`	Yes	None	You must set this variable to the value of your personal NGC API key.
`NIM_CACHE_PATH`	No	`/opt/nim/.cache`	Location (in container) where the container caches model artifacts.
`NIM_HTTP_API_PORT`	No	`8000`	Port inside the container where the NIM service is published. When using the `-p` flag with docker run, ensure the right-hand side of the colon matches this value (for example, `-p 8000:8000`).
`NIM_DISABLE_GPU_SERVER`	No	`False`	Controls the GPU Server for MMseqs2. The GPU Server is enabled by default for optimal performance with the included ColabFold databases. GPU Server requires MMseqs2 databases indexed for GPU use (for example with `mmseqs createindex` using parameters such as `--split 1` and `--index-subset 2` as described in Indexing Databases for GPU Server). Databases downloaded from NGC are already indexed correctly. Custom or third-party databases that are CPU-only, missing GPU index files, or built with incompatible index options may not work with GPU Server—set to `True` to run MMseqs2 on CPU instead.
`NIM_GLOBAL_MAX_MSA_DEPTH`	No	`500`	Sets the maximum number of MSA sequences returned, and is reflected as both the default and the maximum allowed value for the `max_msa_sequences` API parameter. Must be set globally for all requests when GPU Server is enabled (the default in version 2.0.0 and later).
`NIM_MSA_API_MAX_DATABASES`	No	`5`	Maximum number of databases that can be specified in a single API request.
`NIM_MSA_API_MAX_ITERATIONS`	No	`6`	Maximum value for the `iterations` API parameter.
`NIM_MSA_API_MAX_CHAINS`	No	`20`	Maximum number of chains (sequences) allowed in a paired MSA search request.
`NIM_MSA_API_MAX_SEQUENCE_LENGTH`	No	`10240`	Maximum length of an input protein sequence.
`NIM_MSA_API_MAX_STRUCTURES`	No	`1000`	Maximum value for the `max_structures` API parameter in template search requests.
`NIM_MSA_API_SEQ_PATTERN`	No	`^[ARNDCQEGHILKMFPSTWYVX]+$`	Regex pattern used to validate input protein sequences. Modify to accept non-standard amino acid characters.
`NIM_MSA_API_DEFAULT_STRUCTURAL_TEMPLATE_DBS`	No	`pdb70_220313`	Comma-separated list of databases to search for structural templates by default.
`NIM_MSA_COLABFOLD_DEFAULT_PROFILE_DB`	No	`uniref30_2302`	Database used as the profile (first) database in the cascaded ColabFold search pipeline. Must be one of the available databases.
`NIM_MSA_EXPANDABLE_DBS`	No	`uniref30_2302,colabfold_envdb_202108`	Comma-separated list of databases that use the full cascaded expansion pipeline. Databases not in this list use a simpler non-expansion follow-up search.
`NIM_MSA_DB_NAME_MAPPINGS`	No	`uniref30_2302:Uniref30_2302,pdb70_220313:PDB70_220313`	Comma-separated list of `lowercase:DisplayName` mappings for database names in API responses when using `["all"]`. Used for backwards compatibility; will be removed in MSA 3.0 when all database names will resolve to lowercase.
`NIM_MSA_DB_DISPLAY_NAMES`	No	(empty)	Comma-separated list of `db_name:Display Name` overrides for human-readable database names returned by the `/biology/colabfold/msa-search/config/msa-database-configs` endpoint. Overrides the defaults in `/opt/nim/msa/config.py`. Example: `my_custom_db:My Custom Database`.
`NIM_LOG_LEVEL`	No	`INFO`	Specifies the level of logging detail. Available options: `DEBUG`, `INFO`, `WARNING`, `ERROR`.
`NIM_MODEL_NAME`	No	None	Root directory inside the container under which databases are discovered (each database in its own subdirectory). The NIM scans for index files under this path (see `NIM_MSA_DB_INDEX_PATTERN`); pointing `NIM_MODEL_NAME` at a single database folder instead of the parent root can prevent discovery. Use with volume mounts to load external or custom MMseqs2 databases. Refer to Task-Specific Profiles and Custom Databases for details.
`NIM_MODEL_PROFILE`	No	None	Select a specific database profile by ID. Profiles allow reduced storage by loading only the databases needed for a particular task. Refer to Task-Specific Profiles and Custom Databases.
`NIM_MSA_DB_INDEX_PATTERN`	No	`*/.idx`	Glob pattern for discovering sequence databases. The NIM scans for files matching this pattern under `NIM_MODEL_NAME` at startup. Database names are derived from the parent directory.
`NIM_MSA_PDB_CIFS_ZIP`	No	`*/pdb.zip`	Glob pattern for discovering the PDB mmCIF structure archive. Used for retrieving 3D structures during structural template search.
`NIM_GPUSERVER_STARTUP_TIMEOUT_S`	No	`300`	Maximum time (seconds) to wait for a GPU server to become ready at startup.
`NIM_GPUSERVER_STATUS_INTERVAL_S`	No	`3`	Interval (seconds) between GPU server health-check status reports during startup.
`NIM_TELEMETRY_MODE`	No	`0`	Controls telemetry collection. Set to `0` to disable telemetry (default), set to `1` to enable telemetry. Telemetry helps NVIDIA improve performance, compatibility, and reliability while maintaining strict privacy protections. For more information, refer to NVIDIA’s Privacy Policy and NIM Telemetry Settings.
`NIM_TELEMETRY_ENABLE_LOGGING`	No	`true`	Enables logging for telemetry operations when set to `true`. Only applicable when `NIM_TELEMETRY_MODE=1`.
`NIM_EXPERIMENTAL`	No	(not set)	(Experimental) Enables experimental features when set to `1`. Required for batch search and file output mode. Refer to Batch Search (Experimental).
`NIM_MSA_API_MAX_BATCH_SIZE`	No	`300`	(Experimental) Maximum number of sequences (or complexes) allowed in a single batch request. Only effective when `NIM_EXPERIMENTAL=1`.
`NIM_MSA_OUTPUT_DIRECTORY`	No	(not set)	(Experimental) When set, the NIM writes alignment files to this directory and returns `file://` URI references instead of inline content for batch requests only. Non-batch requests continue to return inline alignment strings. The directory is write-only from the NIM’s perspective; lifecycle management is the caller’s responsibility. Only effective when `NIM_EXPERIMENTAL=1`.

Volumes

The following container paths can be mounted to local directories for persistent storage.

Container Path	Required	Notes	Docker Argument Example
`/opt/nim/.cache` (or `NIM_CACHE_PATH` if set)	Recommended	Directory where model artifacts and databases are cached. If not mounted, the container will re-download on each startup. Ensure the local directory has read-write-execute permissions (`chmod 0777`). Example: `mkdir -p ~/.cache/nim && chmod 0777 ~/.cache/nim`	`-v ~/.cache/nim:/opt/nim/.cache`
Custom path (set using `NIM_MODEL_NAME` env variable)	Optional	Mount custom databases by setting `NIM_MODEL_NAME` to the root directory under which each database appears as its own subdirectory inside the container, then mount host paths under that root. Do not set `NIM_MODEL_NAME` to one database folder only—use a parent path and mount each DB under it. Refer to Task-Specific Profiles and Custom Databases for detailed examples.	`-e NIM_MODEL_NAME=/databases -v /host/path/to/db:/databases/mydb:ro`

The MODEL_PATH environment variable is also supported for backward compatibility with the same behavior as NIM_MODEL_NAME.

MMseqs2 Pipeline Tuning Environment Variables

The MSA Search NIM exposes several environment variables that control internal MMseqs2 pipeline parameters. These are set at container startup and apply globally to all requests. The cascaded search pipeline (used by both colabfold and template search) follows these steps per database:

Search — Iterative profile search to find initial hits
Expand — Recover remote homologs similar to initial hits
Align — Sensitive realignment of expanded candidates
Filter — Quality filtering (for example, query coverage, and sequence identity)
result2msa — Convert filtered results to A3M alignment

The variables below tune the align and filter steps, which directly affect per-database output depth and, consequently, the size of the merged colabfold alignment.

Align-Step Parameters

These control how many targets and alternative alignments are kept during the post-expansion realignment. Together, max_accept and alt_ali determine the upper bound U on the untrimmed per-database sequence count: U ≤ max_accept × (1 + alt_ali).

Variable	Default	Description
`NIM_MMSEQS_PROFILE_ALIGN_MAX_ACCEPT`	`100`	Maximum number of accepted targets per query in the profile (first-database) align step. Corresponds to `mmseqs align --max-accept`.
`NIM_MMSEQS_FOLLOWUP_ALIGN_MAX_ACCEPT`	`100`	Same as above, but for follow-up (subsequent database) align steps.
`NIM_MMSEQS_PROFILE_ALIGN_ALT_ALI`	`10`	Maximum number of alternative non-overlapping alignments per accepted target in the profile align step. Corresponds to `mmseqs align --alt-ali`. Each accepted target can produce up to 1 + `alt_ali` alignment rows.
`NIM_MMSEQS_FOLLOWUP_ALIGN_ALT_ALI`	`10`	Same as above, but for follow-up align steps.
`NIM_MMSEQS_PROFILE_ALIGN_EVALUE`	`1e-5`	E-value threshold for the profile align step. Alignments above this e-value are discarded.
`NIM_MMSEQS_FOLLOWUP_SEARCH_EVALUE`	`1e-5`	E-value threshold for the follow-up search step.
`NIM_MMSEQS_FOLLOWUP_ALIGN_EVALUE`	`1e-5`	E-value threshold for the follow-up align step.

With defaults, each database can produce up to 100 × (1 + 10) = 1,100 sequences before trimming. Per-database API results are trimmed to max_msa_sequences (N, default 500), but the merged colabfold entry concatenates untrimmed results from all D databases, yielding up to D × 1,100 sequences.

Filter-Step Parameters

These control quality filtering applied after the align step. Separate variables are provided for the profile (first-database) and follow-up (subsequent database) filter steps.

Variable	Default	Description
`NIM_MMSEQS_PROFILE_FILTER_QID`	`0`	Minimum sequence identity with query (0–1) in the profile filter step. Set to 0 to disable.
`NIM_MMSEQS_PROFILE_FILTER_QSC`	`0.0`	Minimum score per aligned residue with query sequence (`mmseqs filterresult --qsc`, range −50 to 100) in the profile filter step.
`NIM_MMSEQS_PROFILE_FILTER_DIFF`	`0`	Diversity filter: keep at least this many sequences in each MSA block of length 50 (`--diff`) in the profile filter step. Set to 0 to disable diversity filtering.
`NIM_MMSEQS_PROFILE_FILTER_MAX_SEQ_ID`	`1.0`	Maximum pairwise sequence identity (0–1) for redundancy reduction in the profile filter step. Set to 1.0 to disable.
`NIM_MMSEQS_PROFILE_FILTER_MIN_ENABLE`	`100`	Only apply filtering when the MSA has more than this many sequences in the profile filter step. Set to 0 to always filter.
`NIM_MMSEQS_FOLLOWUP_FILTER_QID`	`0`	Minimum sequence identity with query (0–1) in the follow-up filter step. Set to 0 to disable.
`NIM_MMSEQS_FOLLOWUP_FILTER_QSC`	`0.0`	Minimum score per aligned residue with query sequence (range −50 to 100) in the follow-up filter step.
`NIM_MMSEQS_FOLLOWUP_FILTER_DIFF`	`0`	Diversity filter: keep at least this many sequences in each MSA block of length 50 in the follow-up filter step. Set to 0 to disable diversity filtering.
`NIM_MMSEQS_FOLLOWUP_FILTER_MAX_SEQ_ID`	`1.0`	Maximum pairwise sequence identity (0–1) for redundancy reduction in the follow-up filter step. Set to 1.0 to disable.
`NIM_MMSEQS_FOLLOWUP_FILTER_MIN_ENABLE`	`100`	Only apply filtering when the MSA has more than this many sequences in the follow-up filter step. Set to 0 to always filter.

Expand-Step Parameters

Variable	Default	Description
`NIM_MMSEQS_FOLLOWUP_EXPAND_EVALUE`	`inf`	E-value threshold for the follow-up expansion step. `inf` means all expanded hits are kept.

Search Iteration Parameters

Variable	Default	Description
`NIM_MMSEQS_PROFILE_SEARCH_ITERATIONS`	`3`	Number of profile-search iterations in the profile (first-database) search.
`NIM_MMSEQS_FOLLOWUP_SEARCH_ITERATIONS`	`3`	Number of profile-search iterations in follow-up searches.
`NIM_MMSEQS_PAIRED_SEARCH_ITERATIONS`	`3`	Number of profile-search iterations in paired (multimer) search.
`NIM_MMSEQS_FOLLOWUP_NONEXP_SEARCH_ITERATIONS`	`3`	Number of profile-search iterations for follow-up databases that are not in `NIM_MSA_EXPANDABLE_DBS` (for example, non-expandable databases).

Other Pipeline Parameters

Variable	Default	Description
`NIM_MMSEQS_NUM_THREADS`	`12`	Default number of threads for MMseqs2 commands.
`NIM_MMSEQS_TEMPLATE_SENSITIVITY`	`7.5`	Sensitivity parameter for template search. Higher values are more sensitive but slower.
`NIM_MMSEQS_TEMPLATE_EVALUE`	`0.1`	E-value threshold for template search hits.
`NIM_MMSEQS_TEMPLATE_CONVERTALIS_FORMAT`	`query,target,fident,...`	Output format for `convertalis` (template search hits). Refer to the MMseqs2 documentation for column options.
`NIM_MMSEQS_PAIRED_ALIGN_MAX_ACCEPT`	`1000000`	Maximum accepted targets in paired search alignment. Set very high by default to maximize pairing candidates.
`NIM_MMSEQS_PAIRED_ALIGN_EVALUE`	`0.001`	E-value threshold for paired search alignment.
`NIM_MMSEQS_PAIRED_EXPAND_MAX_SEQ_ID`	`0.95`	Maximum sequence identity threshold during paired search expansion.

These environment variables are global: they apply to all requests served by the NIM instance. To change them, restart the container with the desired values. A future release may expose some of these as per-request API parameters.