Okapi
Get a license

Telemetry

Every Okapi instance checks in with OKAPI_UPDATE_ENDPOINT (default https://api.useokapi.app) roughly every 3 hours. This page is the complete, exact list of what that check-in can send — nothing here is abridged.

The version check is mandatory; the rest is opt-out

There are two different requests an instance might make, and which one it makes depends on two independent things: whether telemetry is enabled, and whether the instance is licensed.

Unlicensed, with telemetry disabled (OKAPI_DISABLE_TELEMETRY=1) — a bare GET /v1/latest. No body and no instance id; the only detail it carries is the okapi/<version> User-Agent. This is the mandatory part: Okapi checks whether a newer release exists unless OKAPI_SAFE_MODE suppresses outbound requests, but this specific request carries no information about your instance at all.

Telemetry enabled (the default), or the instance is licensed — a POST /v1/checkin carrying:

  • instanceId — always. A random identifier generated locally on first boot; it isn't tied to any account, email, or license by itself.
  • version — always. The running Okapi version.
  • os / arch — only when telemetry is enabled. Omitted entirely when OKAPI_DISABLE_TELEMETRY=1.
  • licenseKey — only when the instance has activated a license. This is sent regardless of the telemetry setting, including with telemetry disabled — the license check-in is what keeps your cached entitlements (coverage, seats, offers) current, so it runs independent of the telemetry opt-out.

What we see that your instance doesn't send

One thing is worth stating plainly because it isn't in the list above and never will be: like any HTTP server, the control plane sees the IP address a request arrives from, and it records that address on license requests (/v1/activate and /v1/checkin) so activations and check-ins can be traced when a key looks like it's in more places than it should be. That's connection metadata — a property of your instance connecting to us at all, not a new field the client puts in the payload.

What never leaves your instance

Events, logs, issue content, stack traces, user data, and anything else in your database. The fields listed above are the entire contents of every outbound request Okapi's update/license check ever makes — there is no broader "usage analytics" payload beyond what's written out here.

Turning it off

Set OKAPI_DISABLE_TELEMETRY=1 in your .env, then recreate the app with docker compose up -d --force-recreate app. A compose file downloaded before this variable was added does not pass it, and OKAPI_UPDATE_ENDPOINT is not passed at all — use an override file for those, as described in Setting variables the compose file does not list. This stops os/arch from ever being sent and, for an unlicensed instance, drops the check-in down to the bare version-check GET. The telemetry opt-out does not disable the version check or a licensed instance's check-in. OKAPI_SAFE_MODE suppresses both — see Safe mode.

The fail-open promise

Losing contact with OKAPI_UPDATE_ENDPOINT does not change the cached license state. After 14 days without a successful check-in, Okapi shows a quiet notice. An already-recorded coverage lapse or revocation keeps its 14-day or 30-day grace clock and then locks, even offline — see Licensing. Network failure does not start a new grace clock or freeze an existing one.

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