Agent Troubleshooting

Use the guidance below to diagnose and resolve common agent issues.

Agent Status: Offline

If an agent appears Offline, it is not currently communicating with the Verax server.

Common Causes

• The endpoint is powered off

• Network connectivity issues

• Required ports (TCP 3000 and TCP 3002) are blocked

• The verax-agent service is not running

Troubleshooting Steps

1. Verify the endpoint is powered on.

2. Check network connectivity to the Verax server.

   Windows (PowerShell):

   Test-NetConnection <VERAX_SERVER> -Port 3000
   Test-NetConnection <VERAX_SERVER> -Port 3002

   macOS / Linux:

   nc -zv <VERAX_SERVER> 3000
   nc -zv <VERAX_SERVER> 3002

   If the connection fails, review firewall rules and routing configuration.

3. Ensure the agent service is running.

   • Windows: Check the verax-agent service in Services.

   • macOS / Linux:

     sudo systemctl status verax-agent

   Restart if necessary:

   sudo systemctl restart verax-agent

4. Reinstall the agent if needed using a valid installation token.

Agent Status: Online but Health: Unhealthy

If an agent is Online but Unhealthy, it is connected to the Verax server but not fully operational.

Common Causes

• Verax CA certificate is not installed or not trusted

• Hosts file is not properly configured

• DNS cache was not flushed after configuration changes

• Required environment variables are missing

• Traffic is not properly redirected through Verax

Troubleshooting Steps

1. Verify the Verax CA certificate is installed and trusted.

2. Confirm hosts file entries are present and correct.

3. Flush DNS cache after making changes.

   Windows:

   ipconfig /flushdns

   macOS:

   sudo dscacheutil -flushcache
   sudo killall -HUP mDNSResponder

4. Verify required environment variables (if applicable).

5. Restart the verax-agent service after correcting configuration.

Agent Is Online and Healthy but No Activity Is Recorded

If an agent shows as Online and Healthy but no activity appears:

• Confirm the endpoint is actively using supported AI tools

• Verify traffic redirection is correctly configured

• Ensure the correct Verax server address was used during installation

If issues persist after completing these steps, contact Verax Support and provide:

• Operating system

• Agent version

• Verax server address

• Description of the observed behavior

Clean, focused, and strictly troubleshooting-only.