Licensing (self-host)

This page covers self-host licensing. Cloud subscriptions don't have a lock state — see Self-host vs. cloud.

The trial¶

A fresh self-host install runs a full-featured 14-day trial the moment it boots — no key, no signup, nothing to configure.

What locks at expiry¶

When the trial ends (or a license lapses — see below), Okapi keeps ingesting and storing everything, without exception. Nothing is ever deleted. The only thing that changes:

• Issue and log detail views blur behind an unlock prompt.
• Live counts stay visible — you can still see that something is happening, just not the details.
• Settings stay open far enough to activate a license at any time — you're never locked out of the one screen that would unlock you.

Activation¶

Go to Instance settings → Plan & license. Two ways in:

• Paste a license key (OKAPI-XXXX-XXXX-XXXX-XXXX).
• Use the built-in checkout.

Either unlocks live, with no restart. Activation is the one step in Okapi's licensing that needs an internet connection — everything else works fully offline (see below).

Perpetual fallback¶

Self-host licensing is a one-SKU annual subscription that entitles you to updates for as long as it's active. If you cancel or let it lapse, you don't lose what you already have: the version you're running keeps working, forever — across backups, restores, and reinstalls of the same version. You just stop getting new releases until you renew. There is no kill switch.

Coverage and the migration gate¶

Every license carries a coverage horizon (updatesUntil) — the newest release date it entitles you to run. As long as the build you're on is within that window, upgrades apply normally.

The only hard gate is at schema migrations. If you try to upgrade to a build past your coverage window, and that upgrade has pending schema migrations, boot holds in a static limbo page instead of migrating — the schema is left untouched and the instance stops accepting new events until you act. Two ways out:

• Renew — completing a checkout unlocks and resumes boot live.
• Roll back — redeploy the newest version your license actually covers. The exact compose image pin to use (e.g. image: ghcr.io/useokapi/okapi:1.8.2) is shown right on the limbo page.

Every other case migrates through automatically: a fresh database, a dev/CI build, an unlicensed trial instance, an upgrade within coverage, or an out-of-coverage upgrade with nothing pending to migrate at all. OKAPI_FORCE_MIGRATE=1 is the explicit operator override that migrates through the gate regardless — the same category of consent as OKAPI_SKIP_MIGRATE. See Installation → Updating for the practical upgrade/rollback steps.

Offline behavior¶

An instance that can't reach the license server is never degraded below its last-known state. Entitlements are cached in your own Postgres and never expire on their own — if OKAPI_UPDATE_ENDPOINT becomes unreachable, you'll see at most a quiet notice after the grace window closes (14 days for a coverage lapse, 30 days for a revoked license — see below); until then, everything stays exactly as unlocked as it was. A lapsed-but-still-covered license simply keeps the version you have, indefinitely.

Lock states¶

Internally, a self-host instance resolves to one of four states, all rendered identically by the dashboard (issue/log detail views blur; settings stay read-only except the license panel; ingest and deletion are never affected):

• Unlocked — trial active, licensed and covered, or within a grace window.
• Trial expired — the 14-day trial ended with no license activated.
• Coverage lapsed — licensed, but the running build is past updatesUntil and the 14-day out-of-coverage grace has also passed.
• Revoked — the license was revoked (e.g. after a refund) and the 30-day revocation grace has passed.

Seats¶

maxSeats on your license gates organization membership: inviting a new member or accepting an invite past your seat limit is blocked until you free up a seat or upgrade.

Next: Self-host vs. cloud if you're still deciding which to run.