> This page is for NVIDIA Relighting NIM, 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/maxine/relighting/1.2.0/llms.txt
> - 1.1.0: https://docs.nvidia.com/nim/maxine/relighting/1.1.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/maxine/llms.txt.

# Getting Started

## Prerequisites

To ensure that you have the supported hardware and software stack, check the [Support Matrix](/nim/maxine/relighting/support-matrix).

### NGC Authentication

#### Generate an API Key

An NGC API key is required to access NGC resources. You can generate a key at [https://org.ngc.nvidia.com/setup/api-keys](https://org.ngc.nvidia.com/setup/api-keys).

When creating an NGC API Personal key, ensure that at least **NGC Catalog** is selected from the **Services Included** dropdown. You can include more services if this key is to be reused for other purposes.

<Note>
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 [NGC API Keys](https://docs.nvidia.com/ngc/gpu-cloud/ngc-user-guide/index.html#ngc-api-keys) in the NGC User Guide.
</Note>

#### Export the NGC 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, the simplest way is to export it in your terminal:

```bash
export NGC_API_KEY={your_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={your_ngc_api_key}" >> ~/.bashrc

# If using zsh
echo "export NGC_API_KEY={your_ngc_api_key}" >> ~/.zshrc
```

<Note>
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/).
</Note>

#### 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
```

On success, Docker prints `Login Succeeded`.

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 user name and password.

## Launching the NIM Container

The following command launches the Relighting container with the gRPC service. (For a list of parameters, see [Runtime Parameters for the Container](#runtime-parameters-for-the-container).)

Run the NIM launch command. The NIM selects the model profile that matches your GPU (refer to [Model Manifest Profiles](#model-manifest-profiles) to pin one). The command mounts a model cache directory from the host, so later starts reuse the downloaded models:

```bash
export LOCAL_NIM_CACHE=~/.cache/nim
mkdir -p "$LOCAL_NIM_CACHE"
chmod a+rwX "$LOCAL_NIM_CACHE" 2>/dev/null || true
```

```bash
docker rm -f relighting-nim 2>/dev/null
docker run -d --name=relighting-nim \
  --runtime=nvidia \
  --gpus all \
  --shm-size=8GB \
  -e NGC_API_KEY=$NGC_API_KEY \
  -e NV_AI4M_MAX_CONCURRENCY_PER_GPU=1 \
  -e NIM_HTTP_API_PORT=8000 \
  -e NIM_GRPC_API_PORT=8001 \
  -p 8000:8000 \
  -p 8001:8001 \
  -p 9002:9002 \
  -v "$LOCAL_NIM_CACHE:/opt/nim/.cache" \
  nvcr.io/nim/nvidia/relighting:1.2.0

docker logs -f relighting-nim
```


The first start downloads the models into `LOCAL_NIM_CACHE`, and later starts reuse them. To remove the cached models, refer to [Model Caching](/nim/maxine/relighting/advanced-usage#model-caching).

If the NIM launch is successful, the log ends with lines similar to the following. Ports 9000 and 9001 are Triton's ports inside the container; the NIM serves inference on gRPC port 8001.

```text
I1015 08:32:03.733229 94 grpc_server.cc:2560] "Started GRPCInferenceService at 0.0.0.0:9001"
I1015 08:32:03.733594 94 http_server.cc:4755] "Started HTTPService at 0.0.0.0:9000"
I1015 08:32:03.775642 94 http_server.cc:358] "Started Metrics Service at 0.0.0.0:9002"
Triton server is ready
...
[INFO AI4M BASE LOGGER 2026-10-15 08:32:14.341 PID:349] Warm-up done: 3 models x 1 GPU(s), 3 frames at 1280x720 in 3.8s
[INFO AI4M BASE LOGGER 2026-10-15 08:32:14.341 PID:349] gRPC health status: SERVING (Triton connected, all models ready and warmed up)
[INFO AI4M BASE LOGGER 2026-10-15 08:32:14.346 PID:349] Using threading mode for gRPC service
[INFO AI4M BASE LOGGER 2026-10-15 08:32:14.346 PID:349] Starting threading gRPC service with 1 threads
[INFO AI4M BASE LOGGER 2026-10-15 08:32:14.362 PID:349] Using Insecure Server Credentials
[INFO AI4M BASE LOGGER 2026-10-15 08:32:14.364 PID:349] Listening to 0.0.0.0:8001
```

If the NIM fails to start, the container exits, and the last lines of the log name the error.

<Note>
By default, the Relighting gRPC service is hosted on port `8001`. You must use this port for inferencing requests. The port is configurable with the `NIM_GRPC_API_PORT` environment variable.
</Note>

### Model Manifest Profiles

The NIM selects the model profile for your GPU at startup. To list the profiles in the image you pulled, run the `list-model-profiles` utility:

```bash
docker run --rm --runtime=nvidia --gpus all \
  -e NGC_API_KEY=$NGC_API_KEY \
  nvcr.io/nim/nvidia/relighting:1.2.0 list-model-profiles
