Use a License Key

A license key licenses an online server: the server exchanges the key for a lease on first boot and refreshes it hourly. This page covers everything about running with a key. If your server cannot reach the internet at all, see Air-gapped installations instead.

Pass the key to the server

The key is read from one environment variable, KUBEMQ_LICENSE_KEY, in every deployment mode. Replace YOUR_LICENSE_KEY with your key.

docker run -d \  --name kubemq \  -p 50000:50000 \  -p 9090:9090 \  -p 8080:8080 \  -p 9092:9092 \  -p 5672:5672 \  -e KUBEMQ_LICENSE_KEY=YOUR_LICENSE_KEY \  --hostname kubemq \  -v "$(pwd)/kubemq-store:/kubemq/store" \  europe-docker.pkg.dev/kubemq/images/kubemq-next:latest

services:
  kubemq:
    image: europe-docker.pkg.dev/kubemq/images/kubemq-next:latest
    container_name: kubemq
    hostname: kubemq
    ports:
      - "50000:50000"
      - "9090:9090"
      - "8080:8080"
    environment:
      - KUBEMQ_LICENSE_KEY=${KUBEMQ_LICENSE_KEY:?set KUBEMQ_LICENSE_KEY in your shell}
    volumes:
      - kubemq-data:/kubemq/store
    restart: unless-stopped

volumes:
  kubemq-data:

export KUBEMQ_LICENSE_KEY=YOUR_LICENSE_KEY
docker compose up -d

kubectl create namespace kubemq
kubectl create secret generic kubemq-license -n kubemq \
  --from-literal=key=YOUR_LICENSE_KEY

helm repo add kubemq-next https://kubemq-io.github.io/charts-next
helm install kubemq-next kubemq-next/kubemq-next -n kubemq \
  --set licenseKeySecretRef.name=kubemq-license \
  --set licenseKeySecretRef.key=key \
  --set replicas=1 --set standalone=true \
  --set volume.size=5Gi

apiVersion: v1
kind: Secret
metadata:
  name: kubemq-license
  namespace: kubemq
stringData:
  key: YOUR_LICENSE_KEY

spec:
  template:
    spec:
      serviceAccountName: kubemq-cluster-next
      containers:
        - name: kubemq
          image: europe-docker.pkg.dev/kubemq/images/kubemq-next:latest
          env:
            - name: KUBEMQ_LICENSE_KEY
              valueFrom:
                secretKeyRef:
                  name: kubemq-license
                  key: key
          volumeMounts:
            - name: store
              mountPath: /kubemq/store
  volumeClaimTemplates:
    - metadata:
        name: store
      spec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 20Gi

Activation

