Licensing
VCAL Semantic Cache uses mandatory signed-license enforcement. Each instance validates a signed license file at startup.
The server will not start without a valid license.
License Tiers
| Tier | Description | Duration | Notes |
|---|---|---|---|
| Trial | Free evaluation | 30 days | Time-limited technical evaluation |
| Growth | Commercial license | 1 year | Production use, support, and updates |
| Enterprise | Custom agreement | Multi-year | Enterprise terms, advanced support, and custom deployment options |
License Sources
VCAL Semantic Cache can load a license from several sources.
| Variable | Purpose |
|---|---|
VCAL_LICENSE_JSON | Inline signed license JSON |
VCAL_LICENSE_PATH | Path to signed license JSON file |
VCAL_LICENSE_FILE | Alternate path to signed license JSON file |
VCAL_DOCKER_LICENSE_PATH | Docker-specific license path override |
The default license path is:
/etc/vcal/license.json
Avoid setting multiple license variables to different files. If you use Docker, remember that the path in VCAL_LICENSE_PATH must exist inside the container, not only on the host.
Public Key Verification
VCAL Semantic Cache validates the signed license using an Ed25519 public key.
| Variable | Purpose |
|---|---|
VCAL_LICENSE_PUBKEY_FILE | Optional path to public key file, for example /etc/vcal/ed25519.pk.b64 |
Some builds may include a default verification key. For controlled deployments, mount the public key and set VCAL_LICENSE_PUBKEY_FILE explicitly.
Docker Example with Existing Annual License
Host files:
/etc/vcal/vcal-chatbot-annual-13112025.lic.json
/etc/vcal/ed25519.pk.b64
Container command fragment:
-v /etc/vcal/vcal-chatbot-annual-13112025.lic.json:/etc/vcal/vcal-chatbot-annual-13112025.lic.json:ro -v /etc/vcal/ed25519.pk.b64:/etc/vcal/ed25519.pk.b64:ro -e VCAL_LICENSE_PATH=/etc/vcal/vcal-chatbot-annual-13112025.lic.json -e VCAL_LICENSE_PUBKEY_FILE=/etc/vcal/ed25519.pk.b64
A common mistake is to leave an old .env value such as:
VCAL_LICENSE_PATH=/var/lib/vcal/license.json
while also setting:
VCAL_LICENSE_FILE=/etc/vcal/annual-license.json
Use one clear license path or make both variables point to the same file.
Example License File
{
"license_id": "lic_0a7efb91",
"holder": "Example Labs",
"tier": "Growth",
"issued": "2026-05-31",
"exp": "2027-05-31",
"sig": "base64signature..."
}
Validation Flow
At startup:
- VCAL locates the license source.
- VCAL loads the vendor public key or configured public key file.
- VCAL reads the signed license JSON.
- VCAL verifies the Ed25519 signature and expiration.
- License metadata is cached in memory and exposed through status/metrics.
If the license is missing, invalid, unreadable, or expired, VCAL Semantic Cache exits with a diagnostic message.
Trial License Issuance
Trial licenses are self-served via the CLI.
vcal-server license trial <your_email>
vcal-server license verify <code>
To write to a custom path:
export VCAL_LICENSE_PATH="$PWD/license.json"
vcal-server license trial <your_email>
vcal-server license verify <code>
License Status Endpoint
Check the active license with an admin key:
curl -H "X-VCAL-Key: <admin_key>" http://localhost:8080/v1/license/status
Example response:
{
"valid": true,
"tier": "growth",
"org": "VCAL Labs",
"days_until_expiry": 165
}
Renewal
To renew or upgrade a license:
- Obtain a new signed license file.
- Replace the existing license file.
- Restart VCAL Semantic Cache.
docker restart vcal-server
or:
sudo systemctl restart vcal-server
Metrics
Useful licensing metrics include:
vcal_license_valid
vcal_license_days_until_expiry
vcal_license_enforcement_events_total
Multiple Licenses
VCAL Semantic Cache enforces one active license at a time. If multiple license files exist, the one selected by the configured license source is used.