Documentation

Everything you need to get started with Spyd

Quick Start

Installation BETA

curl -fsSL spyd.sh | sh

One-line installation for Linux and macOS. Downloads and installs the latest version automatically.

Initialize Configuration

spyd init

Interactive setup wizard that guides you through:

  • AI provider configuration (OpenAI or Ollama)
  • Monitoring thresholds (CPU, Memory, Disk)
  • Storage settings
  • Alert channels (optional)

Start Monitoring

spyd start

Starts the background daemon that collects metrics and monitors your system.

Check Status

spyd status

Shows current system metrics, daemon status, and recent AI analysis.

Command Reference

Core Commands

start

spyd start

Starts the Spyd daemon in the background. The daemon collects system metrics every 60 seconds (configurable) and triggers AI analysis when thresholds are exceeded.

stop

spyd stop

Gracefully stops the running daemon. Completes the current metric collection cycle before shutting down.

restart

spyd restart

Stops and restarts the daemon. Useful after configuration changes.

status

spyd status

Displays current system health snapshot including CPU, memory, disk usage, load average, and the most recent AI analysis.

# Output includes: ● Daemon: Running (PID: 12345) 📊 CPU: 45.2% | Memory: 62.1% | Disk: 55.3% 🕐 Load: 1.2, 0.8, 0.6 🤖 AI: Last checked 2m ago - System healthy

watch

spyd watch [-i INTERVAL]

Live dashboard that auto-updates every 2 seconds (or custom interval).

# Update every 5 seconds spyd watch -i 5

daemon

spyd daemon

Runs daemon in foreground with verbose logging. Useful for debugging or running in Docker/systemd.

Monitoring & Logs

logs

spyd logs [--follow] [--tail N]

View daemon logs with optional live following.

# Show last 100 lines spyd logs --tail 100 # Follow logs in real-time spyd logs --follow

alerts

spyd alerts [--all] [--severity LEVEL]

List recent alerts with AI analysis.

# Show all alerts (including acknowledged) spyd alerts --all # Filter by severity spyd alerts --severity critical

Configuration

configure ai

spyd configure ai [flags]

Update AI provider settings. Shows full configuration summary when run without flags.

# Show current AI configuration spyd configure ai # Enable/disable AI command execution spyd configure ai --command-enable spyd configure ai --command-disable # Update provider settings spyd configure ai --provider openai --model gpt-4o-mini

configure monitoring

spyd configure monitoring

Interactive configuration for monitoring thresholds (CPU, Memory, Disk, Load Average).

configure alerts

spyd configure alerts [--channel CHANNEL]

Set up notification channels (Email, Slack, Telegram, Webhook, Desktop). Use --channel flag to configure a specific channel directly.

# Interactive mode (all channels) spyd configure alerts # Configure specific channel spyd configure alerts --channel telegram spyd configure alerts --channel email spyd configure alerts --channel slack

configure show

spyd configure show

Display complete configuration summary including AI settings, monitoring thresholds, alert channels, and storage settings.

Utility Commands

upgrade

spyd upgrade

Upgrade to the latest version. Automatically stops daemon, downloads new binary, and provides next steps.

uninstall

spyd uninstall [--yes]

Complete uninstallation with confirmations. Use --yes to skip prompts.

version

spyd version [--verbose]

Show version information. Use --verbose for detailed build info.

Advanced Analysis (AI-Powered)

anomalies

spyd anomalies [--metric TYPE] [--severity LEVEL]

View detected anomalies from baseline learning system. Spyd learns normal behavior patterns and detects deviations.

# View all anomalies spyd anomalies # Filter by metric type spyd anomalies --metric cpu # Filter by severity spyd anomalies --severity high

baselines

spyd baselines [--metric TYPE]

View learned statistical baselines from historical system metrics. Shows mean, standard deviation, and expected ranges.

# View all baselines spyd baselines # Filter by metric spyd baselines --metric memory

baseline-status

spyd baseline-status

Show baseline learning status and progress. Indicates how much data has been collected for accurate anomaly detection.

patterns

spyd patterns [--metric TYPE]

View detected usage patterns. Identifies recurring patterns like daily peaks, weekend behavior, or scheduled tasks.

# View all patterns spyd patterns # Filter by metric spyd patterns --metric disk

correlations

spyd correlations [--strength LEVEL]

View detected correlations between different system metrics. Helps understand which metrics influence each other.

# View all correlations spyd correlations # Filter by strength spyd correlations --strength strong

