> This page is for version 1.0.0 (Latest) (default).
> For other versions, use one of these documentation indexes:
> - 1.0.0 (Latest) (default): https://docs.nvidia.com/nim/harmonizer/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/harmonizer/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nim/harmonizer/_mcp/server.

# Deploy a Custom Harmonizer Checkpoint

> Deploy a compatible Harmonizer checkpoint with Docker or Helm and verify that the custom model serves inference.

Use Bring Your Own Checkpoint (BYOC) to deploy a fine-tuned Harmonizer checkpoint instead of the release-approved default.

## Prerequisites

The checkpoint must be a Harmonizer source `.pkl` artifact compatible with the
packaged runtime. These are `torch.save` state-dict files (containing
`state_dict_unet` and `state_dict_vae`) for the same `Pix2Pix_Turbo` /
Harmonizer model architecture as the default checkpoint, served in bfloat16
(BF16) precision.

Single-file training deltas and adapter-only artifacts are not supported until
they are merged into a full Harmonizer checkpoint.

For Docker, complete the registry login and environment setup in
[Quickstart for Harmonizer NIM](/nim/harmonizer/quickstart-guide). Export `IMG_NAME`, `LOCAL_NIM_CACHE`, and
`NGC_API_KEY` in the terminal where you start the container.

For Helm, prepare the chart and common values in [Deploy Harmonizer NIM with Helm](/nim/harmonizer/helm).

## Deploy the Checkpoint with Docker

Complete these steps to mount a local checkpoint read-only and start the NIM:

1. Prepare the checkpoint directory and verify its default file name.

   Mount the checkpoint directory and point `NIM_FT_CHECKPOINT` at it. The runtime
   loads `diffusion_harmonizer.pkl` from the BYOC root by default:

   ```bash
   export HARMONIZER_BYOC_PATH=/path/to/harmonizer-checkpoint
   test -f "$HARMONIZER_BYOC_PATH/diffusion_harmonizer.pkl"
   chmod -R a+rX "$HARMONIZER_BYOC_PATH"
   ```

2. Optional: Set a different checkpoint file path in the Docker command.

   With BYOC set, the mounted checkpoint defaults to
   `/byoc/diffusion_harmonizer.pkl`. If the file has a different name or location,
   set `HARMONIZER_PKL_MODEL_PATH` to its full in-container path. Add the variable
   before the image name in the Docker command:

   ```bash
   -e NIM_FT_CHECKPOINT=/byoc \
   -e HARMONIZER_PKL_MODEL_PATH=/byoc/my_harmonizer.pkl
   ```

   Both processing modes (non-temporal `V=1` and temporal `V=5`) use the
   single BYOC checkpoint. The runtime applies the same fixed-shape optimization
   path as the default deployment. Measure quality and performance with your
   deployed checkpoint.

3. Start the NIM with the checkpoint mounted read-only.

   The container runs as UID `1000`. Every directory inside the mounted checkpoint
   tree must be traversable and the checkpoint file must be readable by that user.
   The `a+rX` mode grants read and directory-traversal access without making the
   checkpoint writable. Keep the model mount read-only and keep the NIM cache as a
   separate writable mount.

   ```bash
   docker run -it --rm --name harmonizer-byoc \
      --runtime=nvidia \
      --gpus all \
      --shm-size=8g \
      --ulimit memlock=-1 \
      --ulimit stack=67108864 \
      -e NGC_API_KEY \
      -e NIM_FT_CHECKPOINT=/byoc \
      -v "$HARMONIZER_BYOC_PATH:/byoc:ro" \
      -v "$LOCAL_NIM_CACHE:/opt/nim/.cache" \
      -p 8000:8000 \
      $IMG_NAME
   ```

## Deploy the Checkpoint with Helm

Complete these steps to mount an existing checkpoint persistent volume claim
(PVC) and install the chart:

1. Create a checkpoint PVC and write `byoc-values.yaml`.

   Create a PVC that contains `diffusion_harmonizer.pkl` and make the claim
   available in the namespace where you install the NIM. Keep this checkpoint
   claim separate from the writable NIM cache. For example, add the following
   `byoc-values.yaml` override to the common values in
   [Deploy Harmonizer NIM with Helm](/nim/harmonizer/helm):

   ```yaml
   imagePullSecrets:
     - name: ngc-secret

   model:
     ngcAPISecret: ""
     nimCache: /model-store

   persistence:
     enabled: true
     size: 60Gi

   extraVolumes:
     harmonizer-byoc:
       persistentVolumeClaim:
         claimName: harmonizer-byoc

   extraVolumeMounts:
     harmonizer-byoc:
       mountPath: /opt/nim/byoc
       readOnly: true

   env:
     - name: NIM_FT_CHECKPOINT
       value: /opt/nim/byoc
   ```

2. Give container UID `1000` read access to the checkpoint and write access to the separate cache.

   The `harmonizer-byoc` claim must already exist and contain the checkpoint.
   The chart mounts it read-only at `/opt/nim/byoc`. Setting
   `NIM_FT_CHECKPOINT` makes the runtime use the BYOC checkpoint instead of
   downloading the release checkpoint, so `model.ngcAPISecret` can be empty.
   Keep `imagePullSecrets` configured because pulling the NIM container from a
   private NGC registry still requires registry credentials.

   Provision the checkpoint volume so UID `1000` can traverse its directories
   and read the checkpoint file. The checkpoint claim does not need to be writable.
   Configure the separate cache volume so UID `1000` can write to it.

3. Optionally set a nondefault checkpoint file path in `byoc-values.yaml`.

   The persistent volume configured by `persistence` is a separate, writable
   cache. The chart mounts that volume at `model.nimCache` and sets
   `NIM_CACHE_PATH` to the same path. The NIM can therefore retain downloaded
   dependencies and compiled artifacts without writing to the checkpoint PVC.
   Do not set `NIM_CACHE_PATH` again through `env`.

   If the checkpoint file has a different name or a nested location on the PVC,
   add its full mounted path to the same override:

   ```yaml
   env:
     - name: NIM_FT_CHECKPOINT
       value: /opt/nim/byoc
     - name: HARMONIZER_PKL_MODEL_PATH
       value: /opt/nim/byoc/my_harmonizer.pkl
   ```

4. Install the chart with the common values and BYOC override.

   Install the chart with the common values first and the BYOC override second:

   ```bash
   helm install harmonizer-nim nim-wfm-1.3.0.tgz \
      -f custom-values.yaml \
      -f byoc-values.yaml
   ```

## Verify the Deployment

For Helm deployments, forward the HTTP service port before running the checks:

```bash
kubectl port-forward service/harmonizer-nim-nim-wfm 8000:http-api
```

Keep port forwarding running in that terminal. Run the checks from a second
terminal on the same host. Docker deployments already publish port `8000`.
Ensure that a previous deployment does not occupy this port.

Check readiness, then send one image to confirm that the checkpoint produces output:

1. Check the NIM readiness endpoint after startup.

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

2. Send a sample request as shown in [Quickstart for Harmonizer NIM](/nim/harmonizer/quickstart-guide).

   A valid output image confirms that the checkpoint loaded and produces output.