Agent Configuration

Configure your CastellanAI agents to optimize security monitoring for your environment.

Overview

CastellanAI agents are designed to work optimally out of the box with zero configuration required. When you install an agent using an enrollment token from the Portal, all necessary settings are automatically configured.

tip

Most users never need to modify agent settings. Agents are automatically configured during enrollment and receive updates from the Portal.

Automatic Configuration

When an agent enrolls with your account, it automatically receives:

Setting	What It Does
Customer ID	Links the agent to your account
Worker URL	Connects to your secure CastellanAI backend
API Key	Authenticates the agent
Smart Filtering	Optimizes data transmission (enabled by default)

Viewing Your Agents

To view your enrolled agents:

1. Log in to your Customer Portal
2. Click Agents in the header navigation
3. View your agents with their status, platform, and activity

The Agents page showing enrolled agents with status, platform, last seen, and events processed.

The Agents page shows:

Column	Description
Hostname	The machine name where the agent is installed
Platform	Windows, Linux, or macOS
Status	Connected, Disconnected, Pending, Updating, or Error
IP Address	The agent's network address
Version	Installed agent version
Last Seen	When the agent last reported
Events Today	Number of security events processed

Smart Filtering

Smart Filtering is CastellanAI's intelligent event prioritization system that reduces network traffic by 95-98% while ensuring critical threats are detected immediately.

How It Works

Priority Level	Score Threshold	What Happens
Critical	≥90	Sent immediately to dashboard
High	≥70	Batched and sent every few seconds
Medium	≥40	Analyzed locally on the agent
Low	<40	Filtered out (routine noise)

Smart Filtering is enabled by default and requires no configuration.

Event Collection

Agents collect events from multiple sources depending on the operating system:

Windows

• Security Event Log
• System Event Log
• Application Event Log
• PowerShell Event Log

Linux

• Syslog
• Auth log
• Kernel messages

macOS

• Unified logging system
• Security events

Advanced Configuration

For advanced users or special deployment scenarios, agents can be configured through a local configuration file.

warning

Manual configuration is only recommended for advanced deployments. Most users should rely on automatic enrollment configuration.

Configuration File Location

Platform	Location
Windows	C:\ProgramData\CastellanAI\appsettings.json
Linux	/etc/castellanai/appsettings.json
macOS	/Library/Application Support/CastellanAI/appsettings.json

Available Settings

{
  "Agent": {
    "HeartbeatInterval": 30,
    "ReconnectInterval": 5,
    "EventCollection": {
      "CollectSecurity": true,
      "CollectSystem": true,
      "CollectApplication": true,
      "CollectPowerShell": true,
      "MaxEventsPerSecond": 1000,
      "BufferSize": 10000
    },
    "SmartFiltering": {
      "Enabled": true,
      "DataReductionTarget": 95,
      "CriticalThreshold": 90,
      "HighThreshold": 70,
      "MediumThreshold": 40
    }
  }
}

Setting Descriptions

Setting	Default	Description
HeartbeatInterval	30	Seconds between agent heartbeats
ReconnectInterval	5	Seconds to wait before reconnection attempts
CollectSecurity	true	Monitor Security event log
CollectSystem	true	Monitor System event log
CollectApplication	true	Monitor Application event log
CollectPowerShell	true	Monitor PowerShell event log
MaxEventsPerSecond	1000	Rate limit for event processing
BufferSize	10000	Maximum events to buffer locally
SmartFiltering.Enabled	true	Enable intelligent event filtering
DataReductionTarget	95	Target percentage of data reduction

Recommended Settings by Environment

Environment	Recommendation
Production Servers	Use defaults (all channels monitored, Smart Filtering enabled)
Workstations	Use defaults (optimal for end-user devices)
Development	Consider reducing MaxEventsPerSecond to minimize noise
High-Security	Use defaults (Smart Filtering ensures critical events are prioritized)

Troubleshooting

Agent Not Appearing in Portal

1. Verify the agent service is running
2. Check network connectivity to CastellanAI servers
3. Ensure the enrollment token was valid and not expired
4. Review agent logs for error messages

Agent Showing Disconnected

1. Check if the agent service is running on the endpoint
2. Verify network connectivity (firewalls, proxies)
3. Restart the agent service if needed

Events Not Being Collected

1. Verify the event log channels are enabled in the configuration
2. Check that the agent has permission to read event logs
3. Review MaxEventsPerSecond if experiencing high volume

What's Next?

• Agent Health Monitoring - Monitor your agents' status and performance
• Agent Troubleshooting - Resolve common agent issues