> This page is for Boltz-2, version 1.2.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. # Getting Started ## Prerequisites - Refer to the [Support Matrix](/nim/bionemo/boltz2/1.2.0/support-matrix) to make sure that you have the supported hardware and software stack. - An NGC personal API key. The NIM microservice uses the API key to download models from NVIDIA NGC. Refer to [Generating a Personal API Key](https://docs.nvidia.com/ngc/gpu-cloud/ngc-user-guide/index.html#generating-personal-api-key) in the NVIDIA NGC User Guide for more information. - To run the below examples you must have `curl`, `jq`, and the Python `requests` module installed. When you create an NGC API personal key, select at least the option for **NGC Catalog** from the **Services Included** menu. You can specify more services to use the key for additional purposes. ### Installing curl, jq, and the Python requests module 1. `curl` is required to send requests from the command line. On Ubuntu and other Debian-based Linux distributions, `curl` can be installed with the following command, which may require `sudo` access: ```bash sudo apt-get update && sudo apt-get install curl ``` 1. `jq` is used to process and reformat responses from the NIM so they are easier to read. `jq` can be installed using the following command, which may require `sudo` access: ```bash sudo apt-get update && sudo apt-get install jq ``` 1. The Python `requests` module facilitates HTTP requests made in many of the examples for this NIM. The Python requests module can be installed using `pip`: ```bash pip install requests ``` ### NGC Authentication #### Generate an API key To access NGC resources, you need an NGC API key. You can generate a key here: [Generate Personal Key](https://org.ngc.nvidia.com/setup/personal-keys). When creating an NGC API Personal key, ensure that "NGC Catalog" is selected from the "Services Included" dropdown. You can include more services if you reuse this key for other purposes. Personal keys allow you to configure an expiration date, revoke, or delete the key using an action button, and rotate the key as needed. For more information about key types, refer to the [NGC User Guide](https://docs.nvidia.com/ngc/gpu-cloud/ngc-user-guide/index.html#ngc-api-keys). #### Export the API key Pass the value of the API key to the `docker run` command in the next section as the `NGC_API_KEY` environment variable to download the appropriate models and resources when starting the NIM. If you're not familiar with how to create the `NGC_API_KEY` environment variable, the simplest way is to export it in your terminal: ```bash export NGC_API_KEY= ``` Run one of the following commands to make the key available at startup: ```bash # If using bash echo "export NGC_API_KEY=" >> ~/.bashrc # If using zsh echo "export NGC_API_KEY=" >> ~/.zshrc ``` Other, more secure options include saving the value in a file, so that you can retrieve with `cat $NGC_API_KEY_FILE`, or using a [password manager](https://www.passwordstore.org/). #### Docker Login to NGC To pull the NIM container image from NGC, first authenticate with the NVIDIA Container Registry with the following command: ```bash echo "$NGC_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin ``` Use `$oauthtoken` as the username and `NGC_API_KEY` as the password. The `$oauthtoken` username is a special name that indicates that you will authenticate with an API key and not a username and password. ## Starting the NIM Container 1. Ensure you have logged in to Docker and set your `NGC_API_KEY` environment variable as detailed in the preceding section. 1. Create a NIM Cache. If one already exists, you may use the existing one. ```bash export LOCAL_NIM_CACHE=~/.cache/nim mkdir -p ${LOCAL_NIM_CACHE} chmod 777 ${LOCAL_NIM_CACHE} ``` 1. Start the NIM container: ```bash ## Note: these two commands are not required if you have already set the appropiate variables in previous instructions. ## They are provided here as part of a one-click startup sequence. export LOCAL_NIM_CACHE=~/.cache/nim export NGC_API_KEY= ``` ```bash docker run --rm --name boltz2 --runtime=nvidia \ --shm-size=16G \ -e NGC_API_KEY \ -v $LOCAL_NIM_CACHE:/opt/nim/.cache \ -p 8000:8000 \ nvcr.io/nim/mit/boltz2:1.2.0 ``` The preceding command starts the container with the default profile, using all available system GPUs. **Note**: This will require localizing up to 30 Gigabytes of data to disk. If you have the model cached, the version in the NIM cache specified at `LOCAL_NIM_CACHE` will be used. 1. (Optional) Confirm the service is ready to respond to inference requests: ```console $ curl -X GET http://localhost:8000/v1/health/ready ``` *Example Output* ```console 200 true ``` 1. Send an inference request: ```bash #!/bin/bash # Define the protein sequence SEQUENCE="MALWMRLLPLLALLALWGPDPAAAFVNQHLCGSHLVEALYLVCGERGFFYTPKTRREAEDLQVGQVELGGGPGAGSLQPLALEGSLQKRGIVEQCCTSICSLYQLENYCN" # Create JSON payload for protein structure prediction JSON_DATA='{ "polymers": [ { "id": "A", "molecule_type": "protein", "sequence": "'"$SEQUENCE"'" } ], "recycling_steps": 3, "sampling_steps": 50, "diffusion_samples": 1, "step_scale": 1.638, "output_format": "mmcif" }' echo "Making request..." # Make the POST request # Note: This script requires jq to be installed for JSON processing response=$(curl -s -X POST \ -H "Content-Type: application/json" \ -d "$JSON_DATA" \ http://localhost:8000/biology/mit/boltz2/predict) # Extract and display the structure information # Using jq to parse the JSON response echo "Structure prediction completed" echo "Format: $(echo $response | jq -r '.structures[0].format')" echo "Confidence score: $(echo $response | jq -r '.confidence_scores[0]')" echo "Structure (first 500 chars): $(echo $response | jq -r '.structures[0].structure' | head -c 500)..." ``` ```python import requests import json if __name__ == "__main__": sequence = "MALWMRLLPLLALLALWGPDPAAAFVNQHLCGSHLVEALYLVCGERGFFYTPKTRREAEDLQVGQVELGGGPGAGSLQPLALEGSLQKRGIVEQCCTSICSLYQLENYCN" # Replace with your sequence value of interest headers = { "content-type": "application/json" } data = { "polymers": [ { "id": "A", "molecule_type": "protein", "sequence": sequence } ], "recycling_steps": 3, "sampling_steps": 50, "diffusion_samples": 1, "step_scale": 1.638, "output_format": "mmcif" } print("Making request...") response = requests.post("http://localhost:8000/biology/mit/boltz2/predict", headers=headers, data=json.dumps(data)) result = response.json() print("Structure prediction completed") # Access the first predicted structure if result.get("structures"): structure = result["structures"][0] print(f"Structure format: {structure['format']}") print(f"Confidence score: {result['confidence_scores'][0]}") print(f"Structure (first 500 chars): {structure['structure'][:500]}...") ``` The description of all API parameters could be found in the [Input Parameters section](/nim/bionemo/boltz2/1.2.0/inference#input-parameters) of the Inference Guide. ## Runtime Parameters for the Container | Flags | Description | |----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `-it` | `--interactive` + `--tty` (see [Docker docs](https://docs.docker.com/reference/cli/docker/container/run/)) | | `--rm` | Delete the container after it stops (see [Docker docs](https://docs.docker.com/reference/cli/docker/container/run/)). | | `--name=` | Give a name to the NIM container. Use any preferred value. | | `--runtime=nvidia` | Ensure NVIDIA drivers are accessible in the container. | | `--gpus '"device=0"'` | Expose NVIDIA GPU 0 inside the container. If you are running on a host with multiple GPUs, you need to specify which GPU to use. See [GPU Enumeration](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/docker-specialized.html) for further information on for mounting specific GPUs. | | `-e NGC_API_KEY=$NGC_API_KEY` | Provide the container with the token necessary to download adequate models and resources from NGC. See [above](#ngc-authentication). | | `-e NIM_MODEL_PROFILE=` | Specify the profile to use for the NIM. See the [Support Matrix section](/nim/bionemo/boltz2/1.2.0/support-matrix) for more information about available profiles. | | `-e NIM_HTTP_API_PORT=8000` | Specify the port that would be used by NIM inside the container (default is `8000`). | | `-p 8000:8000` | Forward the port where the NIM HTTP server is published inside the container to access from the host system. The left-hand side of `:` is the host system ip:port (`8000` here), while the right-hand side is the container port where the NIM HTTP server is published. | ## Caching Models The first time you start the container, the microservice downloads the model from NGC. You can avoid this download step on future runs by caching the model locally. ```bash # Create the cache directory on the host machine. export LOCAL_NIM_CACHE=~/.cache/nim mkdir -p "$LOCAL_NIM_CACHE" chmod 777 $LOCAL_NIM_CACHE # Run the container with the cache directory as a volume mount. ``` ```bash docker run --rm --name boltz2 --runtime=nvidia \ --shm-size=16G \ -e NGC_API_KEY \ -v $LOCAL_NIM_CACHE:/opt/nim/.cache \ -p 8000:8000 \ nvcr.io/nim/mit/boltz2:1.2.0 ``` ## Stopping the Container The following commands stop the container by stopping and removing the running docker container. ```bash docker stop boltz2 docker rm boltz2 ``` ## Next Steps - Refer to the [Deployment section](/nim/bionemo/boltz2/1.2.0/inference#deployment) in the Inference Guide for more detailed instructions on how to deploy the NIM. - Refer to [Optimization](/nim/bionemo/boltz2/1.2.0/optimization) for settings related to optimizing performance of the NIM on your hardware and software stack.