License Status and Renewal¶

A Huitzo Self-Hosted deployment runs on one Ed25519-signed license.json, issued by Huitzo for that deployment's ID. There is no license server, no online validation and no network call in the licensing path: the backend and the workers read the file and verify it on the host. This page covers what an operator does with that file: place it, check its status, renew it and reload it. Requesting a license is on Request a license.

The license file¶

A license is one JSON file, signed with Ed25519 over the canonical bytes of every field except signature. Its main fields:

Every field is inside the signed bytes, so editing any of them, or even reformatting the file, invalidates it. Raising a limit or extending a term always means a newly signed file.

Editions¶

The tier field is the edition; the purpose decides which one a license gets. The full comparison, with every Preview limit, is in Core editions.

A Preview can only be smaller: a preview file signed with a limit above the Preview value, or carrying a feature, is INVALID (402). Self-hosted Core has no credits, wallets or Stripe billing.

Limits and refusals¶

Each limit is checked where the count can grow. The effective limit is min(licence ceiling, tenant quota, code default): a tenant quota may lower a licence limit, never raise it (how limits are enforced). Licensed and Hosted carry no limit claims, so none of these checks runs a count there.

Shared refusals:

monthly_executions is a soft cap: concurrent runs that pass the check together can overshoot it by a few. A refused request records no execution.

Operating a license file¶

Where the license lives¶

install.sh --license license.json checks the file offline and places it at license/license.json in the install directory (/opt/huitzo) (Install). The license/ directory is mounted read-only at /etc/huitzo/license/ into the migrate, backend, worker and beat containers. Keep the file mode 0644 and never edit it.

The workers read it too: while the license is INVALID they run no task (log event task_license_refused), and on a Preview they skip scheduled runs once the monthly_executions limit is reached (log event scheduled_dispatch_license_skipped).

Check status¶

The backend logs a warning, and responses carry an X-License-Warning header, while the license is in GRACE.

Renew¶

A license is renewed by replacing the file with a newly signed one for the same deployment ID; its later expires_at resets the grace clock. There is no auto-renewal and no subscription toggle.

1. Request the renewal at least 30 days before expires_at, in the partner portal (Request a license). Paid renewals are issued once the client's invoice is paid, and never past its paid-through date.
2. Download the new license.json from the portal's Licenses page and copy it to the host unchanged.
3. Install it with one of the methods below, from the install directory.
4. Confirm that the status shows the new expiry (Check status).

With the Huitzo CLI¶

# pseudocode: on the host, in the install directory (/opt/huitzo)
huitzo license install license.json

huitzo license install needs a Huitzo CLI that includes the command (check huitzo license --help). It:

• verifies the file offline with the release's backend image and refuses an INVALID file or one issued for another deployment ID, before writing anything; it asks before installing a file that expires earlier than the current one (--yes skips the question);
• refuses a file that is already in GRACE (expired, inside its grace window) unless you pass --allow-grace, the same rule as install.sh; huitzo license verify and install print a grace warning for such a file;
• keeps the current file as license.json.prev and writes the new bytes over the live file in place;
• activates it: with an admin or owner session on a deployment whose license is VALID or GRACE it calls reload; otherwise it prints docker compose restart backend worker, and --restart runs it;
• waits for the deployment to report the new expiry, and restores license.json.prev if the deployment reports the new file INVALID.

With install.sh¶

# pseudocode: on the host
/opt/huitzo/install.sh --license license.json

The installer runs its offline license preflight and refuses an INVALID file, one issued for another deployment ID, or (without --allow-grace) one already in GRACE, leaving the live file unchanged. A usable file is written over license/license.json in place. Then reload, or wait for the hourly re-read.

By hand¶

On a host without the CLI, write the new bytes over the live file and restart the services that read it:

# pseudocode: on the host, in the install directory (/opt/huitzo)
cp license/license.json license/license.json.prev
cat ~/license.json > license/license.json
docker compose restart backend worker

This skips the offline check: an INVALID file stops the deployment at the restart. If it does, write license.json.prev back the same way and restart.

Reload¶

The backend and the workers re-read the file at most hourly. To apply a new file immediately without a restart, call reload through the dashboard origin with the token of a tenant admin or owner (other members get 403):

# pseudocode
curl -X POST https://<host>/api/v1/license/reload \
  -H "Authorization: Bearer <admin or owner token>"

The response carries the new state. A reload also tells the workers to re-read the file before they refuse any work. A replacement file that is itself invalid or expired never advances the state. Once the license is INVALID nobody can sign in to get a token, so restart instead: docker compose restart backend worker.

Change edition¶

Moving from Preview to Licensed (for example, a Demo/POC that becomes a Pilot) is a license replacement: request the new license for the same deployment ID, install it and reload. No data migration is involved. Moving to Licensed lifts every limit and removes the Preview banner (Moving between editions).

State machine¶

Expiry is evaluated on every request. A file that is missing or tampered never enters grace. HUITZO_OFFLINE_GRACE_DAYS may lower the signed grace, never raise it. HUITZO_LICENSE_CHECK_INTERVAL sets the re-read interval and is capped at 3600 seconds; a higher value refuses to boot.

Troubleshooting¶

For anything else, contact your Huitzo partner contact or [email protected].

See also¶

• Request a license
• Connected installation
• Core editions
• Operations