```


The output lists the profiles that are compatible with your GPU and the ones that are not, with the compute capability of each. To pin a profile, add `-e NIM_MODEL_PROFILE={profile_id}` to the launch command, with an ID that the output lists as compatible.

<Note>
With a profile ID for another GPU architecture, the NIM does not find the engines for your GPU: it logs `Model validation failed after 120s` and exits.
</Note>

## Environment Variables

The following table describes the environment variables that can be passed into a NIM as a `-e` argument added to a `docker run` command:

| ENV                           | Required? | Default           | Notes                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ----------------------------- | --------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NGC_API_KEY`                 | Yes       | None              | You must set this variable to the value of your personal NGC API key.                                                                                                                                                                                                                                                                                                                                                               |
| `NIM_CACHE_PATH`              | No        | `/opt/nim/.cache` | Location (in container) where the container caches model artifacts.                                                                                                                                                                                                                                                                                                                                                                 |
| `NIM_HTTP_API_PORT`           | No        | `8000`            | HTTP API port inside the container. Serves the following endpoints: `/v1/health/live` (liveness probe), `/v1/health/ready` (readiness probe), `/v1/license` (license information), `/v1/metadata` (asset, license, model, and version metadata), `/v1/manifest` (model manifest), and `/v1/metrics` (Prometheus metrics). Adjust the `-p`/`--publish` flag of `docker run` accordingly (for example, `-p 8000:$NIM_HTTP_API_PORT`). |
| `NIM_GRPC_API_PORT`           | No        | `8001`            | gRPC API port inside the container. Hosts the `VideoRelightingService.Relight` bidirectional streaming RPC and the `grpc.health.v1.Health/Check` health service. Adjust the `-p`/`--publish` flag of `docker run` accordingly (for example, `-p 8001:$NIM_GRPC_API_PORT`).                                                                                                                                                          |
| `NIM_MODEL_PROFILE`           | No        | None              | Set this model profile to download the specific model type supported on your GPU. If it is not set, the NIM selects a matching profile automatically. The earlier name `NIM_MANIFEST_PROFILE` is still honored as a fallback when this variable is unset. For more about `NIM_MODEL_PROFILE`, refer to [Model Manifest Profiles](#model-manifest-profiles).                                                                                                                                                                                                                          |
| `NIM_SSL_MODE`                | No        | `disabled`        | Secure the gRPC port (8001) with `tls` or `mtls`. The HTTP port (8000) stays plaintext.                                                                                                                                                                                                                                                                                                                                             |
| `NIM_SSL_CA_CERTS_PATH`       | No        | `/opt/nim/crt/ssl_ca_cert.pem` with `mtls`; none with `tls`| Path to the CA root certificate inside the NIM. With `mtls`, the NIM verifies client certificates against it. With `tls` and a certificate from a private CA, set it so that the NIM's own readiness check trusts the certificate.                                                                                                                                                                                                                                                                                                                                 |
| `NIM_SSL_CERT_PATH`           | No        | `/opt/nim/crt/ssl_cert_server.pem`| Path to the server's public SSL certificate inside the NIM. Used only when an SSL mode is enabled.                                                                                                                                                                                                                                                                                                                                  |
| `NIM_SSL_KEY_PATH`            | No        | `/opt/nim/crt/ssl_key_server.pem`| Path to the server's private key inside the NIM. Used only when an SSL mode is enabled.                                                                                                                                                                                                                                                                                                                                             |
| `NV_AI4M_MAX_CONCURRENCY_PER_GPU` | No        | `1`               | Maximum concurrent inference requests per GPU.                                                                                                                                                                                                                                                                                                                                                                                      |

## Runtime Parameters for the Container

| Flags                             | Description                                                                                                                                                                                                                                                                                                                                                     |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-d`                              | Run the container in the background.                                                                                                                                                                                                                                                                                                                            |
| `--name=container-name`           | Give a name to the NIM container. The commands in this documentation use `relighting-nim`; if you choose another name, use it in those commands too.                                                                                                                                                                                                                                                                                                      |
| `--runtime=nvidia`                | Ensure NVIDIA drivers are accessible in the container.                                                                                                                                                                                                                                                                                                          |
| `--gpus all`                      | Expose NVIDIA GPUs inside the container. On a host with multiple GPUs, you can expose specific GPUs instead. For more information about mounting specific GPUs, refer to [GPU Enumeration](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/docker-specialized.html#gpu-enumeration). |
| `--shm-size=8GB`                  | Allocate host memory for multi-process communication.                                                                                                                                                                                                                                                                                                           |
| `-v $LOCAL_NIM_CACHE:/opt/nim/.cache`| Mount a host directory as the model cache so that the model download persists across runs.                                                                                                                                                                                                                                                                      |
| `-e NV_AI4M_MAX_CONCURRENCY_PER_GPU`  | Number of concurrent inference requests to be supported by the NIM server per GPU.                                                                                                                                                                                                                                                                              |
| `-e NGC_API_KEY=$NGC_API_KEY`     | Provide the container with the token necessary to download adequate models and resources from NGC. See [NGC Authentication](#ngc-authentication).                                                                                                                                                                                                               |
| `-p <host_port>:<container_port>` | Ports published by the container are directly accessible on the host port.                                                                                                                                                                                                                                                                                      |

## Stopping the Container

The launch commands on this page do not use `--rm`, so stop the container and then
remove it:

```bash
docker stop relighting-nim
docker rm relighting-nim
```