# Licensing & trial

A licensed gateway verifies its licence at boot and licence-apply, with no runtime recheck or expiry. Trials use a separate time-limited runtime path. This page covers the licenses, trial operation, and activation, including unattended fleets.

## Community and Commercial.

### Community — free

- Single server, locked to the machine it activates on.
- Full single-gateway feature set.

### Commercial

- Full topology: mesh, peers, redundancy, and the non-standard gateway profiles require it.
- Bound to a deployment anchor: a machine, or a customer-owned PIV hardware token — the token option suits virtualization, where one token on the host licenses every container on it.

The license lives at `config/license.json` in the site. A leaked file is inert — it only works with its bound machine or token.

## Starting and restarting a trial.

An unlicensed gateway boots to a license page where you can start a trial — no account, no key. Starting it creates a **two-hour window** beginning immediately. Restart to load Commercial-equivalent entitlements; further restarts use the remaining time. The expiry watchdog shuts down the gateway when the window ends. Starting another trial waits out a cooldown that escalates with back-to-back trials — one hour, then two, capped at twelve. The next trial's cooldown resets to one hour after twelve hours have passed since the previous cooldown ended without starting another trial. There's no cap on how many trials you run, just on how fast you chain them.

```sh
# trial state is visible without auth
$ curl http://localhost:8400/api/license/status
{
  "state": "trial",
  "restart_required": false,
  "trial": {
    "active": true,
    "expires_at": "2026-07-03T20:14:08Z",
    "remaining_seconds": 5312,
    "trials_used": 3
  }
}
```

After a trial ends, the `trial` object reports `active: false` with `cooldown_until` and `cooldown_remaining_seconds`; an eligible unlicensed gateway reports `can_start: true`. The trial state is tied to the installation's gateway ID. A trial file carrying a different gateway ID is rejected; this is distinct from machine-bound licensing.

## Three ways to activate.

### Online

Paste an activation key into the gateway's license page (or `POST /api/license/activate`). The gateway makes one portal round-trip and installs the returned license. Follow the returned restart_required status; applying a licence from the lobby requires a restart.

### Offline

Air-gapped gateway: download a machine-request file from the license page (`GET /api/license/request-file`), carry it to the portal, bring the issued license back, apply it.

### Headless

Set an activation key in the environment and a brand-new gateway licenses itself on first boot — built for fleets. Table below.

## Headless activation variables.

| Variable | Purpose |
| --- | --- |
| `THERMITE_ACTIVATION_KEY` | Activation key or account API key — a brand-new gateway self-activates at first boot. |
| `THERMITE_ACTIVATION_KEY_FILE` | Read the key from a file (container secrets, systemd credentials). Mutually exclusive with the inline key — setting both is a config error. |
| `THERMITE_ACTIVATION_EDITION` | commercial (default) or community. |
| `THERMITE_ACTIVATION_LABEL` | Optional operator label recorded with the issuance. |
| `THERMITE_LICENSE_FAILURE_MODE` | lobby (default) — serve the Activate page for a human; exit — exit non-zero so an orchestrator's restart policy and monitoring see the failure. |
| `THERMITE_PORTAL_BASE` | Override the licensing portal base URL. |

Self-activation fires only when the gateway boots with *no* license file. An existing licence prevents automatic boot activation; manually requested activation can still contact the portal. One attempt per boot; a supervised restart retries. For orchestrated fleets, prefer `THERMITE_LICENSE_FAILURE_MODE=exit`, or probe readiness by inspecting the `state` field of `GET /api/license/status` — note that endpoint returns HTTP 200 even in the unlicensed lobby, so a status-code-only probe would mark a lobby gateway ready.
