> This page is for Boltz-2, version 1.0.0.
> For other versions, use one of these documentation indexes:
> - 1.10.0 (Latest) (default): https://docs.nvidia.com/nim/bionemo/boltz2/1.10.0/llms.txt
> - 1.9.0: https://docs.nvidia.com/nim/bionemo/boltz2/1.9.0/llms.txt
> - 1.8.0: https://docs.nvidia.com/nim/bionemo/boltz2/1.8.0/llms.txt
> - 1.7.0: https://docs.nvidia.com/nim/bionemo/boltz2/1.7.0/llms.txt
> - 1.6.0: https://docs.nvidia.com/nim/bionemo/boltz2/1.6.0/llms.txt
> - 1.5.0: https://docs.nvidia.com/nim/bionemo/boltz2/1.5.0/llms.txt
> - 1.4.0: https://docs.nvidia.com/nim/bionemo/boltz2/1.4.0/llms.txt
> - 1.3.0: https://docs.nvidia.com/nim/bionemo/boltz2/1.3.0/llms.txt
> - 1.2.0: https://docs.nvidia.com/nim/bionemo/boltz2/1.2.0/llms.txt
> - 1.1.0: https://docs.nvidia.com/nim/bionemo/boltz2/1.1.0/llms.txt
> - 1.0.0: https://docs.nvidia.com/nim/bionemo/boltz2/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.

# Deploy Using Docker

This section describes how to deploy using Docker.

<Note>
This page assumes you have prepared your environment as detailed in the [Getting Started section](/nim/bionemo/boltz2/1.0.0/getting-started) (see the sections on setting up Docker, NGC CLI, and NGC registry access).
</Note>

1. Pull the Boltz-2 NIM container with the following command.

```bash
docker pull nvcr.io/nim/mit/boltz2:1.0.0
```


2. Run the NIM container with the following command.

```bash
export LOCAL_NIM_CACHE=~/.cache/nim
export NGC_API_KEY=<Your NGC API Key>
```

```bash
docker run --rm --name boltz2 --runtime=nvidia \
    -e NGC_API_KEY \
    -v $LOCAL_NIM_CACHE:/opt/nim/.cache \
    -p 8000:8000 \
    nvcr.io/nim/mit/boltz2:1.0.0
```


This command will start the NIM container and expose port 8000 for the user to interact with the NIM. It will pull the model to the cache at `$LOCAL_NIM_CACHE` on the local filesystem. **Note**: This download can take a very long time (2-10 hours on a 100+Mbps internet connection).

3. Open a new terminal, leaving the current terminal open with the launched service.

4. In the new terminal, wait until the health check end point returns `200 true` before proceeding. This may take a couple of minutes. You can use the following command to query the health check.

```bash
curl -X 'GET' \
    'http://localhost:8000/v1/health/ready' \
    -H 'accept: application/json'
```

To check the NIM's status using Python, use the requests module, after installation, using `pip install requests`:

```python
import requests

url = "http://localhost:8000/v1/health/ready"  # Replace with the actual URL

headers = {
    "content-type": "application/json"
}
try:
    response = requests.get(url, headers=headers)

    # Check if the request was successful
    if response.ok:
        print("Request succeeded:", response.json())
    else:
        print("Request failed:", response.status_code, response.text)
except Exception as E:
    print("Request failed:", E)
```

5. Run the inference to get a multiple sequence alignment for an amino acid sequence. The following is an example of using cURL in BASH:

```bash
#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

# Define the data payload as JSON using a subshell to prevent read issues
data=$(cat <<EOF
{
    "polymers": [
        {
            "id": "A",
            "molecule_type": "protein",
            "sequence": "MKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG",
            "msa": {
                "uniref90": {
                    "a3m": {
                        "alignment": ">seq1\nMKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG\n>seq2\nMKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG",
                        "format": "a3m"
                    }
                }
            }
        }
    ]
}
EOF
)

# Make the POST request
echo "Making request to local NIM..."

# Perform the POST request with curl and save response to output.json
curl -s -X POST "http://localhost:8000/biology/mit/boltz2/predict" \
    -H "Content-Type: application/json" \
    -d "$data" > output.json

echo "Response saved to output.json"
```

The following is an example, in Python, that demonstrates some of the other arguments available to the NIM:

```python
import requests
import json

url = "http://localhost:8000/biology/mit/boltz2/predict"

headers = {
    "content-type": "application/json"
}

data = {
    "polymers": [
        {
            "id": "A",
            "molecule_type": "protein",
            "sequence": "MKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG",
            "msa": {
                "uniref90": {
                    "a3m": {
                        "alignment": ">seq1\nMKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG\n>seq2\nMKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG",
                        "format": "a3m"
                    }
                }
            }
        }
    ]
}

response = requests.post(url, headers=headers, data=json.dumps(data))

# Check if the request was successful
if response.ok:
    print("Request succeeded:", response.json())
else:
    print("Request failed:", response.status_code, response.text)
```

6. View the outputs. You can use the `cat` tool to print the outputs to the command line:

```bash
cat output.json
```

You can also view the output in a text viewer, or pretty-print it using Python's built-in JSON module:

```bash
python -m json.tool output.json
```

## Multiple Sequence Alignment Formatting

The Boltz-2 NIM uses a specific JSON structure for its MSA inputs to enable compatibility with the MSA NIM and other tools. The NIM accepts MSA inputs in the following formats:

| Format | Description |
|--------|-------------|
| A3M | A3M format is a variant of FASTA format that uses lowercase letters to indicate insertions relative to the first sequence. The first sequence in the alignment should be the query sequence. |
| CSV | CSV format requires a header row with columns "key" and "sequence". Each row should contain an integer key (which may be -1) and the corresponding sequence. |

These formats can be generated using either the Boltz-2 python package or the ColabFold server (CSV), or by using an MSA search tool of your choice (A3M).

The NIM accepts MSAs in a dictionary structure that maps database names to MSA formats and their corresponding alignments. The structure is as follows:

```
{
    "polymers": [
        {
            "id": "A",
            "molecule_type": "protein",
            "sequence": "SEQUENCE",
            "msa": {
                "database_name": {           # e.g., "uniref90", "pdb70"
                    "format_name": {         # e.g., "a3m", "csv"
                        "format": "FORMAT",  # e.g., "a3m", "csv"
                        "alignment": "DATA"  # The actual alignment data
                    }
                }
            }
        }
    ]
}
```

Example with actual data:
```
{
    "polymers": [
        {
            "id": "A",
            "molecule_type": "protein",
            "sequence": "MKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG",
            "msa": {
                "uniref90": {
                    "a3m": {
                        "format": "a3m",
                        "alignment": ">seq1\nMKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG\n>seq2\nMKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG"
                    }
                }
            }
        }
    ]
}
```

<Note>
For very large multiple sequence alignments, we recommend using functions like the following to read them directly from their formats on disk.
</Note>

```python
def load_a3m(filename: str, database_name: str = "uniref90") -> dict:
    """
    Load an A3M format multiple sequence alignment from a file.

    Args:
        filename: Path to the A3M file
        database_name: Name of the database to use as the outer key (default: "uniref90")

    Returns:
        Dictionary containing the MSA data in the format expected by the Boltz2 API
    """
    try:
        with open(filename, 'r') as f:
            # Read the file and remove any null bytes
            content = f.read().replace('\0', '')

        # Create the MSA structure
        msa_data = {
            database_name: {
                "a3m": {
                    "format": "a3m",
                    "alignment": content.strip()  # Keep original A3M content
                }
            }
        }
        return msa_data
    except Exception as e:
        raise Exception(f"Error loading A3M file {filename}: {str(e)}")

def load_csv(filename: str, database_name: str = "uniref90") -> dict:
    """
    Load a CSV format multiple sequence alignment from a file.

    Args:
        filename: Path to the CSV file
        database_name: Name of the database to use as the outer key (default: "uniref90")

    Returns:
        Dictionary containing the MSA data in the format expected by the Boltz2 API
    """
    try:
        with open(filename, 'r') as f:
            # Read the file and remove any null bytes
            content = f.read().replace('\0', '')

        # Parse CSV content
        csv_reader = csv.DictReader(content.splitlines())

        # Create the MSA structure with CSV format
        msa_data = {
            database_name: {
                "csv": {
                    "format": "csv",
                    "alignment": content.strip()  # Keep original CSV content
                }
            }
        }
        return msa_data
    except Exception as e:
        raise Exception(f"Error loading CSV file {filename}: {str(e)}")

# Example usage:
if __name__ == "__main__":
    import json
    import csv

    # Example 1: Load MSA from A3M file with default database name
    a3m_data = load_a3m("path/to/alignment.a3m")

    # Example 2: Load MSA from A3M file with custom database name
    a3m_data_custom = load_a3m("path/to/alignment.a3m", database_name="pdb70")

    # Example 3: Load MSA from CSV file with default database name
    csv_data = load_csv("path/to/alignment.csv")

    # Example 4: Load MSA from CSV file with custom database name
    csv_data_custom = load_csv("path/to/alignment.csv", database_name="custom_db")

    # Example 5: Create request payload with loaded MSA
    request_data = {
        "polymers": [
            {
                "id": "A",
                "molecule_type": "protein",
                "sequence": "MKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG",
                "msa": a3m_data  # or csv_data, a3m_data_custom, csv_data_custom
            }
        ],
        "recycling_steps": 3,
        "sampling_steps": 50,
        "diffusion_samples": 1,
        "step_scale": 1.638,
        "output_format": "mmcif"
    }

    # Print the formatted request data
    print(json.dumps(request_data, indent=2))
```

## Advanced Usage

For Advanced Usage of the NIM, see the sections on [Optimization](/nim/bionemo/boltz2/1.0.0/optimization) and [Performance](/nim/bionemo/boltz2/1.0.0/performance).

For details about available endpoints, see the [API Reference](/nim/bionemo/boltz2/1.0.0/api-reference) section.