> This page is for MSA Search, version 3.0.0 (Latest) (default).
> For other versions, use one of these documentation indexes:
> - 3.0.0 (Latest) (default): https://docs.nvidia.com/nim/bionemo/msa-search/3.0.0/llms.txt
> - 2.6.0: 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.

# Quickstart for MSA Search

> Start the MSA Search NIM container and run your first monomer, paired, structural template, and RNA multiple sequence alignment search requests.

This quickstart walks you through starting the MSA Search NIM container and running your first MSA, paired MSA, and structural template search requests.

## Prerequisites

Before you begin, ensure you have completed the setup described in [Prerequisites](/nim/bionemo/msa-search/get-started/prerequisites) and the [Support Matrix](/nim/bionemo/msa-search/get-started/support-matrix), including:

- Compatible hardware and software (see [Support Matrix](/nim/bionemo/msa-search/get-started/support-matrix))
- Python 3 with the `requests` module (for running examples)
- `jq` (for the template search shell example)

## Start the NIM Container

To start the NIM container, complete the following steps:

1. Create a local cache directory for the NIM.

   The container runs as UID/GID 1000 (`nvs`), and the directory must be writable by that user. If your account is a different UID, the following `chown` assigns the cache to `1000`. Leave the container user unchanged so the service can create `/opt/nim/workspace`. Refer to [Volumes](/nim/bionemo/msa-search/configuration#volumes).

   ```bash
   export LOCAL_NIM_CACHE=~/.cache/nim
   mkdir -p "$LOCAL_NIM_CACHE"
   if [ "$(id -u)" -ne 1000 ]; then
     sudo chmod 700 "$LOCAL_NIM_CACHE"
     sudo chown -R 1000:1000 "$LOCAL_NIM_CACHE"
   else
     chmod 700 "$LOCAL_NIM_CACHE"
   fi
   ```

2. Start the NIM container.

   ```bash
   docker run -it --rm \
     --runtime=nvidia \
     --gpus all \
     -v "$LOCAL_NIM_CACHE:/opt/nim/.cache" \
     -p 8000:8000 \
     nvcr.io/nim/colabfold/msa-search:3
   ```
   

   <Note>
   The first time you start the container, it will download approximately 1.4 TB of database files to the local cache. This process can take several hours depending on your internet connection speed. Subsequent starts will use the cached data.
   </Note>

3. Confirm the service is ready to respond to inference requests.

   ```bash
   curl http://localhost:8000/v1/health/ready
   ```

## MSA Search Examples

The following examples demonstrate how to use the MSA Search NIM to perform multiple sequence alignment on protein sequences.

For comprehensive descriptions of all available API parameters, refer to the [API Reference](/nim/bionemo/msa-search/api-reference). For information on assessing model performance, refer to [Benchmarking](/nim/bionemo/msa-search/benchmarking).

### Python Client Example

The following example shows how to search for similar sequences and generate a multiple sequence alignment. To run the example, complete the following steps:

1. Save the following Python example to a file named `nim_client.py`.

   ```python
   #!/usr/bin/env python3

   import requests
   import json

   url = "http://localhost:8000/biology/colabfold/msa-search/predict"

   r = requests.post(
       json={
           "sequence": "SGSMKTAISLPDETFDRVSRRASELGMSRSEFFTKAAQR",
           "e_value": 0.0001,
           "iterations": 1,
           "output_alignment_formats": ["a3m", "fasta"],
       },
       url=url,
   )

   print(r.text[:100], "...")
   r = r.json()
   print("Response keys:", list(r.keys()), "\n")
   print("Alignments by dbs:\n")
   for db, formats in r["alignments"].items():
       print(" ", db)
       for fmt, alignment_obj in formats.items():
           aln = alignment_obj["alignment"]
           print("   ", alignment_obj["format"], "lines:", len(aln.split("\n")))
           from textwrap import indent
           print(indent(aln[:300] + "...", "        | "))
   ```

2. Execute the example.

   ```bash
   chmod +x nim_client.py
   ./nim_client.py
   ```

The example will display the alignment results for each database, showing the format and a preview of the alignment content.

### Shell Client Example

You can also use `curl` to send requests directly:

```bash
curl http://localhost:8000/biology/colabfold/msa-search/predict \
  -H "Content-Type: application/json" \
  -d '{
    "sequence": "SGSMKTAISLPDETFDRVSRRASELGMSRSEFFTKAAQR",
    "e_value": 0.0001,
    "iterations": 1,
    "output_alignment_formats": ["a3m", "fasta"]
  }' -o response.json && sed 's/\\n/\n/g' response.json | head -n 25 && echo "...trimmed..."
```

## Paired MSA Search for Protein Complexes

The MSA Search NIM also supports paired MSA search for protein complexes (multimers). Paired search finds homologous sequences for each chain and pairs them by species, preserving co-evolutionary signals essential for accurate complex structure prediction.

### Python Client Example for Paired Search

To perform a paired MSA search for a two-chain protein complex, complete the following steps:

1. Save the following Python example to a file named `nim_client_paired.py`.

   ```python
   #!/usr/bin/env python3

   import requests
   import json
   from pathlib import Path

   url = "http://localhost:8000/biology/colabfold/msa-search/paired/predict"

   # Hemoglobin alpha and beta chains (truncated for example)
   seq1 = "VLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHGKKVADALTNAVA"
   seq2 = "MHLTPEEKSAVTALWGKVNVDEVGGEALGRLLVVYPYTQRFFESFGDLSTPDAVMGNPKVKAHGKKVLGAF"

   r = requests.post(
       json={
           "sequences": [seq1, seq2],
           "e_value": 0.0001,
       },
       url=url,
   )

   print(r.text[:100], "...")
   r = r.json()

   Path("msa_outputs_paired").mkdir(exist_ok=True)
   Path("msa_outputs_paired/response.json").write_text(json.dumps(r, indent=4, sort_keys=True))
   print("Saved response to msa_outputs_paired/response.json\n")

   print("Response keys:", list(r.keys()), "\n")
   print("Alignments by chain:\n")

   for chain_id, alignments in r["alignments_by_chain"].items():
       print(f" Chain {chain_id}:")
       for db, formats in alignments.items():
           print(f"   {db}")
           for fmt, alignment_obj in formats.items():
               aln = alignment_obj["alignment"]
               fmt_name = alignment_obj["format"]
               print("     ", fmt_name, "lines:", len(aln.split("\n")))
               from textwrap import indent
               print(indent(aln[:300] + "...", "          | "))

               f = Path(f"msa_outputs_paired/{chain_id}_{db}.{fmt_name}")
               f.write_text(aln)
               print(f"          Saved to {f}")
   ```

2. Execute the example.

   ```bash
   chmod +x nim_client_paired.py
   ./nim_client_paired.py
   ```

### Shell Client Example for Paired Search

You can also use `curl` to send paired MSA requests:

```bash
curl http://localhost:8000/biology/colabfold/msa-search/paired/predict \
  -H "Content-Type: application/json" \
  -d '{
    "sequences": [
        "VLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHGKKVADALTNAVA",
        "MHLTPEEKSAVTALWGKVNVDEVGGEALGRLLVVYPYTQRFFESFGDLSTPDAVMGNPKVKAHGKKVLGAF"
    ],
    "e_value": 0.0001
  }' -o response.json && sed 's/\\n/\n/g' response.json | head -n 25 && echo "...trimmed..."
```

The response contains `alignments_by_chain` with paired alignments for each chain (for example, "A", "B"), where each chain has the same number of sequences paired by species.

## Structural Template Search

The MSA Search NIM supports structural template search for finding homologous protein structures. Template search queries PDB databases to find proteins with similar structures and retrieves the corresponding mmCIF structure files.

### Python Client Example for Template Search

To run a structural template search, complete the following steps:

1. Save the following Python example to a file named `nim_client_template_search.py`.

   ```python
   #!/usr/bin/env python3

   import requests
   import json
   from pathlib import Path

   url = "http://localhost:8000/biology/colabfold/msa-search/structure-templates/predict"

   # Hemoglobin alpha chain
   seq = "VLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHGKKVADALTNAVA"

   r = requests.post(
       json={
           "sequence": seq,
           "structural_template_databases": ["pdb70_220313"],
           "e_value": 0.0001,
           "max_structures": 20,
       },
       url=url,
   )

   print(r.text[:100], "...")
   r = r.json()

   Path("structure_outputs").mkdir(exist_ok=True)
   Path("structure_outputs/response.json").write_text(json.dumps(r, indent=4, sort_keys=True))
   print("Saved response to structure_outputs/response.json\n")

   print("Response keys:", list(r.keys()), "\n")
   print("N structures:", len(r["structures"]))
   for pdb_id, s in r["structures"].items():
       preview = s['structure'][:70].replace('\n', '\\n')
       print(f"  {pdb_id}: {preview}...")
   ```

2. Execute the example.

   ```bash
   chmod +x nim_client_template_search.py
   ./nim_client_template_search.py
   ```

### Shell Client Example for Template Search

Search for a template:

```bash
curl http://localhost:8000/biology/colabfold/msa-search/structure-templates/predict \
  -H "Content-Type: application/json" \
  -d '{
    "sequence": "SGSMKTAISLPDETFDRVSRRASELGMSRSEFFTKAAQR",
    "structural_template_databases": ["pdb70_220313"],
    "max_structures": 5
  }' | jq '.search_hits, .structures | keys'
```

The response includes:
- `search_hits`: Template hits in M8 format organized by database
- `structures`: Retrieved mmCIF structure files for the top hits
- `alignments`: MSA alignments (same as standard MSA search)

For detailed API parameters, refer to the [API Reference](/nim/bionemo/msa-search/api-reference).

## RNA MSA Search

The MSA Search NIM supports RNA MSA search for nucleotide sequence homologs. By default, the NIM is configured for protein databases. To start the NIM in RNA search mode, select the `databases:rna` model profile (refer to [Task-Specific Profiles and Custom Databases](/nim/bionemo/msa-search/task-specific-profiles-and-custom-databases) for details).

### Start the NIM in RNA Mode

If the protein NIM container is still running from the earlier example, stop it first (press `Ctrl+C` or run `docker stop` on the container) to free port 8000.

```bash
export LOCAL_NIM_CACHE=~/.cache/nim
mkdir -p "$LOCAL_NIM_CACHE"
# The container runs as UID 1000. Give that user ownership when this account is different.
if [ "$(id -u)" -ne 1000 ]; then
  sudo chmod 700 "$LOCAL_NIM_CACHE"
  sudo chown -R 1000:1000 "$LOCAL_NIM_CACHE"
else
  chmod 700 "$LOCAL_NIM_CACHE"
fi
```

```bash
docker run -it --rm \
  --runtime=nvidia \
  --gpus all \
  -e NIM_MODEL_PROFILE=a60d3de82ada0810080d4d8acc500464faae466313cf39374033d7da5c3f9b00 \
  -v "$LOCAL_NIM_CACHE:/opt/nim/.cache" \
  -p 8000:8000 \
  nvcr.io/nim/colabfold/msa-search:3
```


<Note>
The RNA databases (RNAcentral) are approximately 94 GB. The first start downloads them to the local cache.
</Note>

### Python Client Example (RNA)

To run the RNA MSA search example, complete the following steps:

1. Save the following Python example to a file named `nim_client_rna.py`.

   ```python
   #!/usr/bin/env python3

   import requests
   import json
   from pathlib import Path

   url = "http://localhost:8000/biology/riboseek/msa-search/predict"

   r = requests.post(
       json={
           "sequence": "GGCUCAGUGGUCCAAUGGUAAAGCGCUCGUCGCAGAGCCAGAGGGUCCUGGGUUCGAUUCCCAACAGGGUCA",
           "e_value": 0.1,
           "iterations": 3,
       },
       url=url,
   )

   print(r.text[:100], "...")
   r = r.json()

   Path("msa_outputs_rna").mkdir(exist_ok=True)
   Path("msa_outputs_rna/response.json").write_text(json.dumps(r, indent=4, sort_keys=True))
   print("Saved response to msa_outputs_rna/response.json\n")

   print("Response keys:", list(r.keys()), "\n")
   print("Alignments by dbs:\n")
   for db, formats in r["alignments"].items():
       print(" ", db)
       for fmt, alignment_obj in formats.items():
           aln = alignment_obj["alignment"]
           fmt_name = alignment_obj["format"]
           print("   ", fmt_name, "lines:", len(aln.split("\n")))
           from textwrap import indent
           print(indent(aln[:300] + "...", "        | "))

           f = Path(f"msa_outputs_rna/{db}.{fmt_name}")
           f.write_text(aln)
           print(f"        Saved to {f}")
   ```

2. Execute the example.

   ```bash
   chmod +x nim_client_rna.py
   ./nim_client_rna.py
   ```

### Shell Client Example (RNA)

```bash
curl http://localhost:8000/biology/riboseek/msa-search/predict \
  -H "Content-Type: application/json" \
  -d '{
    "sequence": "GGCUCAGUGGUCCAAUGGUAAAGCGCUCGUCGCAGAGCCAGAGGGUCCUGGGUUCGAUUCCCAACAGGGUCA",
    "e_value": 0.1,
    "iterations": 3
  }' -o response.json && sed 's/\\n/\n/g' response.json | head -n 25 && echo "...trimmed..."
```

## Stop the Container

The `docker run` preceding command uses `-it --rm`, so press `Ctrl+C` in the terminal running the container to stop it and remove it.

## Next Steps

- [Benchmarking](/nim/bionemo/msa-search/benchmarking) - View benchmarking results and learn how to run your own performance tests
- [Configuration](/nim/bionemo/msa-search/configuration) - Configure environment variables, GPU selection, and volume mounting
- [Task-Specific Profiles and Custom Databases](/nim/bionemo/msa-search/task-specific-profiles-and-custom-databases) - Reduce storage requirements with profiles or use custom databases
- [Scaling](/nim/bionemo/msa-search/scaling) - Learn about scaling strategies for production deployments
- [API Reference](/nim/bionemo/msa-search/api-reference) - Reference the comprehensive API documentation with all available parameters