Skip to main content

Agent Updates

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

Why Update?

Regular updates ensure you have the latest threat detection capabilities, performance improvements, and security patches.

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.

Enrollment Preserved

When updating an agent, credentials and configuration are preserved. No re-enrollment is required.

Windows Update​

# 1. Stop the service
Stop-Service "Castellan Agent"

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

# 3. Verify the new version
castellan-agent version

# 4. Start the service
Start-Service "Castellan Agent"
Enterprise Deployment

Use Group Policy, SCCM, or other deployment tools to push updates across your organization.

Enrollment Preservation​

When updating an agent:

What's PreservedWhat's Updated
✅ Credentials (Customer ID, API key)✅ Agent binary
✅ Configuration settings✅ Dependencies
✅ Enrollment status✅ Feature capabilities

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:

CheckExpected
Agent statusConnected (green dot)
Version columnNew version number
Events TodayIncreasing (events being collected)

4. Check Logs​

Review logs for any errors after the update:

Get-Content "C:\ProgramData\CastellanAI\logs\agent.log" -Tail 50

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:
curl -v https://api.castellanai.com
📋 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
  4. Completely uninstall and reinstall if needed

Update Best Practices​

Recommended Practices

Follow these guidelines for smooth agent updates.

PracticeDescription
Update RegularlyApply updates within 7 days of release for security patches
Test FirstUpdate a non-critical agent first to verify compatibility
Monitor After UpdateWatch the Portal for any issues after updating
Keep RecordsDocument which versions are deployed where
Use AutomationConsider using configuration management (Ansible, Puppet, etc.) for large deployments

Update Frequency​

Update TypeRecommendation
Security patchesApply immediately (within 24-48 hours)
Bug fixesApply within 7 days
Feature updatesApply within 30 days

What's Next?​

GuideDescription
Agent Health MonitoringMonitor agent status and performance
Agent TroubleshootingResolve common agent issues
SupportGet help from our support team