Skip to navigation

Quickstart for Boltz-2

View as MarkdownOpen in Claude

This Quickstart Guide walks you through authenticating with NGC, starting the Boltz-2 NIM container, and running your first prediction request. For comprehensive system requirements and verified configurations, refer to the Support Matrix.

Prerequisites

Before you begin, make sure you have the following:

  • Refer to the 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 in the NVIDIA NGC User Guide for more information.

  • To run the following 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

Install each of the following tools:

  1. Install curl to send requests from the command line.

    On Ubuntu and other Debian-based Linux distributions, install it with the following command, which could require sudo access:

    sudo apt-get update && sudo apt-get install curl
  2. Install jq to process and reformat responses from the NIM so they are easier to read.

    Install it using the following command, which may require sudo access:

    sudo apt-get update && sudo apt-get install jq
  3. Install the Python requests module, which facilitates HTTP requests made in many of the examples for this NIM.

    Install it using pip:

    pip install requests

NGC Authentication

The following steps generate and export the NGC API key that the NIM uses to download models.

Generate an API Key

To access NGC resources, you need an NGC API key. You can generate a key here: API 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.

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 are not familiar with how to create the NGC_API_KEY environment variable, export it in your terminal:

export NGC_API_KEY=<value>

Run one of the following commands to make the key available at startup:

# If using bash
echo "export NGC_API_KEY=<value>" >> ~/.bashrc
# If using zsh
echo "export NGC_API_KEY=<value>" >> ~/.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.

Docker Login to NGC

To pull the NIM container image from NGC, first authenticate with the NVIDIA Container Registry with the following command:

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.

Quickstart Steps

To start the Boltz-2 NIM and run your first prediction, complete the following steps:

  1. Confirm you have logged in to Docker and set your NGC_API_KEY environment variable, as detailed in the preceding section.

  2. Create a NIM Cache.

    If one already exists, you may use the existing one.

    export LOCAL_NIM_CACHE=~/.cache/nim
    mkdir -p ${LOCAL_NIM_CACHE}
    chmod 777 ${LOCAL_NIM_CACHE}
  3. Start the NIM container:

    ## Note: these two commands are not required if you have already set the appropriate variables in previous instructions.
    ## They are provided here as part of a one-click startup sequence.
    export LOCAL_NIM_CACHE=~/.cache/nim
    export LOCAL_NIM_OUTPUT=~/boltz2-nim-output
    export NGC_API_KEY=<Your NGC API Key>
    mkdir -p ${LOCAL_NIM_OUTPUT}
    chmod 777 ${LOCAL_NIM_OUTPUT}
    docker run --rm --name boltz2 --runtime=nvidia \
    --shm-size=16G \
    -e NGC_API_KEY \
    -e NIM_OUTPUT_PATH=/opt/nim/output \
    -v $LOCAL_NIM_CACHE:/opt/nim/.cache \
    -v $LOCAL_NIM_OUTPUT:/opt/nim/output \
    -p 8000:8000 \
    nvcr.io/nim/mit/boltz2:1.10.0
    • Mounting /opt/nim/output keeps prediction artifacts (confidence JSONs, PAE/PDE .npz files) separate from the model cache. Refer to Volumes. To serve fine-tuned weights, refer to Custom Checkpoints.
    • The --runtime=nvidia flag is the legacy approach for GPU access and might require additional Docker daemon configuration. For Docker 19.03 or later, you can use the --gpus flag instead, which works without additional configuration.

    Use all GPUs:

    docker run --rm --name boltz2 --gpus all \
    --shm-size=16G \
    -e NGC_API_KEY \
    -e NIM_OUTPUT_PATH=/opt/nim/output \
    -v $LOCAL_NIM_CACHE:/opt/nim/.cache \
    -v $LOCAL_NIM_OUTPUT:/opt/nim/output \
    -p 8000:8000 \
    nvcr.io/nim/mit/boltz2:1.10.0

    Or specify one GPU device:

    docker run --rm --name boltz2 --gpus "device=0" \
    --shm-size=16G \
    -e NGC_API_KEY \
    -e NIM_OUTPUT_PATH=/opt/nim/output \
    -v $LOCAL_NIM_CACHE:/opt/nim/.cache \
    -v $LOCAL_NIM_OUTPUT:/opt/nim/output \
    -p 8000:8000 \
    nvcr.io/nim/mit/boltz2:1.10.0

    The preceding command starts the container with the default profile, using all available system GPUs.

    This requires localizing up to 30 GB of data to disk. If you have the model cached, the version in the NIM cache specified at LOCAL_NIM_CACHE is used.

  4. (Optional) Confirm the service is ready to respond to inference requests:

    $ curl -i -X GET http://localhost:8000/v1/health/ready

    Example Output

    HTTP/1.1 200 OK
    content-type: application/json
    true
  5. Send an inference request:

