macOS Installation

Complete guide for installing the CastellanAI Agent on macOS.

Quick Install

Install using the package installer and grant Full Disk Access to enable complete security monitoring.

Prerequisites

Before installing, ensure you have:

• macOS 12 (Monterey) or later
• Apple Silicon or Intel processor
• Administrator access
• Network access to Worker API (outbound HTTPS on port 443)

---

Download

1. Log in to the Customer Portal
2. Navigate to Agents → Download
3. Select macOS and download the .pkg installer

---

Installation

📦 Package Installer

Package Installer

sudo installer -pkg CastellanAgent.pkg -target /

Or double-click the .pkg file and follow the installation wizard.

Gatekeeper Warning

If you see "CastellanAgent.pkg cannot be opened", right-click the file and select Open to bypass Gatekeeper.

🍺 Homebrew

Homebrew Installation (Coming Soon)

# Add CastellanAI tap
brew tap castellanai/tap

# Install the agent
brew install castellan-agent

Coming Soon

Homebrew installation will be available after initial launch.

---

Grant Full Disk Access

Required Step

The agent requires Full Disk Access to monitor security events. Without this permission, the agent cannot read system logs.

1. Open System Preferences (or System Settings on macOS 13+)
2. Navigate to Security & Privacy → Privacy → Full Disk Access
3. Click the lock icon and authenticate
4. Click + and add /Library/Application Support/CastellanAgent/Castellan.Agent
5. Ensure the checkbox is enabled

📸 Step-by-step with screenshots

1. Open System Preferences:

   • Click the Apple menu → System Preferences
   • Or use Spotlight: Cmd + Space, type "Security"

2. Navigate to Full Disk Access:

   • Click Security & Privacy
   • Select the Privacy tab
   • Select Full Disk Access in the left sidebar

3. Add the Agent:

   • Click the lock icon (bottom left) and enter your password
   • Click the + button
   • Navigate to /Library/Application Support/CastellanAgent/
   • Select Castellan.Agent and click Open

4. Verify:

   • Ensure the checkbox next to Castellan.Agent is checked

---

Configuration

Edit the configuration file:

sudo nano /Library/Application\ Support/CastellanAgent/appsettings.json

appsettings.json

{
  "AgentSettings": {
    "CustomerId": "your-customer-id",
    "HubUrl": "https://api.castellanai.com/hubs/agent-communication"
  }
}

---

Start the Service

The agent runs as a launchd service:

# Load and start the service
sudo launchctl load /Library/LaunchDaemons/com.castellanai.agent.plist

# The service starts automatically on boot

---

Verify Installation

Check Service

# Check if service is running
sudo launchctl list | grep castellan

# Expected output shows PID and status:
# 12345  0  com.castellanai.agent

View Logs

# View real-time logs
tail -f ~/Library/Logs/CastellanAgent/agent.log

# Or use Console.app
# Console → Search for "CastellanAgent"

# Or use log command
sudo log show --predicate 'process == "CastellanAgent"' --last 1h

Agent CLI

# Check agent status
castellan-agent status

# Check version
castellan-agent version

---

Uninstallation

🗑️ How to Uninstall

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

# Remove application files
sudo rm -rf /Library/Application\ Support/CastellanAgent

# Remove launch daemon
sudo rm /Library/LaunchDaemons/com.castellanai.agent.plist

# Remove logs (optional)
rm -rf ~/Library/Logs/CastellanAgent

---

Troubleshooting

❌ Service won't start

1. Check launchd errors:

   sudo launchctl error com.castellanai.agent

2. Run manually to see errors:

   /Library/Application\ Support/CastellanAgent/Castellan.Agent

3. Check Console.app for crash reports

🔒 Permission denied errors

Full Disk Access is required. Verify the agent has FDA:

1. Go to System Preferences → Security & Privacy → Privacy → Full Disk Access
2. Ensure Castellan.Agent is listed and checked
3. If not present, add it manually

After granting FDA, restart the service:

sudo launchctl unload /Library/LaunchDaemons/com.castellanai.agent.plist
sudo launchctl load /Library/LaunchDaemons/com.castellanai.agent.plist

🔌 Agent not connecting

1. Test network connectivity:

   curl -v https://api.castellanai.com

2. Check for proxy settings:

   echo $http_proxy $https_proxy

3. Verify DNS:

   nslookup api.castellanai.com

🛡️ Gatekeeper blocking installation

If you see "cannot be opened because it is from an unidentified developer":

1. Right-click the .pkg file
2. Select Open from the context menu
3. Click Open in the dialog

Or temporarily allow from anywhere:

sudo spctl --master-disable
# Install the agent
sudo spctl --master-enable

---

What's Next?

Guide	Description
Configuration	Advanced agent configuration options
Health Monitoring	Monitor agent status and performance
Troubleshooting	Resolve common issues