> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trusting the local HTTPS certificate for Flows custom apps

> Step-by-step guide to installing a trusted local certificate so your Flows custom app loads without warnings in Cognite Data Fusion (CDF).

This guide is for developers building Flows custom apps. Before you begin, make sure you have a Flows custom app created and dependencies installed. See [Getting started with Flows custom apps](/cdf/flows/guides/getting-started).

`npm run dev` serves your app over HTTPS so CDF can embed it in an iframe. Without a trusted certificate, the browser blocks the embed and shows **Not Secure** or **"the webpage at `https://localhost:3001/` might be having issues"**. You need to establish trust between your browser and the local dev server before CDF can load your app.

You can establish trust in two ways:

* **[Install `mkcert`](#installing-mkcert-recommended)**: One-time setup that works everywhere. Requires admin access.
* **[Accept the certificate in the browser](#accepting-the-certificate-manually-no-admin-required)**: No installation needed, but you must repeat this on every dev server restart.

## Installing mkcert (recommended)

<Steps>
  <Step title="Install the mkcert binary">
    <Tabs>
      <Tab title="macOS / Linux">
        Run the following command in your terminal:

        ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        brew install mkcert
        ```
      </Tab>

      <Tab title="Windows (Chocolatey)">
        1. Open the **Start** menu, type **Windows PowerShell**.
        2. Right-click **Windows PowerShell** and select **Run as administrator**.
        3. Accept the UAC prompt.
        4. Run the following command:

        ```powershell theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        choco install mkcert
        ```
      </Tab>

      <Tab title="Windows (Scoop)">
        Run the following command in your terminal:

        ```powershell theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        scoop bucket add extras
        scoop install mkcert
        ```
      </Tab>
    </Tabs>

    <Tip>If you don't have a package manager, download the binary directly from the [mkcert installation guide](https://github.com/FiloSottile/mkcert#installation).</Tip>
  </Step>

  <Step title="Run setup-https">
    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    npx @cognite/cli@latest apps setup-https
    ```

    This command adds the `mkcert` **Certificate Authority (CA)** to your system trust store and issues a certificate for `localhost`, `local.cognite.ai`, and `*.local.cognite.ai`.
    <Note>You must accept the sudo or UAC prompt when it appears.</Note>
  </Step>

  <Step title="Restart the dev server and browser">
    Stop `npm run dev`, restart it, then fully quit and reopen your browser so it re-reads the trust store. The address bar should show the lock icon.
  </Step>
</Steps>

## Accepting the certificate manually (no admin required)

If you don't have admin access, manually trust the dev server's self-signed certificate in your browser:

<Steps>
  <Step title="Start the dev server">
    Run the following command in your terminal:

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    npm run dev
    ```

    The URL is displayed in the terminal (for example, `https://localhost:3001`).
  </Step>

  <Step title="Open the localhost URL in a new tab">
    Open a new tab in your browser and paste the URL. The browser shows a privacy warning:

    <Tabs>
      <Tab title="Chrome / Edge">
        Select **Advanced** → **Proceed to localhost (unsafe)**.
      </Tab>

      <Tab title="Firefox">
        Select **Advanced…** → **Accept the Risk and Continue**.
      </Tab>

      <Tab title="Safari">
        Select **Show Details** → **visit this website** → **Visit Website**.
      </Tab>
    </Tabs>

    The new tab will appear blank or show a "The webpage at `https://localhost:3001` might be having issues" message as the app only renders within the CDF iframe, not in a standalone window. You can close this tab.
  </Step>

  <Step title="Reload CDF">
    Return to the **CDF** tab and reload. If the iframe doesn't load immediately, reload again and wait a few seconds for the now-trusted session to register.
  </Step>
</Steps>

<Warning>
  Install `mkcert` to avoid repeating this step.Without `mkcert`, the dev server generates a new certificate on every start, so the browser warning returns on every restart, port change (for example, `3002` instead of `3001`), or browser switch.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="`apps setup-https` says 'mkcert is not installed'">
    **Symptom**:

    * Running `npx @cognite/cli@latest apps setup-https` fails with `mkcert is not installed`.

    **Cause**:

    * The CLI cannot find `mkcert` on your `PATH`.

    **Resolution**:

    * Install `mkcert` (see [Installing mkcert (recommended)](#installing-mkcert-recommended)), then run the command again.
    * On Windows, run `choco install mkcert` from an elevated PowerShell.
  </Accordion>

  <Accordion title="Browser still shows Not Secure after setup">
    **Symptom**:

    * The browser shows **Not Secure** even after `apps setup-https` completed successfully.

    **Cause**:

    * The browser cached the old trust store state and hasn't re-read it yet.

    **Resolution**:

    * Fully quit and reopen the browser.
    * On Windows, close Edge from the system tray, not just the window.
  </Accordion>

  <Accordion title="`apps setup-https` not found">
    **Symptom**:

    * The CLI reports that the `apps setup-https` command doesn't exist.

    **Cause**:

    * Your local version of `@cognite/cli` is older than `1.4.0`, which is when the command was added.

    **Resolution**:

    * Run the command with `@latest` to bypass any pinned version:

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    npx @cognite/cli@latest apps setup-https
    ```

    * If `@latest` still resolves to a version older than `1.4.0`, delete any `.npmrc` in the current directory that pins a registry or version.
  </Accordion>

  <Accordion title="The port keeps incrementing (3001 → 3002 → 3003 …)">
    **Symptom**:

    * Each `npm run dev` start uses a higher port number.

    **Cause**:

    * An orphaned `node` process from a previous session is still holding the port.

    **Resolution**:

    * Find and stop the process. You can only stop processes you own.

    ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    # macOS / Linux
    lsof -i :3001 # Checks what's running on port 3001
    kill -9 <PID> # Stops the process
    ```

    ```powershell theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    # Windows
    Get-Process -Id (Get-NetTCPConnection -LocalPort 3001).OwningProcess
    Stop-Process -Id <PID> -Force
    ```
  </Accordion>
</AccordionGroup>

## Further reading

* [Running Flows custom apps locally](/cdf/flows/guides/running-locally)
* [Sign Flows custom apps from the CLI](/cdf/flows/guides/code-signing)