What okfhub counts, and what you can opt out of

Install counts

When okfhub add <org>/<bundle> succeeds, the CLI sends a single fire-and-forget ping to /api/ingest. The ping is default-on (per the ecosystem majority — npm, the GitHub CLI, Vercel, Homebrew all ship default-on) and carries exactly six fields: the bundle namespace + name, the event type, a daily-rotating dedup hash, a CI flag, and the CLI version. That is the entire payload — no IP, no User-Agent, no OS, no geo, no referrer.

The daily_id_hash is computed client-side as sha256(install_id + UTC_date + server_salt) from a random local identifier. It lets the server dedup same-machine-same-day (so a re-install doesn't double-count) while being unlinkable across days and unrecoverable to the install_id. No IP is ever put in the payload.

How to opt out of the install ping

Any ONE of these disables the install ping (they are OR'd together — set any one and the CLI sends nothing, not even a “telemetry disabled” heartbeat):

# (a) Environment variable — the universal / CI / air-gapped path
export OKFHUB_NO_TELEMETRY=1

# (b) Persisted config command — the discoverable path
okfhub telemetry disable

# (c) The DO_NOT_TRACK convention (npm / gh / Vercel honor it too)
export DO_NOT_TRACK=1

See the current effective state with okfhub telemetry status (it resolves all three signals) and the exact payload with okfhub telemetry show.

CI vs human installs

When the CLI detects a CI environment (CI, GITHUB_ACTIONS, GITLAB_CI, etc.), the ping is tagged ci: true and counted in a separate bucket. This is the single highest-leverage accuracy fix — npm and PyPI download counts are notorious for NOT doing this, so a pipeline running 50×/day reports 50 “installs.” okfhub keeps human and CI counts distinct.

Live-read counts

When an agent calls read_concept or list_concepts through the public MCP gateway, the gateway increments a per-bundle counter. This is server-side: the gateway sees the request, like an npm download counter or a crates.io download count. There is nothing for the client to opt out of — the count happens because the request reached the server.

The install-ping opt-out does NOT affect the read count. Opting out of telemetry stops the client install ping; it does not stop the gateway from observing a request it received. (Conflating these two — claiming the opt-out affects the read count, or that the read count is “anonymous because no IP” — is the privacy leak this design avoids.)

Only gateway reads are counted — live registry queries. Local okfhub mcp reads (an agent reading your installed copy over stdio) are NOT counted, because that is a local file read, not a live-registry query. The read counter retains no per-client data — just an incrementing integer per bundle.

How your IP is used (rate-limiting only)

To protect the ingest and gateway endpoints from abuse, we rate-limit per IP using a sliding window. This derives a short-lived key from your IP that is stored in our Redis (Upstash) for up to about 2 minutes and then expires automatically. We never log IP addresses, and we never persist them beyond that bounded rate-limit window — the IP-derived key exists only for the window TTL and is never written to any log or any long-term store.

In short: the only things retained are the aggregate integer counters and the daily-rotating daily_id_hash dedup set (which rolls over each UTC day). The rate-limit IP-derived key is bounded to the ~2-minute window and is not part of that retained set.

What we never collect

The install ping payload is exactly the six fields above — verified by okfhub telemetry show and enforced by a strict server schema that rejects any extra field. Specifically, we never collect:

• Your IP address (the IP is used only to derive the ~2-minute rate-limit window key — it is never sent in the ping body, never logged, never persisted beyond the window).
• Your User-Agent, OS, architecture, or locale.
• Geographic location or network information.
• Referrer, entry path, or how you found okfhub.
• The raw install_id (only the daily-rotating hash crosses the wire).

Full product analytics (geo / referrer / agent-type distribution) is permanently out of scope for this milestone. okfhub telemetry is install count + live reads, nothing more.

How counts are shown

Counts on the site are descriptive, never a verdict. A bundle row shows “N installs” and the evidence strip carries the backing repo context (with the “popularity ≠ safety” framing) — the install count’s caveats live here rather than on the row: “updated every 6h · opt-out; actual may be higher”. The numbers are refreshed by a 4×/day job, so they are at most about 6 hours stale; and because some users opt out, the real install count may be higher than what is shown. Counts never become a “popular,” “trending,” or “best” label, and no threshold, score, or color is derived from them — a high count is not an endorsement.