#!/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 "Complex PDE score: $(echo $response | jq -r '.complex_pde_scores[0]')"
echo "Structure (first 500 chars): $(echo $response | jq -r '.structures[0].structure' | head -c 500)..."

The description of all API parameters is in the Input parameters section of the Inference page.

Runtime Parameters for the Container

The following table lists the runtime flags used with the docker run command.

FlagsDescription
-it--interactive + --tty (refer to the Docker docs)
--rmDelete the container after it stops (refer to the Docker docs).
--name=<container-name>Give a name to the NIM container. Use any preferred value.
--runtime=nvidia(Legacy) Ensure NVIDIA drivers are accessible in the container. Requires additional Docker daemon configuration. For Docker 19.03+, using --gpus is recommended as it works without additional configuration.
--gpus all(Recommended for Docker 19.03+) Expose all available NVIDIA GPUs inside the container. This is the modern approach for GPU access.
--gpus '"device=0"'Expose specific NVIDIA GPUs inside the container (for example, device 0). If you are running on a host with multiple GPUs, you can specify which GPUs to use. Refer to GPU enumeration for further information.
-e NGC_API_KEY=$NGC_API_KEYProvide the container with the token necessary to download adequate models and resources from NGC. Refer to NGC authentication.
-e NIM_MODEL_PROFILE=<profile_id>Optional. Pin the shipped 1.9.0 profile. Leave unset for auto-selection. Refer to Select a profile manually and the Support Matrix.
-e NIM_HTTP_API_PORT=8000Specify the port that would be used by NIM inside the container (default is 8000).
-p 8000:8000Forward 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.

# 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.
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.10.0

Stopping the Container

The following commands stop the container by stopping and removing the running docker container.

docker stop boltz2
docker rm boltz2

Running on Slurm With Enroot

This section describes how to run the Boltz2 NIM on a Slurm-based HPC cluster using Enroot to run the NGC container.

NGC_API_KEY: You must export your NGC API key before running the Slurm script so that Enroot can pull the image from NGC. Then run the script (for example, bash boltz2_srun.sh).

Before you start, you must complete the following prerequisites:

  1. Install Enroot version 3.4.1 or newer on the cluster.

  2. Export your NGC API key in your environment so that Enroot can pull the image from NGC:

    export NGC_API_KEY=<your_NGC_API_key>