On the first boot of an installation the server has no cached lease, so it activates: it sends the key, its installation fingerprint and a description of where it runs (standalone, docker or kubernetes, plus the server version and, when KUBEMQ_IMAGE_DIGEST is injected, the image digest — operator 1.1.1 and later inject NODE_NAME on every pod and KUBEMQ_IMAGE_DIGEST when the cluster's image reference is pinned by digest, …@sha256:…; a tag-only image reference leaves the digest empty) to https://license.kubemq.io. The service answers with a signed lease — a 7-day token bound to this fingerprint (24 hours for a trial) — which the server caches and verifies from then on. The key itself is not stored by the server.

If activation fails:

• Bad key (401, three refusals 30 seconds apart) — the server refuses to start. There is one error for an unknown key, a disabled license, a revoked one and an expired one; the log line ends in #first-boot-bad-key.
• Bad request (400, three times) — the service could not parse the activation request itself; the server refuses to start with #first-boot-bad-request. This is a version mismatch between the server build and the service, not a key problem.
• Untrusted signing key (422 untrusted_kid) — the service signs with a key this server build does not trust; the server refuses to start immediately with #untrusted-kid. Upgrade the server.
• Service unreachable (DNS, timeout, 5xx) or any other answer (429, an unexpected status) — the server retries with backoff (1, 2, 5, 15, then 30 minutes, ±10%), honouring a Retry-After header up to a cap of 30 minutes, for KUBEMQ_LICENSE_FIRST_BOOT_RETRY_MINUTES (default 30 minutes), then refuses to start with #first-boot-unreachable, which points at the pre-activated file path. A 429 rate_limited here is expected on a multi-node first boot: the pods of one installation activate in parallel and share a per-license activate rate limit, so some of them log first boot: activate answered HTTP 429 rate_limited; retrying in …s #first-boot-unreachable and wait 1–2 minutes before succeeding. That is not a fault and needs no action — the server is not unreachable, only rate-limited, and the same #first-boot-unreachable anchor covers both cases.

After activation, the server refreshes hourly and activates again only when the cached lease can no longer be used: it is past its expiry plus grace, or it is bound to another installation's fingerprint (a store volume copied from another host). In both cases the server logs a warning and activates with the key instead of refusing.

The lease cache

The server keeps four small files under its store directory:

The default store path inside the container is /kubemq/store.

Regenerate a key

A key can be regenerated — after a leak, a staff change, or simply because it was lost. Regeneration issues a new key and invalidates the old one for new activations. Running servers are unaffected: they hold a lease and refresh with it, never with the key. Update the value wherever you store it (Secret, .env, CI variable) so that the next new installation activates with the new key.

Trial keys are regenerated through the resend option on kubemq.io/trial; paid keys through your KubeMQ contact.

Check the license: GET /api/v1/license

The management API reports the full licensing state. It is authenticated like every other management route.

curl -s http://localhost:8080/api/v1/license | jq

{
  "license_id": "6f1c2a3e-9b4d-4c5e-8a7f-1d2e3f4a5b6c",
  "issued_to": "Example Corp",
  "plan": "pro",
  "mode": "online",
  "source": "key",
  "license_expires_at": "2027-09-19T00:00:00Z",
  "lease_expires_at": "2026-09-26T12:15:00Z",
  "grace_days": 7,
  "run_until": "2026-10-03T12:15:00Z",
  "max_instances": 3,
  "fingerprint": "3f2a9c1e-7b6d-4e5f-9a8b-0c1d2e3f4a5b",
  "fingerprint_source": "persisted",
  "token_version": 3,
  "kid": "license-signing-v2",
  "last_refresh": { "at": "2026-09-19T12:15:00Z", "outcome": "ok", "status": 200, "next_at": "2026-09-19T13:12:00Z" },
  "clock": { "skew_seconds": 1, "skew_warning": false, "high_water_mark": "2026-09-19T12:15:00Z" },
  "revocation": { "seen_count": 0, "first_seen": null, "last_seen": null, "reason": null, "draining": false },
  "over_cap": false,
  "silent": false,
  "usage": { "enabled": true, "last_report_at": "2026-09-19T12:10:00Z", "last_outcome": "accepted", "last_status": 200, "cursor_to": "2026-09-19T12:10:00Z", "boot_id": "0b3d5f7a-9c1e-4a2b-8d6f-1e3c5a7b9d0f" },
  "warnings": []
}

The fields to watch:

?include=lease

GET /api/v1/license?include=lease adds a lease field carrying the bare lease token — the server's bearer credential. It is guarded accordingly: the call is refused with 403 when management-API authentication is disabled, it requires the admin role, and every call (granted or denied) is written to the audit log as license.lease_read. It exists for the operator's lease cache write-back (Kubernetes); kmq license never requests it.

kmq license

The CLI renders the same object:

kmq license
kmq license -o yaml
kmq license --fields plan,mode,lease_expires_at,run_until

-o selects the output format (json, ndjson, yaml, table); --fields projects the output to the named fields. The command needs a service key with at least the read_only role — see kmq CLI.

Change the licensing endpoint

KUBEMQ_LICENSE_ENDPOINT (default https://license.kubemq.io) is the base URL the server activates, refreshes and reports usage against. Change it only when told to by KubeMQ — for example to point at a forwarder inside your network that reaches the same host. The value is an http:// or https:// base URL (plain http:// is accepted for a development endpoint); a trailing slash is trimmed and the /v1/... paths are appended. Anything else is a configuration error and the server exits with code 1.

Pre-activated file for egress-restricted networks

Some networks can reach the internet in general but cannot open egress to license.kubemq.io — a strict allow-list, a proxy that strips request bodies, a regulated environment. The answer is not to open the firewall: ask KubeMQ for a pre-activated file.

A pre-activated file is an offline license file bound to your installation's fingerprint list, valid for up to one year. The server then runs exactly like an air-gapped installation — no activation, no refresh, no usage reports — and is renewed by reissuing the file before it expires. To request one, read each installation's fingerprint from GET /api/v1/license and follow Air-gapped installations.

Related settings

A drain or retry value outside its range (or one that is not an integer) is a configuration error: the server exits with code 1, not 3, and the log line names the variable.

The complete table, including the file variables, is in Core & Licensing.