> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/ai-workbench/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/ai-workbench/_mcp/server.

# Custom Certificate Support

This document provides detailed instructions for using custom certificate support in AI Workbench.

## Overview of Custom Certificates

You can use custom Certificate Authority (CA) certificates for host verification of services, registries, and package repositories.

This is automatically handled on a *host-by-host* basis in the following ways:

- **Automatic:** Detect and use the host's certificate store.
- **Automatic:** Configure Docker or Podman to trust certificates from the host's store.
- **Optional:** Add certificates to project containers during build and at runtime.
- **Optional:** Configure `pip` and other package managers to trust the custom certificates.

### Automatic Detection

AI Workbench automatically detects and uses the host certificate store.

The following *standard* locations are automatically added to the container runtime's trusted certs.

- **Linux**: */etc/ssl/certs*
- **macOS**: System Keychain
- **Windows**: Windows Certificate Store

### General Limitations

There are some limitations to the automatic detection and use of the host certificate store. These are:

- **Only** the standard host certificate store will be added.
- Certificate store changes may require restarting the Workbench service and containers.
- Docker Desktop requires restarting **both** the Workbench service and Docker Desktop.
- Certificate errors are **not** handled separately but do appear in the Workbench service logs.
- Workbench **doesn't** add certs to project containers by default, but you can set an option for this.

## Container Cert Configuration (optional)

You must set a configuration option to add certificates to project containers. To do this, follow these steps:

1. You set a configuration option on a "host-by-host" basis, i.e. "location-by-location" basis.
2. This is done with the `service.project_custom_ca_enabled` field in the *config.yaml* file.
3. This will add the host certificate store to **every** project container built or run on that host.
4. This adds **all** of the certificates in the store to the container.
5. This will trigger rebuild notifications for **all** containers on the host when the store changes.

### Setting the Container Option

The Desktop App lacks options to re-configure the Workbench service.

However, you can do this manually by editing a configuration file on the host. Here are some methods for doing this:

- You need to edit the *config.yaml* file on the host.

- Depending on how Workbench was installed, that file is in the following location:

  - **Ubuntu**: */home/workbench/.nvwb/config.yaml*
  - **macOS**: */Users/workbench/.nvwb/config.yaml*
  - **Windows** (in the WSL distro *NVIDIA-Workbench*): */home/workbench/.nvwb/config.yaml*

- Open *config.yaml* in a file editor and set the `project_custom_ca_enabled` field to `true`:

  ```yaml
  # Example config.yaml file
  # This is a sample file. Your file may be different.
  # The field may not be present in your file, so you may have to add it.

  service:
    project_custom_ca_enabled: true

  # This field enables custom CA certs in project containers.
  # It adds the host certificate store to containers.
  # Any changes to the store will trigger rebuilds.
  ```

- Fully shutdown and restart Workbench on the host.

## FAQs

For frequently asked questions about custom certificate support, see [Custom Certificate Support](/ai-workbench/reference/faq#custom-certificate-support).