Skip to content

GuidesLicence and updates

How the check works

bitchos validates your key against hwic.dev from the first tick that has a session UUID, retrying with backoff (1 s, 2 s, 4 s… capped at 30 s) until it has an answer. Nothing runs until it does: the tick bus is withheld from an unlicensed client, so no module can act.

  • Once validated, it re-checks every 6 hours, which also refreshes the offline stamp.
  • Switching Minecraft accounts inside Lunar is noticed immediately and forces a fresh check.
  • A key binds to the first Minecraft UUID it validates on. Used on another account it is refused with "This key is bound to another Minecraft account". Only the key owner can unbind it, via Discord.

/bitchos licence prints the full state: key file path, masked key, account, last result, what the server said, remaining grace and time to the next check. It works even when unlicensed.

Three answers, not three shades of one

The server can only say three things, and the mod treats them differently on purpose:

answer means what the mod does
valid the key is good and bound to you runs, and writes the offline stamp
invalid a real verdict from the server destroys the stamp; an already-running session needs two rejections a minute apart before it stops
network failure timeout, rate limit, server error, non-JSON, captive portal falls back on the stamp and says so

The last row is the important one. An outage or a rate limit is never reported as "you need a licence".

Offline grace

A successful check writes a signed stamp to ~/.bitchos/license.stamp. If hwic.dev cannot be reached, that stamp keeps you licensed for 72 hours. During grace the mod retries every 5 minutes and chat says:

licence server unreachable — running on your last check (N left)

When the server comes back: licence server is back — verified. If grace runs out with the server still down, the mod pauses with an explicit message. A real rejection destroys the stamp at once; grace is for outages, not for revoked keys.

Updates

The mod updates itself, in two halves, which is why a new build takes two restarts:

  1. Launch one. After the game starts, a background check asks hwic.dev for the latest version. If it is strictly newer, the jar is downloaded, its SHA-256 is verified against the advertised hash, the file is checked to be a real bitchos jar, and it is staged next to the running jar as bitchos.jar.new.
  2. Launch two. Before the game loads anything, the staged jar replaces the old one (kept as bitchos.jar.bak for a manual rollback). This is the only moment the jar is not open; on Windows a loaded jar cannot be replaced at all.

Any failure at any step leaves the installed jar untouched and the launch continues normally. To turn updating off, create an empty file named no-autoupdate in ~/.bitchos/.

Forge holds every jar in mods/ open for the whole session, so the mod cannot replace itself. On start it checks hwic.dev and, if a newer Forge build exists, tells you in chat to replace the jar. Download it from the redeem page and swap the file.

The chat greeting on join says which build you are on and whether it is the latest.

Managing your key

  • Link the key to your Discord account from the redeem page, then use /key in discord.gg/fkdr to check, unlink or reset it.
  • Boost keys expire when the boost does; the redeem page says so. Lifetime keys do not expire.
  • If your key leaks, reset it with /key before somebody validates it on their account.