> This page is for ProteinMPNN, version 1.2.0 (Latest) (default).
> For other versions, use one of these documentation indexes:
> - 1.2.0 (Latest) (default): https://docs.nvidia.com/nim/bionemo/proteinmpnn/1.2.0/llms.txt
> - 1.1.0: https://docs.nvidia.com/nim/bionemo/proteinmpnn/1.1.0/llms.txt
> - 1.0.2: https://docs.nvidia.com/nim/bionemo/proteinmpnn/1.0.2/llms.txt
> - 1.0.0: https://docs.nvidia.com/nim/bionemo/proteinmpnn/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.

# Quickstart Guide

## Start NIM

<Note>
This page assumes you have completed the [Prerequisites](/nim/bionemo/proteinmpnn/prerequisites) (client software, NGC account and API key, Docker login to the NGC registry, and accepted license terms).
</Note>

1. Export `NGC_API_KEY` variable.

   ```bash
   export NGC_API_KEY=<your personal NGC key>
   ```

   <Warning>
   Only **Personal API Keys** or **Service API Keys** are supported. Legacy API keys are not supported and will result in a failed `docker pull`.
   </Warning>

2. The NIM container automatically downloads models. To save time and bandwidth,
   provide a local cache directory. This way the NIM can reuse already downloaded
   models. Run the following commands to set up the cache directory.

   ```bash
   export LOCAL_NIM_CACHE=~/.cache/nim
   mkdir -p "$LOCAL_NIM_CACHE"
   sudo chmod 0777 -R "$LOCAL_NIM_CACHE"
   ```

3. Run the NIM container with the following commands.

   <Warning>
   If you have not already, visit the [ProteinMPNN NGC page](https://catalog.ngc.nvidia.com/orgs/nim/teams/ipd/containers/proteinmpnn) and click **Accept Terms** under the Governing Terms section before pulling the container. See [Prerequisites](/nim/bionemo/proteinmpnn/prerequisites#accept-license-terms) for details.
   </Warning>

   ```bash
   docker run -it \
       --runtime=nvidia \
       --gpus='"device=0"' \
       -p 8000:8000 \
       -e NGC_API_KEY \
       -v "$LOCAL_NIM_CACHE":/home/nvs/.cache/nim \
       nvcr.io/nim/ipd/proteinmpnn:latest
   ```

   This command starts the NIM container and exposes port 8000 for the user to interact with the NIM.

4. Open a new terminal, leaving the terminal that runs the service open. In the new terminal, wait until the health check endpoint returns `{"status":"ready"}` before proceeding. This can take a couple of minutes. You can use the following command to query the health check.

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

## Run the Python Client Example

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

   ```python
   #!/usr/bin/env python3
   import requests
   import json
   from pathlib import Path

   def get_reduced_pdb():
       pdb = Path("1R42.pdb")
       if not pdb.exists():
           pdb.write_text(requests.get(f"https://files.rcsb.org/download/{pdb}").text)
       lines = filter(lambda line: line.startswith("ATOM"), pdb.read_text().split("\n"))
       return "\n".join(list(lines)[:200])

   r = requests.post(
       url="http://localhost:8000/biology/ipd/proteinmpnn/predict",
       json={
           "input_pdb": get_reduced_pdb(),
           "ca_only": False,
           "use_soluble_model": False,
           "sampling_temp": [0.1],
       },
   )
   r.raise_for_status()
   print(r, "Saving to output.fa:\n", r.text[:200], "...")
   Path("output.fa").write_text(json.loads(r.text)["mfasta"])
   ```

2. Run the example.

   ```bash
   chmod +x nim_client.py

   ./nim_client.py
   ```

3. The NIM saves results to the `output.fa` file in Multi-FASTA format. You can view the file using the following command.

   ```bash
   cat output.fa
   ```

## Run the Shell Client Example

1. Save the following Shell example to a file named `nim_client.sh`.

   ```bash
   #!/usr/bin/env bash
   set -e

   URL=http://localhost:8000/biology/ipd/proteinmpnn/predict

   if [ ! -e 1R42.pdb ]; then curl -O https://files.rcsb.org/download/1R42.pdb; fi

   pdb=$(cat 1R42.pdb | grep ^ATOM | head -n 200 | awk '{printf "%s\\n", $0}')

   request='{
    "input_pdb": "'"$pdb"'",
    "ca_only": false,
    "use_soluble_model": false,
    "sampling_temp": [0.1]
   }'
   curl -H 'Content-Type: application/json' \
        -d "$request" "$URL"
   ```

2. Run the example.

   ```bash
   chmod +x nim_client.sh

   ./nim_client.sh
   ```

3. The NIM displays the results to the terminal in JSON format. You can configure the NIM to display the results, scores, and probabilities in the Multi-FASTA output format.

## Stop the Container

When you are done, press `Ctrl+C` in the terminal running the container. Because the `docker run` command does not use `--rm`, Docker keeps the stopped container. Run `docker ps -a` to find it and `docker rm` with its container ID to remove it.