Skip to main content

Agent Updates

Keep your CastellanAI agents up-to-date with the latest security features, performance improvements, and bug fixes.

Checking Agent Versions​

In the Portal​

View agent versions from the Customer Portal:

  1. Log in to your Customer Portal
  2. Click Agents in the header navigation
  3. The Version column shows each agent's installed version

Compare versions across your fleet to identify agents that need updating.

On the Endpoint​

Check the installed version directly on any endpoint:

castellan-agent version

This displays:

  • Agent version number
  • Platform (Windows, Linux, or macOS)
  • Runtime version

Updating Agents​

Currently, agents are updated by reinstalling the latest version. The agent preserves its enrollment during the update process.

Windows Update​

# Stop the service
Stop-Service "Castellan Agent"

# Download and run the latest installer
# (Get installer from Portal or your deployment system)

# Verify the new version
castellan-agent version

# Start the service
Start-Service "Castellan Agent"

Linux Update​

# Stop the service
sudo systemctl stop castellan-agent

# Install the new version (preserves enrollment)
# Method depends on your deployment:
# - Package manager: sudo apt upgrade castellan-agent
# - Manual: Download and extract new binary

# Verify the new version
castellan-agent version

# Start the service
sudo systemctl start castellan-agent

macOS Update​

# Stop the service
sudo launchctl unload /Library/LaunchDaemons/com.castellanai.agent.plist

# Install the new package
# (Download from Portal or deployment system)
sudo installer -pkg castellan-agent-latest.pkg -target /

# Verify the new version
castellan-agent version

# Start the service
sudo launchctl load /Library/LaunchDaemons/com.castellanai.agent.plist

Enrollment Preservation​

When updating an agent:

  • Credentials are preserved - The agent remains enrolled with your account
  • Configuration is maintained - Settings carry over to the new version
  • No re-enrollment required - Just update and restart

If you need to re-enroll for any reason:

castellan-agent enroll --token YOUR_TOKEN --portal-url https://api.castellanai.com --force

Post-Update Verification​

After updating, verify the agent is working correctly:

1. Check Version​

castellan-agent version

Confirm the version matches the expected update.

2. Check Status​

castellan-agent status

Verify the agent shows as enrolled with correct credentials.

3. Check Portal​

In the Customer Portal, verify:

  • Agent shows Connected status (green dot)
  • Version column shows the new version
  • Events are being collected (Events Today increasing)

4. Check Logs​

Review logs for any errors after the update:

Windows:

C:\ProgramData\CastellanAI\logs\agent.log

Linux:

sudo journalctl -u castellan-agent -n 50

macOS:

sudo tail -f /Library/Logs/CastellanAI/agent.log

Update Troubleshooting​

Agent Won't Start After Update​

  1. Check that the service is installed correctly
  2. Review agent logs for startup errors
  3. Verify configuration file wasn't corrupted
  4. Try running manually to see errors: 
    castellan-agent run

Agent Shows Disconnected After Update​

  1. Verify network connectivity to CastellanAI servers
  2. Check firewall rules for port 443 (HTTPS)
  3. Test connectivity: 
    # Linux/macOS
    curl -v https://api.castellanai.com

    # Windows
    Test-NetConnection -ComputerName api.castellanai.com -Port 443

Version Didn't Change​

  1. Ensure you stopped the old service before updating
  2. Verify you installed to the correct location
  3. Check for multiple installations that may conflict

Update Best Practices​

  • Update Regularly - Apply updates within 7 days of release for security patches
  • Test First - Update a non-critical agent first to verify compatibility
  • Monitor After Update - Watch the Portal for any issues after updating
  • Keep Records - Document which versions are deployed where
  • Use Automation - Consider using configuration management (Ansible, Puppet, etc.) for large deployments

What's Next?​