> This page is for MSA Search, version 2.2.0.
> For other versions, use one of these documentation indexes:
> - 2.6.0 (Latest) (default): https://docs.nvidia.com/nim/bionemo/msa-search/2.6.0/llms.txt
> - 2.5.0: https://docs.nvidia.com/nim/bionemo/msa-search/2.5.0/llms.txt
> - 2.4.0: https://docs.nvidia.com/nim/bionemo/msa-search/2.4.0/llms.txt
> - 2.3.0: https://docs.nvidia.com/nim/bionemo/msa-search/2.3.0/llms.txt
> - 2.2.0: https://docs.nvidia.com/nim/bionemo/msa-search/2.2.0/llms.txt
> - 2.1.0: https://docs.nvidia.com/nim/bionemo/msa-search/2.1.0/llms.txt
> - 2.0.0: https://docs.nvidia.com/nim/bionemo/msa-search/2.0.0/llms.txt
> - 1.0.0: https://docs.nvidia.com/nim/bionemo/msa-search/1.0.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nim/bionemo/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nim/bionemo/_mcp/server.

# Configuration

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:

```bash
docker run --runtime=nvidia ...
```

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

```bash
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](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/docker-specialized.html#gpu-enumeration).

## 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 (e.g., `-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. Set to `True` to disable if using custom databases that do not support GPU Server. |
| `NIM_GLOBAL_MAX_MSA_DEPTH`  | No        | `500`             | Sets the maximum number of MSA sequences returned. Must be set globally for all requests when GPU Server is enabled (default in version 2.0.0). |
| `NIM_MSA_API_MAX_DATABASES` | No        | `5`               | Maximum number of databases that can be specified in a single API request. |
| `NIM_MSA_API_MAX_MSA_SEQUENCES` | No    | `10001`           | Maximum value for the `max_msa_sequences` API parameter. |
| `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  | `4096`            | Maximum length of an input protein sequence. |
| `NIM_MSA_API_DEFAULT_STRUCTURAL_TEMPLATE_DBS` | No | `PDB70_220313` | Comma-separated list of databases to search for structural templates by default. |
| `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_LOG_LEVEL`             | No        | `INFO`            | Specifies the level of logging detail. Available options: `DEBUG`, `INFO`, `WARNING`, `ERROR`. |
| `NIM_MODEL_NAME`            | No        | None              | Path to custom database directory inside the container. Use with volume mounts to load external or custom MMSeqs2 databases. See [Task-Specific Profiles and Custom Databases](/nim/bionemo/msa-search/2.2.0/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. See [Task-Specific Profiles and Custom Databases](/nim/bionemo/msa-search/2.2.0/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_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](https://www.nvidia.com/en-us/about-nvidia/privacy-policy/) and [NIM Telemetry Settings](https://developer.nvidia.com/docs/nim-tools/latest/templates/nimlib/nim-telemetry.html). |
| `NIM_TELEMETRY_ENABLE_LOGGING` | No     | `true`            | Enables logging for telemetry operations when set to `true`. Only applicable when `NIM_TELEMETRY_MODE=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 via `NIM_MODEL_NAME` env variable)  | Optional    | Mount custom databases by setting `NIM_MODEL_NAME` to point to your database directory inside the container, then mount the host directory to that path. Useful for using external or custom MMSeqs2 databases. See [Task-Specific Profiles and Custom Databases](/nim/bionemo/msa-search/2.2.0/task-specific-profiles-and-custom-databases) for detailed examples. | `-e NIM_MODEL_NAME=/databases -v /host/path/to/db:/databases/mydb:ro` |

<Note>
The `MODEL_PATH` environment variable is also supported for backward compatibility with the same behavior as `NIM_MODEL_NAME`.
</Note>