Activate Your License

A new installation gets 3 days of full access with no license, counted from the moment it first started. If you have not installed KoolBox yet, start with Install KoolBox.

During those 3 days a dark amber banner with an orange warning triangle sits across the top of the content area on every page — checked on all of them — alongside a Grace Period badge at the top right:

License not activated — 3 days remaining in grace period
Activate your license before the grace period expires to maintain uninterrupted access.
[Activate now]

One feature is held back during the grace period: the Kai assistant is unavailable until a license is active, and it really is absent rather than merely inert — there is no sidebar entry and no mention of it anywhere in the interface.

Go to Administration → License in the sidebar to activate. There are two ways to do it: online if your server can reach the internet, or offline if it cannot.

Use this if your server can reach the internet.

1. 1
   In the sidebar, open Administration → License.
2. 2
   Select the Online Activation tab.
3. 3
   Paste the activation code from your purchase confirmation email into the box. Codes look like KBOX-XXXX-XXXX-XXXX.
4. 4
   Click Activate.

Your machine fingerprint is sent to Koolify's activation service, which returns a license bound to this specific installation.

The License Details card lists, in this order:

Beside it sits an Enabled Modules card, with one pill per module your plan includes — private AI chat, RAG, document analysis, OCR, workflow automation and so on. The set differs from plan to plan, so treat this card as the authoritative statement of what your own key unlocks.

Every value on both cards comes from the key Koolify issued you, which is the quickest way to confirm you were given what you bought.

If it fails, the message tells you which of these it was:

Use this when your server has no internet access. It is a simple two-file exchange, and once done, the installation never contacts any server again.

1. 1

   Download your machine fingerprint. On the Administration → License page, the Machine Fingerprint card is at the top. Click Download fingerprint file. Your browser saves a small file named like koolbox-fingerprint-1791953435543.json.

2. 2

   Send that file to Koolify through your approved channel. It is a small text file. You can open it and read it first; it contains only your installation's own identifier and basic host characteristics.

3. 3

   Koolify sends back a signed license file (.lic), generated specifically for this machine.

4. 4

   Upload it. On the same page, choose the Offline Activation tab and either drag the file onto the dashed box or click it to browse. The box reads “Drop license file here or click to browse — accepts .json or .lic files signed by Koolify”, and that is exactly what it accepts.

If it fails:

Your license is tied to this installation so it cannot be copied elsewhere. The fingerprint looks like this:

KB-A1B2-C3D4-E5F6-7890-ABCD

It is a one-way cryptographic hash of an identifier created once for this installation, combined with seven host characteristics: hostname, operating system and kernel release, CPU model and core count, memory size, and the first network adapter's address. All seven are listed on screen as small chips, so you can see exactly what goes into it, and they appear in the file you download — which is the whole of it, about half a kilobyte:

{
  "version": "1.0",
  "generatedAt": "2026-10-14T04:50:35.870Z",
  "machineFingerprint": "KB-7B6F-9ECF-1EB9-2F58-7FAD",
  "installId": "70594920-6637-407a-b368-dc034a36d625",
  "components": {
    "hostname": "your-server",
    "platform": "Linux",
    "release": "7.0.0-1014-aws",
    "cpuModel": "Intel(R) Xeon(R) Platinum 8259CL CPU @ 2.50GHz",
    "cpuCores": "2",
    "totalMemoryGb": "8",
    "primaryMac": "0e:ff:c3:c9:3b:53"
  },
  "platform": {
    "product": "KoolBox Private AI Platform",
    "consoleVersion": "1.0.0"
  }
}

No documents, user data, prompts or business information are involved — that is the entire file, and you can read it before you send it. The consoleVersion line describes the file format, not your installed release, so do not be concerned that it reads 1.0.0 on a 1.2.8 server. Because the installation's own identifier is part of the hash, the fingerprint survives routine hardware changes.

This differs between the two license types, and the difference matters.