Reliability And Privacy

How Kunai protects user data, limits provider traffic, and keeps failures diagnosable.

Kunai is designed to keep playback useful when providers, networks, Discord, or local files behave imperfectly. The default rule is simple: preserve the user's current context, keep durable user data safe, and make failures explainable.

What Kunai Protects

Watch history, lists, playlists, queue sessions, notifications, followed titles, and completed download records are durable user data.
Stream URLs, provider caches, recommendation caches, release schedules, source inventories, provider health, and trace rows are disposable cache data.
Startup maintenance may prune expired cache rows. It must not delete durable history, playlists, download jobs, lists, follows, or notifications.

Recovery Behavior

Playback recovery is conservative:

recover refreshes the current playback intent after failure evidence.
replay or restart starts the current episode from the beginning.
a failed fresh lookup can keep the current cached stream if it is still usable.
provider fallback should explain what failed and what recovered.

Queue recovery is explicit. If a previous session crashed with pending queue items, Kunai can show a recoverable queue notice. Restoring that notice moves pending items into the current session, but it does not autoplay them.

Offline And Downloads

Downloads stay local-first:

/downloads manages queued, running, failed, and retryable jobs.
/library and /offline show completed local media.
completed artifacts are validated before Kunai marks them ready.
when ffprobe is available, Kunai stores local duration metadata after validation.
offline rows may show duration, resume position, percent watched, and watched state from local history.

Opening the offline library must not call providers. Repair, re-download, and online playback are explicit user actions.

Diagnostics Privacy

Diagnostics stay local unless you export or share them. Exported bundles are redacted and should not include raw stream URLs, cookies, authorization headers, signed query values, or private home-directory paths.

The fastest way to inspect reliability state is:

/diagnostics

For a shareable local bundle:

/export-diagnostics

Support bundles include category sections such as playback, provider, cache, presence, download, and offline. Each section includes the latest operation so a report can show whether a provider fallback happened, Discord failed to clear, or a download artifact was validated.

Usage analytics

Anonymous usage analytics are off by default. You can explicitly enable or disable them in Settings → General → Usage analytics.

On a fresh install, setup offers an explicit choice. Existing installs get one non-blocking recommendation explaining the payload; that notice does not enable analytics, create an id, or send anything. No analytics requests run before you enable it, in a non-interactive terminal, or when DO_NOT_TRACK=1 or CI=true.

When on, Kunai sends at most one tiny ping per day:

{ "installId": "<uuid>", "version": "<semver>", "os": "<platform>", "arch": "<arch>", "ts": 0 }

Never titles, queries, providers, stream URLs, or file paths
Turning it off deletes the install id from disk. The id exists only while analytics is enabled
DO_NOT_TRACK=1 and CI=true block sends regardless of the setting. A value of 0, false, or no does not block
Without an interactive terminal — piped or scripted output — analytics stays off, because the notice could not be shown
The ingest stores HMAC-hashed install ids with your platform, architecture, and version, and never a raw UUID. It does not read your IP address at all
Raw rows are deleted after 35 days. A permanent table keeps one hashed row per install with a first-seen date, which is what an exact lifetime count costs
Public docs show yesterday's active installs, a lifetime total, and version / platform / architecture breakdowns. Any group with fewer than 5 installs is reported as other. This is per-breakdown small-cell suppression, not a joint anonymity guarantee. Those numbers can be inflated by abuse; they cannot expose what you watch. See the live usage analytics page.

Preview the exact JSON with /analytics show.

If you turn analytics on, pings go to analytics.kunai.kitsunekode.in. Point them somewhere else — or nowhere — by setting KUNAI_ANALYTICS_URL, or analyticsEndpoint in your config; an empty value disables sending outright. Leaving analytics off, running without a terminal, or setting DO_NOT_TRACK means nothing is ever sent, whatever the endpoint says.

Release Confidence

Before release candidates, deterministic checks should pass first:

bun run fmt
bun run lint
bun run typecheck
bun run test
bun run build

Live provider, Discord, and real mpv checks are still manual by design. They are provider and machine reality checks, not default CI.

What Kunai Protects

Watch history, lists, playlists, queue sessions, notifications, followed titles, and completed download records are durable user data.
Stream URLs, provider caches, recommendation caches, release schedules, source inventories, provider health, and trace rows are disposable cache data.
Startup maintenance may prune expired cache rows. It must not delete durable history, playlists, download jobs, lists, follows, or notifications.

Recovery Behavior

Playback recovery is conservative:

recover refreshes the current playback intent after failure evidence.
replay or restart starts the current episode from the beginning.
a failed fresh lookup can keep the current cached stream if it is still usable.
provider fallback should explain what failed and what recovered.

Offline And Downloads

Downloads stay local-first:

/downloads manages queued, running, failed, and retryable jobs.
/library and /offline show completed local media.
completed artifacts are validated before Kunai marks them ready.
when ffprobe is available, Kunai stores local duration metadata after validation.
offline rows may show duration, resume position, percent watched, and watched state from local history.

Opening the offline library must not call providers. Repair, re-download, and online playback are explicit user actions.

Diagnostics Privacy

The fastest way to inspect reliability state is:

/diagnostics

For a shareable local bundle:

/export-diagnostics

Usage analytics

Anonymous usage analytics are off by default. You can explicitly enable or disable them in Settings → General → Usage analytics.

When on, Kunai sends at most one tiny ping per day:

{ "installId": "<uuid>", "version": "<semver>", "os": "<platform>", "arch": "<arch>", "ts": 0 }

Never titles, queries, providers, stream URLs, or file paths
Turning it off deletes the install id from disk. The id exists only while analytics is enabled
DO_NOT_TRACK=1 and CI=true block sends regardless of the setting. A value of 0, false, or no does not block
Without an interactive terminal — piped or scripted output — analytics stays off, because the notice could not be shown
The ingest stores HMAC-hashed install ids with your platform, architecture, and version, and never a raw UUID. It does not read your IP address at all
Raw rows are deleted after 35 days. A permanent table keeps one hashed row per install with a first-seen date, which is what an exact lifetime count costs
Public docs show yesterday's active installs, a lifetime total, and version / platform / architecture breakdowns. Any group with fewer than 5 installs is reported as other. This is per-breakdown small-cell suppression, not a joint anonymity guarantee. Those numbers can be inflated by abuse; they cannot expose what you watch. See the live usage analytics page.

Preview the exact JSON with /analytics show.

Release Confidence

Before release candidates, deterministic checks should pass first:

bun run fmt
bun run lint
bun run typecheck
bun run test
bun run build

Live provider, Discord, and real mpv checks are still manual by design. They are provider and machine reality checks, not default CI.

Reliability And Privacy

What Kunai Protects

Recovery Behavior

Offline And Downloads

Diagnostics Privacy

Usage analytics

Release Confidence

On this page

Reliability And Privacy

What Kunai Protects

Recovery Behavior

Offline And Downloads

Diagnostics Privacy

Usage analytics

Release Confidence

On this page