predictions

spyd predictions [--type TYPE]

View predictive forecasts for disk space, memory leaks, and resource exhaustion. Get early warnings before problems occur.

# View all predictions spyd predictions # Filter by type spyd predictions --type disk_full

cascading

spyd cascading [--hours N]

View cascading failure events. Detects when one system issue triggers others in a chain reaction.

# View recent cascading events spyd cascading # Show events from last 12 hours spyd cascading --hours 12

events

spyd events [SUBCOMMAND]

View log intelligence and error patterns. Detects OOM kills, segfaults, and error clusters from system logs.

# List detected log events spyd events list # Show error pattern clusters spyd events patterns

services

spyd services [SUBCOMMAND]

Manage service health monitoring. Auto-discovers systemd services, tracks uptime, response times, and health status. Supports incident management and historical check data.

# List all monitored services with status spyd services list # Show detailed status for a service spyd services status ssh spyd services status nginx # View recent health checks spyd services checks nginx --hours 24 spyd services checks ssh --hours 1 # View all active incidents spyd services incidents # Calculate uptime percentage spyd services uptime nginx --hours 24 spyd services uptime mysql --hours 168 # Weekly

Configuration

Configuration file location: ~/.config/spyd/config.yaml

AI Configuration

ai: provider: openai # or ollama api_key: sk-... model: gpt-4o-mini timeout: 30 # seconds enable_command_execution: true # Allow AI to run diagnostic commands
Note: AI command execution is enabled by default. The AI can only run safe, read-only commands (ps, df, tail, etc.) to investigate issues. All commands are whitelisted and audited.

Monitoring Configuration

monitoring: interval: 60 # Check every 60 seconds cpu_threshold: 80 # Alert at 80% CPU mem_threshold: 85 # Alert at 85% memory disk_threshold: 90 # Alert at 90% disk load_threshold: 2.0 # Alert at load average 2.0

Alert Configuration

alerts: enabled: true min_level: warning # info, warning, or critical dedup: true dedup_window: 15 # minutes

Storage Configuration

storage: db_path: ~/.local/share/spyd/spyd.db retention_days: 30 # Keep data for 30 days max_db_size_mb: 500 # Max database size

Alert Channels

Spyd supports multiple notification channels. Configure them using spyd configure alerts or by editing the config file.

📧

Email

SMTP-based email notifications. Supports Gmail, Outlook, and custom SMTP servers.

💬

Slack

Send alerts to Slack channels using incoming webhooks.

📱

Telegram

Instant notifications via Telegram bot. Create a bot with @BotFather.

🔗

Webhook

Generic HTTP webhooks for Discord, custom APIs, or other services.

💻

Desktop

Native desktop notifications on Linux (requires notify-send).

Email Configuration Example

channels: email: enabled: true smtp_host: smtp.gmail.com smtp_port: 587 smtp_user: alerts@example.com smtp_pass: your-app-password from: spyd@yourserver.com to: - admin@example.com use_tls: true

Telegram Configuration Example

channels: telegram: enabled: true bot_token: 123456789:ABC... chat_id: 123456789
Tip: Use spyd configure alerts for interactive setup of all notification channels.

AI-Powered Analysis

Spyd uses AI to provide intelligent, context-aware analysis of your system health. When thresholds are exceeded, the AI investigates and provides actionable recommendations.

How It Works

🔍

L1: Detection

Continuous monitoring detects when metrics exceed thresholds.

🔬

L2: Investigation

AI analyzes system state and runs diagnostic commands to understand the issue.

💡

L3: Solution

Provides specific, actionable steps to resolve the problem.

Supported AI Providers

OpenAI

Use GPT-4o-mini or other OpenAI models. Requires API key.

spyd configure ai --provider openai --model gpt-4o-mini

Ollama

Run AI locally with Ollama. Free and private. No API key required.

spyd configure ai --provider ollama --model llama3
Privacy Note: When using OpenAI, only redacted system summaries are sent for analysis. Sensitive information (usernames, paths, IPs) is automatically removed.

Support & Help

📚

Documentation

Complete guides and command reference at spyd.sh/docs

💡

Built-in Help

Run spyd help or spyd COMMAND --help for command-specific help

🔒

Privacy First

100% local processing. Your data never leaves your server.

🆓

Free & Open Source

MIT License. Free forever, no hidden costs.

Need Help? Run spyd configure show to see your current configuration and verify all settings.