Linux Installation

Complete guide for installing the CastellanAI Agent on Linux.

Quick Install

Most Linux distributions can install the agent with a single package command. Choose your distribution below for specific instructions.

Prerequisites

Before installing, ensure you have:

• Ubuntu 20.04+, Debian 11+, RHEL 8+, or CentOS Stream 8+
• Root or sudo 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 your distribution:
   • Debian/Ubuntu: .deb package
   • RHEL/CentOS: .rpm package

---

Installation

Debian/Ubuntu

Debian/Ubuntu Installation

# Install the .deb package
sudo dpkg -i castellan-agent_1.0.0_amd64.deb

# If dependencies are missing, run:
sudo apt-get install -f

Alternative: APT Repository

# Add CastellanAI repository (coming soon)
curl -fsSL https://packages.castellanai.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/castellanai.gpg
echo "deb [signed-by=/usr/share/keyrings/castellanai.gpg] https://packages.castellanai.com/apt stable main" | sudo tee /etc/apt/sources.list.d/castellanai.list
sudo apt update
sudo apt install castellan-agent

RHEL/CentOS

RHEL/CentOS Installation

# Install the .rpm package
sudo rpm -i castellan-agent-1.0.0.x86_64.rpm

# Or using dnf/yum:
sudo dnf install castellan-agent-1.0.0.x86_64.rpm

Alternative: YUM Repository

# Add CastellanAI repository (coming soon)
sudo cat > /etc/yum.repos.d/castellanai.repo << EOF
[castellanai]
name=CastellanAI Repository
baseurl=https://packages.castellanai.com/yum/stable
enabled=1
gpgcheck=1
gpgkey=https://packages.castellanai.com/gpg
EOF
sudo dnf install castellan-agent

---

Configuration

Edit the configuration file:

sudo nano /etc/castellan-agent/appsettings.json

/etc/castellan-agent/appsettings.json

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

File Permissions

Ensure the configuration file has restricted permissions:

sudo chmod 600 /etc/castellan-agent/appsettings.json
sudo chown root:root /etc/castellan-agent/appsettings.json

---

Start the Service

# Enable agent to start on boot
sudo systemctl enable castellan-agent

# Start the agent now
sudo systemctl start castellan-agent

---

Verify Installation

Check Service

# Check service status
sudo systemctl status castellan-agent

# Expected output:
# ● castellan-agent.service - CastellanAI Security Agent
#      Loaded: loaded (/etc/systemd/system/castellan-agent.service; enabled)
#      Active: active (running)

View Logs

# View recent logs
sudo journalctl -u castellan-agent -f

# View last 50 lines
sudo journalctl -u castellan-agent -n 50

# Or check log files directly
sudo tail -f /var/log/castellan-agent/agent.log

Agent CLI

# Check agent status
castellan-agent status

# Check version
castellan-agent version

---

Uninstallation

Debian/Ubuntu

# Stop the service
sudo systemctl stop castellan-agent

# Remove the package
sudo dpkg -r castellan-agent

# Remove configuration (optional)
sudo rm -rf /etc/castellan-agent

RHEL/CentOS

# Stop the service
sudo systemctl stop castellan-agent

# Remove the package
sudo rpm -e castellan-agent

# Or using dnf:
sudo dnf remove castellan-agent

---

Troubleshooting

❌ Service won't start

1. Check logs for errors:

   sudo journalctl -u castellan-agent -n 50

2. Verify configuration syntax:

   sudo cat /etc/castellan-agent/appsettings.json | python3 -m json.tool

3. Check SELinux/AppArmor:

   # Check SELinux status
   sestatus
   
   # Temporarily disable for testing
   sudo setenforce 0

🔌 Agent not connecting

1. Test network connectivity:

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

2. Check firewall:

   # UFW (Ubuntu)
   sudo ufw status
   
   # firewalld (RHEL/CentOS)
   sudo firewall-cmd --list-all

3. Verify DNS resolution:

   nslookup api.castellanai.com

📝 Permission denied errors

The agent needs read access to system logs:

# Add agent to adm group (for syslog access)
sudo usermod -a -G adm castellan-agent

# Or adjust log permissions
sudo chmod 644 /var/log/auth.log

---

What's Next?

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