# Self-hosted licensing

> How a self-hosted MergeHarbor license works, how to install and renew it, and what happens at expiry. Keys are verified offline.

A self-hosted installation needs a license key from MergeHarbor. The key is a signed file (`.lic`) that the installation checks **offline**, against public keys built into the release. MergeHarbor is never contacted, so the check works in air-gapped networks.

Without a valid key, **reviews are paused**. Everything else works: you can sign in, connect code hosts and identity providers, and configure organizations before the key arrives.

## What a license contains

| Term             | Meaning                                                                                |
| ---------------- | -------------------------------------------------------------------------------------- |
| Customer         | Your company and a contact, as recorded by MergeHarbor                                 |
| Plan             | Team, Advanced or Enterprise. The features are the same as the same plan in the cloud. |
| Add-on features  | Extra features beyond the plan, for example single sign-on or SCIM on Team             |
| Seats            | Active developers per calendar month across the whole installation (or unlimited)      |
| Quality modes    | Which review cost modes organizations may choose                                       |
| Term             | Start and expiry dates, with a grace period (14 days unless agreed otherwise)          |
| Instance binding | Optional. The key works only on one installation.                                      |

An **active developer** is a person whose pull request got a review that month. Each person counts once, however many organizations they are reviewed in. Bots never count. When the seat limit is reached, pull requests from developers not yet counted that month wait until the next month, and the review says why.

## Evaluation licenses

To try MergeHarbor on your own infrastructure, [ask for an evaluation license](https://mergeharbor.com/contact?source=self-hosting). It works like a paid license but runs for at most 45 days and has no grace period: reviews pause when it ends. Installing a paid key resumes them within a minute.

## Install a key

1. Save the `.lic` file on the machine or in the cluster.
2. Point MergeHarbor at it:
   - **Docker Compose:** copy it to `license/mergeharbor.lic` in the install directory.
   - **Helm:** create a Secret from it, then set `license.existingSecret`:

     ```sh
     kubectl create secret generic mergeharbor-license --from-file=license.lic=./mergeharbor.lic
     ```

   - **Any other setup:** set `LICENSE_FILE` to the file's path on the `api` and `worker` containers. You can also set `LICENSE_KEY` to the key text.
3. Open **Settings → System status** in the console as an instance administrator. It shows the license state, plan, seats used this month and the expiry date.

To check a key before installing it, run `mergeharbor license check mergeharbor.lic` in the `mergeharbor` image. Add `-instance <id>` to check a key bound to one installation.

## Renew

MergeHarbor sends a renewed `.lic` file before the current one expires. Replace the file (or the Secret's content): the installation picks it up within a minute, without a restart.

To bind a key to one installation, send MergeHarbor the **instance id** from Settings → System status. A bound key does not work if it is copied to another installation.

## Expiry and warnings

| State                               | Reviews | What instance administrators see           |
| ----------------------------------- | ------- | ------------------------------------------ |
| Valid                               | Run     | Nothing                                    |
| Expires within 30 days              | Run     | An amber banner on every page              |
| Expired, in the grace period        | Run     | A red banner with the days left            |
| Grace period over, or not yet valid | Paused  | A red banner, and each review explains why |
| No key, or the key is not valid     | Paused  | A red banner with the reason               |

When reviews pause, nothing is deleted. History, settings and exports keep working, and installing a valid key resumes reviews within a minute.