Agent Issues

Troubleshooting common agent startup, enrollment, and guard issues.

Agent Not Starting

Check Privileges

The agent requires root (macOS) or Administrator (Windows):

bash
# macOS
sudo bluesentinel

# Windows (PowerShell as Administrator)
.\bluesentinel.exe

Check Logs

  • macOS: /Library/Application Support/BlueSentinel/logs/bluesentinel.log
  • Windows: C:\ProgramData\BlueSentinel\logs\bluesentinel.log

Common Startup Errors

"Permission denied" — Agent not running as root/Administrator.

"Cannot connect to server" — Server URL is incorrect or port 5100 is blocked.

"Invalid enrollment token" — Token has expired or reached max uses. Generate a new token from the admin dashboard.

"Database locked" — The local SQLite database is locked by another process. Kill any orphan bluesentinel processes and restart.

Enrollment Fails

  1. Verify the enrollment token is still valid (check expiry and use count in dashboard)
  2. Verify the server URL is correct and accessible from the endpoint
  3. Check if the device is already enrolled (409 conflict error)
  4. Verify port 5100 is not blocked by a firewall

Guards Not Working

Check Guard Status

The heartbeat payload includes guard thread status. In the dashboard, go to the device detail page and check which guards show as running/stopped.

Guard Thread Died

If a guard thread crashes, the agent logs the exception but continues running other guards. Check the agent logs for stack traces.

OS-Level Enforcement Not Applied

The anti-tamper loop reapplies OS-level settings every 10 seconds. If settings are immediately reversed, check for conflicting Group Policy or MDM configurations.

Agent Using Too Much CPU

  • The browser guard MITM proxy can be CPU-intensive during heavy browsing. Consider setting the proxy port to 0 to disable it.
  • The file watcher can generate high load if monitoring large directories. Narrow the watch directory list.
  • The process guard scan interval may be too frequent. Increase the check interval in the policy.

Agent Offline

If a device shows as offline in the dashboard:

  1. Check if the agent process is running on the endpoint
  2. Verify network connectivity to the server
  3. Check the agent logs for connection errors
  4. The agent retries every 60 seconds — wait for the next heartbeat cycle