Licensing and authorization

When no valid license (LICENSE_KEY) is injected, GateLLM runs as the free edition: single-node mode is fully functional, but the memory cap is squeezed to 512MB and distributed capabilities like Redis / PostgreSQL are disabled. This chapter explains what you'll see, what limits apply, and how to activate.

Getting through Docker single node does not require a license — the zero-config main path is exactly the free-edition state, and the whole single-node tutorial completes normally.

What happens when unlicensed

License status is determined by whether a valid LICENSE_KEY is injected at startup (empty = unlicensed = free edition). When unlicensed, the gateway converges configuration as follows during startup:

Item	Unlicensed (free edition)	Licensed
Memory cap MEMORY_SOFT_LIMIT_MB	Capped at 512 MB (config values above 512 are squeezed to 512)	Per config value, no cap
REDIS_URL	Cleared (disabled)	Enabled per config
POSTGRES_URL	Cleared (disabled)	Enabled per config
STORAGE_MODE	Forced to sqlite (single-node)	Can use postgresql (multi-instance)
Distributed / multi-instance	Unavailable	Available

⚠️ If you set a non-empty REDIS_URL / POSTGRES_URL while unlicensed (i.e. you actually connected Redis / PostgreSQL), startup fails outright with license restriction: this instance is unlicensed and cannot use distributed features.... Setting only STORAGE_MODE=postgresql while POSTGRES_URL is empty (the image default) does not fail — the license layer downgrades it to sqlite and continues startup under the 512MB cap. The free edition can only run single-node sqlite. For production storage selection see the production checklist.

Console banner

After logging into the console, an unlicensed instance shows a persistent amber banner at the top (triggered by /console/api/check-status returning valid=false):

• Free edition: Free version — memory is capped at 512MB, Redis and PostgreSQL are disabled (single-instance mode only). Contact your provider to activate a license.
• License expired: License expired — memory is capped at 512MB, Redis and PostgreSQL are disabled (single-instance mode only).

The banner is amber, not red — this is a soft degradation, not a fault. The gateway keeps running; only distributed capabilities are turned off.

What is unaffected

Under the free edition (unlicensed), the following are identical to the licensed version:

• All routing, protocol translation, load balancing, access control, and script transforms of the single-node gateway
• The console UI and management API (users, upstreams, models, keys, logs, statistics)
• The docs site itself (local search, dark mode, etc., unrelated to licensing)

In other words, using GateLLM single-node does not require a license. A license is only needed when you want to run multi-instance shared state (Redis + PostgreSQL).

How to activate

The license key is an Ed25519-signed base64 string (payload||signature), injected via an environment variable:

docker run -e LICENSE_KEY="<your license key>" ghcr.io/gatellm-io/gatellm:latest

ℹ️ License validation only takes effect when the image is built with --build-arg LICENSE_ENABLED=true. The official ghcr.io/gatellm-io/gatellm:latest enables it by default; self-built images must confirm this build-arg. After injecting a valid key and restarting, the console banner disappears and the 512MB and distributed limits are lifted. The official image is multi-arch (linux/amd64 + linux/arm64); for tag semantics and how to pin an architecture, see image tags and architectures.

Contact your deployment party or provider to obtain a license key.

Console license panel and online re-validation

On a licensed instance, Console → Settings → System shows the "License" panel: plan (Professional / Enterprise), billing cycle (monthly / yearly), total memory, instance-count cap, per-instance memory, license number, plus the last online check time and last result (valid / invalid).

Licensing is not a one-time check — the gateway periodically re-validates online against the license server (normally about every 24 hours; on validation failure it enters a degradation cadence, retrying about every 30 minutes):

• Grace period: when an online re-validation finds the license invalid (e.g. expired, revoked), the gateway does not degrade immediately — it enters a grace period (number of days issued by the license server), and the panel shows "Grace period · N days remaining". Features are unaffected during the grace period; only after it is exhausted does the gateway degrade to the free edition (512MB memory cap, Redis / PostgreSQL disabled). If you see a grace warning, renew or switch to a new key as soon as possible.
• Cluster over-limit: in a multi-instance deployment, when reconciliation detects the actual instance count or total memory exceeds the licensed quota, the panel shows an "over-limit" warning — warning only, the gateway keeps serving; reduce instances or contact the provider to raise the quota.

FAQ

Q: The banner says "contact the provider to activate", but I'm just a caller. This banner is aimed at the operator deploying GateLLM. If you only call models through the gateway (a caller), this banner does not affect your usage — it only concerns the deployer's multi-instance / high-availability capabilities. Contact your platform operator.

Q: Can the free edition go to production? Yes for single-node with memory needs < 512MB. Production deployments that need multi-instance high availability, Redis shared state, or PostgreSQL storage require a license. See Achieve high availability.

Q: Injecting LICENSE_KEY made startup fail instead? After injecting a license, the license layer no longer forces STORAGE_MODE back to sqlite. If you set STORAGE_MODE=postgresql but didn't fill POSTGRES_URL, it errors with server.postgres_url is required for postgresql storage mode. Either fill POSTGRES_URL, or explicitly set STORAGE_MODE=sqlite. See Docker single node → Common environment variables.

Next: Environment variable reference for all environment variables; Production checklist for production storage selection; Achieve high availability for multi-instance deployment.