To run the Boltz-2 NIM on Slurm with Enroot, complete the following steps:

  1. Check that Enroot is available.

    On the login node, verify Enroot is installed:

    enroot version
    which enroot

    If Enroot is not installed, contact your cluster administrator. Create the Enroot config directory if it does not exist:

    mkdir -p ~/.config/enroot
  2. Create and add NGC credentials.

    Create the credentials file so Enroot can pull images from NGC. Replace YOUR_NGC_API_KEY with your NGC API key:

    echo 'machine nvcr.io login $oauthtoken password YOUR_NGC_API_KEY' > ~/.config/enroot/.credentials
    chmod 600 ~/.config/enroot/.credentials
  3. Configure and run the Slurm job script.

    Copy the script below to a file, such as boltz2_srun.sh, and set the variables at the top for your cluster and paths:

    • ACCOUNT: Slurm account name
    • PARTITION: Slurm partition (for example, interactive or gpu)
    • ROOT_DIR: Your working directory on the cluster (for example, Lustre or NFS path)
    • NGC_API_KEY: Must be exported in your environment before running the script (for example, export NGC_API_KEY=<your_key>)

    Use a shared filesystem path for ROOT_DIR and CACHE_PATH so that the SQSH image and cache are visible from the node where the job runs. Save the following as boltz2_srun.sh and run it with bash boltz2_srun.sh:

    #!/bin/bash
    # --- Slurm job configuration (customize for your cluster) ---
    ACCOUNT="your_slurm_account"
    PARTITION="interactive"
    GPUS_PER_NODE=1
    MEMORY="32G"
    TIME="04:00:00"
    # --- Paths (customize for your cluster) ---
    ROOT_DIR="/path/to/your/workspace"
    CACHE_PATH="${ROOT_DIR}/.nim_cache"
    WORKING_CACHE_DIR="/opt/nim/.cache"
    WORKING_PATH="${ROOT_DIR}"
    MOUNT_PATH="/workspace/data"
    TMP_PATH="${ROOT_DIR}/tmp"
    MOUNT_TMP_PATH="${MOUNT_PATH}/tmp"
    # --- NGC image (use # between registry and image path for Enroot) ---
    NGC_IMAGE="docker://nvcr.io#nim/mit/boltz2:1.10.0"
    CONTAINER_NAME="boltz2"
    ACTIVE_SQSH_PATH="${ROOT_DIR}/boltz2.sqsh"
    handle_error() { echo "Error: $1"; exit 1; }
    mkdir -p "$(dirname "${ACTIVE_SQSH_PATH}")" || handle_error "Failed to create directory for SQSH file"
    mkdir -p "${CACHE_PATH}" || handle_error "Failed to create cache directory"
    mkdir -p "${TMP_PATH}" || handle_error "Failed to create tmp directory"
    echo "Step 1: Requesting interactive resources..."
    srun --account="${ACCOUNT}" \
    --partition="${PARTITION}" \
    --gpus-per-node="${GPUS_PER_NODE}" \
    --mem="${MEMORY}" \
    --time="${TIME}" \
    --export=ALL \
    -o /dev/tty -e /dev/tty \
    bash -c "
    echo \"Step 2: Importing Docker image\"
    if [ ! -f \"${ACTIVE_SQSH_PATH}\" ]; then
    mkdir -p \"\$(dirname \"${ACTIVE_SQSH_PATH}\")\" || { echo \"Failed to create directory\"; exit 1; }
    enroot import -o \"${ACTIVE_SQSH_PATH}\" ${NGC_IMAGE} || { echo \"Failed to import Docker image\"; exit 1; }
    else
    echo \"Docker image already exists, skipping import.\"
    fi
    echo \"Step 3: Creating Enroot container...\"
    if enroot list 2>/dev/null | grep -q \"${CONTAINER_NAME}\"; then
    enroot remove -f ${CONTAINER_NAME} || true
    fi
    enroot create --name ${CONTAINER_NAME} \"${ACTIVE_SQSH_PATH}\" || { echo \"Failed to create container\"; exit 1; }
    NODE=\$(hostname)
    echo \"\$NODE\" > \"${WORKING_PATH}/.boltz2_node\"
    echo \"Step 4: Boltz2 container ready.\"
    echo \"=====================================\"
    echo \"Working directory in container: ${MOUNT_PATH}\"
    echo \"From another terminal run: ssh -L 8000:localhost:8000 \$NODE\"
    echo \"Node name saved to: ${WORKING_PATH}/.boltz2_node\"
    echo \"=====================================\"
    cat > \"\${TMPDIR:-/tmp}/rc.local\" << RCEOF
    #!/bin/sh
    export TMPDIR=${MOUNT_TMP_PATH}
    export TEMP=${MOUNT_TMP_PATH}
    export TMP=${MOUNT_TMP_PATH}
    export HOME=${MOUNT_PATH}
    export XDG_CACHE_HOME=${WORKING_CACHE_DIR}
    export XDG_DATA_HOME=${MOUNT_PATH}/.local/share
    mkdir -p ${MOUNT_TMP_PATH} ${MOUNT_PATH}/.local/share
    /opt/nim/start_server.sh &
    exec /bin/bash
    RCEOF
    chmod +x \"\${TMPDIR:-/tmp}/rc.local\"
    enroot start \\
    --mount ${CACHE_PATH}:${WORKING_CACHE_DIR} \\
    --mount ${WORKING_PATH}:${MOUNT_PATH} \\
    --mount \"\${TMPDIR:-/tmp}/rc.local:/etc/rc.local\" \\
    -e NGC_API_KEY \\
    -e TMPDIR=${MOUNT_TMP_PATH} \\
    -e TEMP=${MOUNT_TMP_PATH} \\
    -e TMP=${MOUNT_TMP_PATH} \\
    -e HOME=${MOUNT_PATH} \\
    -e XDG_CACHE_HOME=${WORKING_CACHE_DIR} \\
    -e XDG_DATA_HOME=${MOUNT_PATH}/.local/share \\
    ${CONTAINER_NAME} || { echo \"Failed to start container\"; exit 1; }
    "
  4. Create an SSH tunnel from your machine or the login node, after the container is running on a compute node:

    ssh -L 8000:localhost:8000 $(cat /path/to/your/workspace/.boltz2_node)
  5. Send an inference request.

    In another terminal, with the tunnel open, run the following command:

    curl -s -X POST "http://localhost:8000/biology/mit/boltz2/predict" \
    -H "Content-Type: application/json" \
    -d '{"polymers":[{"id":"A","molecule_type":"protein","sequence":"MTEYKLVVVGACGVGKSALTIQLIQNHFVDEYDPTIEDSYRKQVVID"}]}' \
    --max-time 300

    If the request succeeds, you will get a JSON response containing the prediction result.

Next Steps

When you are ready, continue with the following:

  • Refer to Inferencing with the NIM for the full API reference and usage examples.
  • Refer to Optimization for settings related to optimizing performance of the NIM on your hardware and software stack.