---
title: "Heartbeat"
description: "How Asphyxia confirms a player's client is still protected, and why it can't be faked."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.asphyxia.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Heartbeat

The heartbeat is how your server knows a player's anti-cheat is still running.
Every protected client checks in on a regular schedule. If those check-ins stop,
or one of them doesn't look right, the server stops trusting that player.

## Why it exists

Client-side detections are only useful while they're actually running. The
first thing most cheat tools try is to stop or strip them out — and if that
worked silently, a cheater would look identical to a clean player from the
server's point of view.

The heartbeat closes that gap. It flips the question around: instead of waiting
to hear about a problem, the server *expects* to hear from every client on a
schedule, and treats silence as the problem.

## What a check-in carries

Each heartbeat tells the server two things:

1. **That the client is alive and unmodified.**
2. **Anything the client's detections have found** since the last check-in.

That second part is why detections don't need their own channel — they ride
along on a message the server is already verifying.

## Why it can't be faked

Every heartbeat is **signed**. When a player connects, the server issues that
one session its own set of credentials, derived from your server's shared
secret. The client signs each check-in with them, and the server verifies the
signature before it believes a single word of the contents.

That means a forged or replayed heartbeat fails verification, because producing
a valid one requires credentials that only that client and your server hold.
Each check-in is also single-use, so capturing a real one and sending it again
later doesn't work either.

If verification fails, the player is banned — a heartbeat that doesn't verify
means someone was tampering with the connection between client and server, not
that something went wrong.

> **Note**
>
> Asphyxia never trusts a client's word about its own health. The signature only
> proves the message really came from that session; what the message *claims* is
> still evaluated on the server.

## When a player stops checking in

A missed check-in isn't automatically malicious — a frame hitch, a bad
connection, or a heavy resource can all delay one. So Asphyxia nudges before it
punishes:

1. The player misses their expected window.
2. The server asks them directly for a check-in, and waits.
3. It retries a few times.
4. If nothing comes back, the player is disconnected with a message telling
   them they can reconnect.

That last step is a **disconnect, not a ban**. Someone whose game froze gets to
come back; someone who removed the anti-cheat gets dropped every time until
they stop.

The missed window is still counted against that player's session, and shows up
on their record in the [Players page](/website/players) as a failed heartbeat.
A player with a handful of failures over a long session is usually just on a
poor connection. A player who fails constantly is worth a closer look.

## On join

New players get a short grace period to finish loading before the first
check-in is expected. If a client joins and never checks in at all within that
window, it's disconnected — that's the case where the anti-cheat never started
on their machine.

## What you'll see

Normal operation is silent. The messages you may see are:

```text
[Asphyxia.] › ⚠ warn  Disconnected Playername (ID 12) — their client stopped
                  responding to the anti-cheat.

[Asphyxia.] › ⚠ warn  Disconnected Playername (ID 12) — their client never
                  checked in with the anti-cheat after joining.
```

Occasional lines like these are normal on any busy server. A sudden burst of
them usually means a resource on your server is hanging the client, not that
you're being attacked — see
[Troubleshooting](/anticheat/troubleshooting).

Source: https://docs.asphyxia.dev/anticheat/heartbeat/index.mdx