Hosting edition

Licensing and renewal

How Hosting edition license keys work, what happens when one expires, and how keys renew on their own.

The open-source core needs no key. The Hosting edition does: it will not start without a valid license key in license_file.

The key file#

A key is one line of text that starts with lurcast-license-v1.. Save it as a plain text file and point hosting.license_file at it:

hosting:
  license_file: /var/lib/lurcast/license.key

Keys are signed, and the server checks the signature offline. It does not contact anyone to start or to stream. The only outgoing request is the optional automatic renewal.

What is in a key#

Field Meaning
id The key's subscription. Keys bought online carry the subscription ID, which starts with sub_.
licensee Your company name.
email Where keys are sent.
edition Always hosting.
max_stations How many stations you can create. Empty means no limit.
issued_at When the key was made.
expires_at When the key runs out.

Each key covers one billing period, plus a few days so a renewal has time to arrive. GET /api/hosting/v1/license shows the key's licensee, expiry, station limit and how many stations you have.

Station limits#

Your plan sets max_stations:

Plan Stations
Starter 25
Growth 100
Unlimited No limit

Creating a station past the limit fails with 403 and License allows 25 station(s). If you move to a smaller plan and already have more stations than it allows, your stations keep running; you cannot create new ones until you are under the limit. Listener counts, bitrates and transfer are not limited by the license; you set those per station.

When a key expires#

Listeners are never cut off because of the license.

  1. Up to 30 days before expiry, the server logs a warning at startup.
  2. After expiry, everything keeps working for 14 days of grace, with a warning in the log.
  3. After the grace period, existing stations keep streaming, but the API is read-only: creating, changing, suspending and deleting stations fail with 403 until you install a renewed key. Reading stations, usage, reports, metrics and the license still works.

GET /api/hosting/v1/license reports expired: true once the key has run out and lapsed: true once the grace period is over. Prometheus can alert on lurcast_license_expiry_timestamp_seconds; see Metrics and royalty reports.

Automatic renewal#

With license_url set (the default is https://lurcast.com/api/license/renew), the server renews its own key:

  • It checks every 6 hours, starting a minute after startup.
  • From 10 days before the key expires, it posts the current key to license_url. Only the key is sent.
  • If your subscription is still active, it gets back the key for the current billing period, saves it to license_file and uses it straight away. No restart is needed.
  • If the subscription has ended, the server logs why the renewal was refused and keeps the current key. It tries again on the next check.

The server writes the new key next to the old one and renames it into place, so the directory that holds license_file must be writable by the server's user. Network errors are logged and retried 6 hours later.

To run fully offline, turn renewal off and install each new key by hand:

hosting:
  license_url: ""

Installing a key by hand#

We email a new key after each payment, so you always have the current one even with renewal off. To install it:

  1. Replace the contents of license_file with the new key.
  2. Restart the service, for example sudo systemctl restart lurcast-hosting.

The server reads the key file at startup; with renewal off it does not watch the file for changes.

Keys issued by hand rather than through a subscription are not renewed automatically. Ask info@lurcast.com for a new one.

Cancelling#

If you cancel, your key keeps working until it expires, then for the 14-day grace period. After that your stations keep streaming but cannot be changed. Nothing is deleted.