License file

Your license file, helixor.hxlic, says who you are, which packs and features you may use, and until when. It also carries the key that opens your packs. This page lists every field and every check the runtime makes.

Format#

A UTF-8 JSON document. Every field except signature is covered by the signature, so changing any value, including whitespace inside a string, invalidates the file.

{
  "license_version": "1.0",
  "license_id": "hx_lic_org_example_1790000000",
  "issued_at": "2026-09-01T12:00:00+00:00",
  "identity": {
    "organization": "Example Corp",
    "org_id": "org_example",
    "contact_email": "security@example.com"
  },
  "entitlements": {
    "tier": "DEVELOPER",
    "plan_name": "Developer",
    "overage_policy": "TRUE_UP",
    "licensed_packs": ["compliance.regulatory_pii_guard.v1", "custom.*"],
    "licensed_solvers": ["solver.tcn.*"],
    "features": ["in_process_streaming", "decision_as_a_function", "custom_playbook_compilation"],
    "max_decisions_per_minute": null,
    "max_decisions_lifetime": null
  },
  "validity": {
    "valid_from": 1788264000.0,
    "valid_until": 1819800000.0,
    "grace_period_days": 14
  },
  "crypto": {
    "key_id": "ep1_2026",
    "content_key": "<secret>",
    "algorithm": "Ed25519-AES-256-GCM"
  },
  "signature": "<128 hex characters>"
}

Fields#

Agreement acceptance#

Planned A license is issued only for an account with a recorded acceptance of the current Helixor Software License Agreement. Licenses that record that acceptance use "license_version": "1.1" and carry a top-level agreement object:

{
  "license_version": "1.1",
  "license_id": "hx_lic_org_example_1790000000",
  "issued_at": "2026-09-01T12:00:00+00:00",
  "agreement": {
    "agreement_id": "helixor-software-license-agreement-v2",
    "agreement_sha256": "ab2e1e2a67e5b99165cc6f4f8c9713e2e8e525dba893797f4f94cbe50a399807",
    "accepted_at": "2026-09-01T11:58:40+00:00"
  },
  "identity": { "...": "..." },
  "entitlements": { "...": "..." },
  "validity": { "...": "..." },
  "crypto": { "...": "..." },
  "signature": "<128 hex characters>"
}

The agreement object is signed like every other field: it is part of the canonical bytes the Ed25519 signature covers, so changing it invalidates the license.

• 1.0 licenses still verify. A license without an agreement object and with "license_version": "1.0" is accepted as before.
• A 1.1 license must carry the agreement. A 1.1 license without the agreement object is rejected as invalid.
• A new agreement version needs a new acceptance. When Helixor publishes a new version, you accept it before a license is issued or renewed. Your current license keeps the version you accepted.

Verification#

Every time a license is loaded (by helixor-pack, when a pack is unsealed, or in POST /v1/decision with license_data), the runtime checks, in order:

1. Signature present

   A missing or empty signature fails with LicenseSignatureInvalidError.

2. Signature valid

   The runtime rebuilds the canonical form: every field except signature, serialized as JSON with sorted keys and no spaces. It verifies the Ed25519 signature against the Helixor authority public key built into the runtime. Any change fails with LicenseSignatureInvalidError. A license signed by a revoked authority key fails with its subclass LicenseRevokedAuthorityError: since 0.3.0 the runtime rejects the authority key that 0.2.0 and early 0.2.1 builds trusted, so a license signed with it must be reissued, and packs compiled for it compiled again.

3. Not before

   If the current time is before valid_from, it fails with LicenseNotYetValidError.

4. Not expired

   If the current time is after valid_until plus grace_period_days × 86,400 seconds, it fails with LicenseExpiredError. Between valid_until and that point the license still works, and inspect-license reports IN GRACE PERIOD.

Verification is offline. It uses the built-in public key and your system clock; no call is made to Helixor. Keep host clocks synchronized.

Pack and solver entitlements are checked separately, when you compile or load a pack. See Packs and manifest.

helixor-pack inspect-license ~/.helixor/helixor.hxlic

Tiers#

Installing a license file is currently manual: save it as ~/.helixor/helixor.hxlic with mode 600 (see Licensing). A helixor license activate command is Planned.

Features#

Where the runtime looks for the license#

The helixor-pack commands, HelixorEngine.load_pack (see the Python reference), the decision service and HelixorSolver use one search order and take the first file found:

1. The explicit path: --license, or license_file=.
2. $HELIXOR_LICENSE_FILE.
3. ./helixor.hxlic in the working directory.
4. ~/.helixor/helixor.hxlic.

The name helixor.lic that runtime 0.3.0 used is still accepted in the two directories. Both names in one directory raise LicenseLocationAmbiguousError (LICENSE_LOCATION_AMBIGUOUS). None found raises LicenseNotFoundError (LICENSE_NOT_FOUND, also a FileNotFoundError), whose message lists the six locations checked and the sign-up URL; the CLI prints it and exits with status 1. An explicit path or $HELIXOR_LICENSE_FILE naming a missing file raises the same error without searching further. HelixorEngine() searches nothing: it always uses the built-in Community license.

See Configuration for the environment variables.