What does "the agent checks in" mean?

The octoja agent holds a persistent realtime connection to the server and uses keepalives to confirm it is still there — a "check-in" is one such keepalive.

Written By Erdinc Akay

Last updated About 2 months ago

What "checking in" means

The octoja agent is a small program that runs on each monitored device. It holds a persistent realtime connection to the octoja server and uses keepalives to confirm it is still there. This is called checking in.

Each check-in also carries data — the latest check results, inventory updates, and anything else the server needs to know. If the agent stops checking in, octoja assumes the device might be offline and changes the status indicator so you can spot the problem quickly.

How octoja shows this on the device tile

The coloured ring around a device tile tells you how recently the agent last checked in:

Ring colourWhat it means
Green (with glow)Online — checked in within the last few seconds
YellowOffline — last check-in less than 1 hour ago
RedLast check-in was 1 hour to 7 days ago
GreyMore than 7 days — the device is considered inactive

On the device detail page you can see the exact timestamps: Last Seen (the most recent connection) and Last Reported (the most recent inventory report). The detail page hero also shows a pulsing ring for servers (Windows Server, Linux Server) whose last check-in was 1 to 7 days ago.

Why a device might stop checking in

There are a few common reasons:

  • The device is turned off or sleeping. Laptops that are closed overnight will stop checking in until they wake up. This is normal.
  • The network is down. If the device cannot reach the internet, it cannot reach octoja either. The agent will resume checking in automatically once connectivity returns.
  • The agent service was stopped or uninstalled. This is less common but worth checking if a device stays grey for days.

How the agent behaves on your network

  • Firewalls. The agent connects outward to the octoja server over port 443 (HTTPS). In environments with strict outbound filtering, allow port 443 to the octoja server.
  • Bandwidth. Check-ins are tiny. Even hundreds of devices checking in every few seconds stay well below normal background traffic.
  • Reconnection. If the agent loses connection temporarily, it reconnects on its own as soon as the network is back.