Coolify logoCoolify
Cloud

Sentinel

Sentinel is the Rust-based lightweight agent Coolify runs on a connected server. It reports server and container health to your Coolify instance and can collect the data used by CPU and memory charts.

The short version

Coolify runs Sentinel as the coolify-sentinel container on each eligible server. Sentinel sends authenticated status updates to Coolify and stores metric history locally when metrics are enabled.

Sentinel is not available on every server

Sentinel is not available on build servers or Docker Swarm servers. Validate a standard Docker server before configuring Sentinel.

What Sentinel reports

Sentinel supplies the preferred status path from a connected server to Coolify.

Server heartbeatKeeps the server marked Sentinel In Sync while authenticated updates continue to arrive.
Container stateReports running state and Docker health information for resources on the server.
Disk usageIncludes usage for the server root filesystem in regular status updates.
CPU and memory historyCollects server and supported resource metrics when the separate metrics setting is enabled.

How Sentinel works

From Sentinel to Coolify

The container reads local Docker and host information, then sends the result to the Coolify control plane.

1

Start coolify-sentinel

2

Read host and Docker state

3

Send an authenticated update

4

Refresh the server heartbeat

5

Store metric samples when enabled

  • Coolify starts Sentinel on the selected connected server.
  • The container reads server and container information without publishing its API on a host port.
  • Sentinel sends updates to Coolify URL using Sentinel token at the configured Push interval.
  • Coolify shows Sentinel In Sync while the heartbeat remains current.
  • Coolify queries the API from inside the container when it needs metric history stored under /data/coolify/sentinel.

When the heartbeat becomes stale, Coolify marks Sentinel Out of Sync and uses SSH-based checks until Sentinel resumes.

New server settings enable Sentinel by default, but an existing server can remain disabled. Metrics collection is separately disabled by default.

Enable or sync Sentinel

  1. Open Servers and select the server.
  2. Open Sentinel > Configuration.
  3. If Sentinel is disabled, select Enable Sentinel.
  4. If Coolify shows Out of Sync, select Sync. If Sentinel is already live, the same action is labeled Restart.
  5. Wait for the server header to show Sentinel In Sync.

Sentinel needs a URL it can reach from the connected server. If Coolify URL is empty, configure the instance URL, return to Sentinel, and sync again.

Sentinel settings

SettingDefaultAccepted value and effect
Coolify URLGenerated from the Coolify instance settingsA full URL. Sentinel sends its updates to this address. Changing the instance URL updates remote servers that use the generated URL.
Sentinel tokenGenerated by CoolifyA required authentication token. Use Regenerate instead of creating your own token.

Collection rate, history retention, and push interval are configured on the server's Charts page. See Sampling and retention.

Use Apply and restart after changing the Sentinel custom image. Sentinel runs with Docker's unless-stopped restart policy. Coolify restarts unhealthy agents or agents that stop pushing, and shows the last push error while Sentinel is out of sync.

Treat the Sentinel token as a secret. Coolify encrypts it in the instance database and sends it to the Sentinel container as an environment variable.

Sentinel and metrics

Sentinel and metrics have separate controls.

Status reporting and metric history

Keep Sentinel enabled for status reporting even when you do not need historical charts.

Sentinel without metrics

  • Sends heartbeats to Coolify
  • Reports container state and Docker health information
  • Reports root filesystem usage
  • Does not collect CPU and memory history

Sentinel with metrics

  • Keeps all server and container status reporting
  • Collects server CPU and memory history
  • Collects metrics for supported resource containers
  • Uses local disk space according to the sampling rate and retention period

Enable or disable the collector from Servers > [server] > Charts. Disabling Sentinel also disables metrics. For chart scope, retention, and resource limitations, read Metrics.

Troubleshooting

Overview

Understand how Coolify monitors server availability, container state, disk usage, backups, and CPU and memory metrics.

Metrics

Enable and view Coolify CPU and memory metrics for servers, applications, and standalone databases.

On this page

Sentinel
What Sentinel reports
How Sentinel works
Enable or sync Sentinel
Sentinel settings
Sentinel and metrics
Troubleshooting