> Raw Markdown twin (generated at build time from the source Markdown). Rendered page: https://docs.gatellm.io/en/reference/licensing · Doc index: https://docs.gatellm.io/en/llms.txt


# 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](/en/quickstart/docker-single-node.md) **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](/en/practices/production-checklist.md).

## 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:

```bash
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](/en/reference/image-tags-and-arch.md).

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](/en/usecases/high-availability.md).

**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](/en/quickstart/docker-single-node.md#common-env-vars).

**Next**: [Environment variable reference](/en/reference/configuration.md) for all environment variables; [Production checklist](/en/practices/production-checklist.md) for production storage selection; [Achieve high availability](/en/usecases/high-availability.md) for multi-instance deployment.