Troubleshooting

Common issues and solutions for CyberCage.

Installation Issues

Installer Fails

Symptom: curl -sSL https://get.cybercage.io | sh fails

Solutions:

1. Check internet connection
2. Verify curl is installed: curl --version
3. Try manual download: curl -O https://get.cybercage.io/install.sh
4. Check system requirements (OS, architecture)

Permission Denied

Symptom: "Permission denied" during installation

Solution: Run with sudo:

curl -sSL https://get.cybercage.io | sudo sh

Daemon Issues

Daemon Won't Start

Symptom: cybercage status shows daemon not running

Solutions:

# Check current status
cybercage status

# Force a sync to refresh state
cybercage sync --force

# Reset daemon (clears caches)
cybercage reset

# Restart daemon using OS service manager
sudo systemctl restart cybercage  # Linux
sudo launchctl restart com.cybercage.daemon  # macOS

Daemon Not Syncing

Symptom: Last sync time is stale (>5 minutes)

Solutions:

1. Check connection: cybercage ping
2. Force sync: cybercage sync --force
3. Verify API key exists: ls ~/.cybercage/config.yml
4. Check firewall rules (port 443 outbound must be open)
5. Reset daemon if needed: cybercage reset

Viewing Logs

Since the CLI doesn't have a logs command, access logs through:

Dashboard:

• Go to Organization → Audit Logs in the Dashboard
• Filter by device/user to find relevant entries

System Logs:

• macOS: Console.app → Search for "cybercage"
• Linux: journalctl -u cybercage -n 50
• Windows: Event Viewer → Applications

Application Detection Issues

IDE Not Detected

Symptom: Application doesn't appear in Dashboard

Solutions:

1. Verify IDE is supported (check supported platforms list)
2. Check config file exists at expected path
3. Run cybercage status to see detected applications
4. Force sync: cybercage sync --force
5. Wait 5 minutes for detection scan
6. Restart daemon using OS service manager

Protection Fails

Symptom: Protection toggle stays OFF or shows Error

Solutions:

1. Check file permissions on application config
2. Look for syntax errors in original config
3. View error details in Dashboard → Applications → Activity
4. Try cybercage reset to clear any cached state
5. Contact support with cybercage status output

Server Approval Issues

Server Stuck in Pending

Symptom: Server shows "Pending" but no one approved it

Solutions:

1. Verify sync is working: cybercage status
2. Force sync to get latest approvals: cybercage sync --force
3. Contact your admin to review and approve in Dashboard
4. Check if server hash changed (requires new approval)

Approved Server Still Blocked

Symptom: Server is Approved but user sees block error

Solutions:

1. Restart application (config needs reload)
2. Force sync: cybercage sync --force
3. Wait 30 seconds for changes to propagate
4. Check if policy overrides approval in Dashboard
5. Run cybercage status to verify server appears as approved

Performance Issues

High Latency

Symptom: Slow responses from MCP servers

Solutions:

1. Check Hub connectivity: cybercage ping
2. Verify in Dashboard → Analytics for cache hit rates
3. Check if LLM analysis is enabled (Builder plan feature)
4. Consider adjusting security policies for performance

High CPU Usage

Symptom: Daemon using excessive CPU

Solutions:

1. Check cybercage status for abnormal activity
2. Reset daemon to clear state: cybercage reset
3. Check for rapid config file changes
4. Update to latest daemon version through Dashboard

Getting Help

For Individual Developers

First Line of Support:

• Contact your organization administrator
• They can review logs, adjust policies, and escalate issues

Information to Provide:

# Save system status
cybercage status > cybercage-status.txt

• Share the status file with your admin
• Describe what you were trying to do
• Include any error messages

For Organization Administrators

Dashboard Support:

• Access in-app support from your Dashboard
• Live chat available for Builder and Enterprise plans

Email Support:

• contact@cybercage.io

Information to Include:

# Collect system information
cybercage status > status.txt

• Organization name and ID
• Screenshots from Dashboard
• Steps to reproduce the issue
• Status output from affected machines

Emergency Support

For critical security incidents (Enterprise customers):

• Security Hotline: Contact provided in your Dashboard
• Email: contact@cybercage.io
• Include:
  • Threat details and severity
  • Number of affected users
  • Immediate business impact

Common CLI Commands Reference

Available Commands

# Check system status
cybercage status

# Test connectivity
cybercage ping

# Force synchronization
cybercage sync --force

# Reset daemon and clear caches
cybercage reset

What These Commands Show

cybercage status:

• Daemon online/offline state
• Hub connection status
• Protected applications list
• Monitored servers
• Last sync timestamp

cybercage ping:

• Simple connectivity check
• Response time to Hub

cybercage sync:

• Forces immediate sync with Hub
• Shows number of apps/servers discovered
• Updates approvals and policies

cybercage reset:

• Clears internal caches
• Triggers fresh sync
• Useful for resolving stuck states

Platform-Specific Issues

macOS

Gatekeeper Blocks Installation:

• System Preferences → Security & Privacy → Allow cybercage

LaunchDaemon Issues:

sudo launchctl list | grep cybercage
sudo launchctl restart com.cybercage.daemon

Linux

Systemd Service Issues:

systemctl status cybercage
sudo systemctl restart cybercage
journalctl -u cybercage -f  # Follow logs

SELinux/AppArmor:

• May need policy adjustments for daemon
• Contact support for configuration help

Windows

Service Management:

• Use Services app to check CyberCage service
• Run as Administrator if permission issues
• Check Windows Defender exceptions

Next Steps

• Installation Guide - Clean installation steps
• Configuration - Setup options
• Dashboard Guide - Using the web interface
• FAQ - Frequently asked questions