Quickstart Guide

Complete the Prerequisites before you start.

For custom or alternative models, refer to Custom Models. For advanced request workflows, refer to Examples.

Pull the NIM Container

Run the following command to pull the container:

docker pull nvcr.io/nim/nvidia/alchemi-bgr:1.1.0

Run the NIM Container

Default model: The default configuration downloads the MACE-MPA-0 medium checkpoint from Hugging Face when the container starts. No manual model download or mount is required for the default use case.

Run the following command to start the NIM container and expose port 8000 for interaction:

export NGC_API_KEY=<Your NGC API Key>

docker run --rm -ti --name alchemi-bgr --gpus=all \
    -e NGC_API_KEY \
    -p 8000:8000 \
    --shm-size=8g \
    nvcr.io/nim/nvidia/alchemi-bgr:1.1.0

The output should display messages similar to the following:

INFO     | BGR:cuda:0 |  Starting BGR engine worker on cuda:0
INFO     | BGR:cuda:1 |  Starting BGR engine worker on cuda:1

At this point, the server might perform automatic batch size estimation (unless you set ALCHEMI_NIM_BATCH_SIZE), which produces output similar to the following:

INFO     | BGR:cuda:0 |  Starting BGR engine worker on cuda:0
INFO     | BGR:cuda:0 |  Atom count 192 took 12.90 ms, 67.17 μs/atom (3 runs)
INFO     | BGR:cuda:0 |  Atom count 504 took 14.06 ms, 27.89 μs/atom (3 runs)
...
INFO     | BGR:cuda:0 |  Estimated batch size: 4104, max: 38956
INFO     | BGR:cuda:0 |  Backend cuda:0 ready for inference
INFO     | BGR:cuda:0 |  Backend cuda:0 is ready (took 88.68s)
INFO     | BGR:cuda:0 |  Status server started on ipc:///tmp/nim_status_cuda_0.ipc
INFO     | BGR:cuda:0 |  Initialization complete on cuda:0

After initialization is complete, the Triton server starts and is ready when the following logging statements appear:

INFO 2026-03-03 17:40:33.087 nimutils.py:79] I0303 17:40:33.087241 106 http_server.cc:4809] "Started HTTPService at 0.0.0.0:8000"
INFO 2026-03-03 17:40:33.130 nimutils.py:79] I0303 17:40:33.130584 106 http_server.cc:358] "Started Metrics Service at 0.0.0.0:8002"

Check the Health of the NIM

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

In the new terminal, run the following command to query the health check:

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

Wait until the health check endpoint returns HTTP 200 with "status":"ready" before you proceed. The successful response also includes backends_alive and backends_total. During startup or a health failure, a 503 response might contain only a status message. This can take a couple of minutes while the NIM estimates optimal batch sizes for the GPU.

To check the NIM’s status using Python, use the requests module:

import requests
url = "http://localhost:8000/v1/health/ready"
headers = {
    "content-type": "application/json"
}
try:
    response = requests.get(url, headers=headers)
    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)

Basic Inference Request

For the request format and required atomic data fields, refer to API Reference.

Install the Python library used in the code sample:

pip install requests

The following code sample demonstrates a simple inference request with a hydrogen molecule in a periodic cell:

import requests
server_url = "http://localhost:8000"
# Simple H2 molecule in a periodic box
package = {
    'atoms': [{
        'coord': [0.0, 0.0, 0.0, 0.0, 0.0, 1.0],
        'numbers': [1, 1],
        'cell': [10, 0, 0, 0, 10, 0, 0, 0, 10],
    }],
}
result = requests.post(f"{server_url}/v1/infer", json=package)
result.raise_for_status()
print(result.json())

Configuration Options

For the complete configuration reference and all environment variables, refer to Configuration and Environment Variables.

Stop the NIM Container

Run the following command to stop the running NIM container:

docker stop alchemi-bgr