CatOps

Fast and convenient monitoring with AI. One command to install, zero configuration needed.

Set up in 5 minutes. Get a beautiful dashboard. AI helps you troubleshoot. Monitor standalone servers or entire Kubernetes clusters with Telegram alerts and web dashboard at catops.app.

# Install in seconds
curl -sfL https://get.catops.app/install.sh | bash

Features

Core Monitoring:

System metrics (CPU, Memory, Disk, Network, I/O)
Process monitoring with resource usage
Log collection from Docker, journald, and log files
Real-time Telegram alerts
Beautiful web dashboard
Cross-platform (Linux, macOS, Kubernetes)

AI-Powered:

AI Assistant - Ask questions about your server directly from CLI
Smart alert analysis
Troubleshooting recommendations

Deployment Options:

Standalone: Monitor individual servers (Linux/macOS)
Kubernetes: Monitor entire clusters with DaemonSet

Alerting:

Telegram bot integration
Alert deduplication (no spam)
Interactive Telegram buttons (Acknowledge, Silence)
Instant notifications with detailed context

Management:

Background service with auto-start
Simple CLI commands
Automatic updates
User-level installation (no root required)

Quick Start

Standalone Server

# 1. Install
curl -sfL https://get.catops.app/install.sh | bash

# 2. Check status
catops status

# 3. Enable web dashboard (optional)
catops auth login YOUR_TOKEN

Kubernetes Cluster

# 1. Get your token from https://catops.app/setup

# 2. Install with Helm
helm install catops oci://ghcr.io/mfhonley/catops/helm-charts/catops \
  --namespace catops-system \
  --create-namespace \
  --set auth.token=YOUR_TOKEN

# 3. Verify installation
kubectl get pods -n catops-system

That's it! Your servers/nodes appear in the dashboard within 60 seconds.

Installation

Standalone Servers

Requirements:

Linux (systemd) or macOS (launchd)
AMD64 or ARM64 architecture
No root privileges required

One-Command Install:

curl -sfL https://get.catops.app/install.sh | bash

Operating Modes:

Local Mode (default): Metrics collected locally, view with catops status
Cloud Mode: Telegram alerts + Web dashboard at catops.app

Enable Cloud Mode for Telegram alerts:

# 1. Install CatOps
curl -sfL https://get.catops.app/install.sh | bash

# 2. Get token from https://catops.app
catops auth login YOUR_TOKEN

# 3. Configure Telegram bot on catops.app dashboard

From Source (Developers):

git clone https://github.com/mfhonley/catops.git
cd catops/cli
go build -o catops ./cmd/catops
./catops --version

Kubernetes Clusters

Requirements:

Kubernetes 1.19+
Helm 3.0+
metrics-server installed

Quick Install:

# Basic installation (core metrics only)
helm install catops oci://ghcr.io/mfhonley/catops/helm-charts/catops \
  --namespace catops-system \
  --create-namespace \
  --set auth.token=YOUR_TOKEN

With Prometheus (Extended Metrics):

# Includes pod labels, owner info, 200+ metrics
helm install catops oci://ghcr.io/mfhonley/catops/helm-charts/catops \
  --namespace catops-system \
  --create-namespace \
  --set auth.token=YOUR_TOKEN \
  --set prometheus.enabled=true \
  --set kubeStateMetrics.enabled=true

Verify Installation:

# Check pods are running
kubectl get pods -n catops-system

# Check logs
kubectl logs -n catops-system -l app.kubernetes.io/name=catops --tail=20

Usage

Basic Commands

Monitoring:

catops status              # Show current metrics
catops processes           # Top processes by resource usage
catops restart             # Restart monitoring service

AI Assistant:

catops ask "Why is my CPU high?"           # Ask AI about your server
catops ask "What's causing memory spikes?"  # Analyze issues
catops ask "Should I be worried?"           # Get recommendations

Configuration:

catops config show                  # Show current config
catops set interval=30              # Set metrics collection interval (10-300 seconds)

Service Management:

catops autostart enable    # Enable auto-start on boot
catops autostart disable   # Disable auto-start
catops autostart status    # Check auto-start status

System:

catops update              # Check for updates and install
catops uninstall           # Remove CatOps completely
catops --version           # Show version

AI Assistant

CatOps includes a FREE AI assistant that analyzes your server metrics and provides intelligent answers.

Features:

Context-aware - Analyzes current CPU, Memory, Disk, and top processes
Fast responses - Optimized for CLI
Privacy-first - Only sends metrics, not logs
No subscription required

Examples:

catops ask "Why is my CPU usage high?"
catops ask "What's causing memory spikes?"
catops ask "Should I be worried about disk usage?"
catops ask "Explain what's happening on my server"

Telegram Alerts

Setup:

Enable Cloud Mode: catops auth login YOUR_TOKEN
Configure Telegram on catops.app dashboard
Connect your Telegram account
Start receiving personal alerts

Interactive Alert Buttons:

When connected to catops.app, alerts include interactive buttons:

CPU Spike Detected

server-prod-01
5.2% -> 35.8% (+30.6% spike)

[Acknowledge] [Silence] [Details]

Acknowledge - Mark alert as seen, stop re-notifications
Silence - Mute alerts for 30m/1h/2h/24h (useful for maintenance)
Details - Open web dashboard for full metrics and history

Cloud Mode (Web Dashboard)

Enable web dashboard at catops.app:

# 1. Get token from https://catops.app (Profile -> Generate Auth Token)

# 2. Login
catops auth login YOUR_AUTH_TOKEN

# 3. Verify
catops auth info

Benefits:

Real-time metrics accessible from anywhere
Historical data and trends
Log collection and analysis
Multi-server monitoring
Team collaboration
Mobile-friendly interface

Operation Modes:

Local Mode (default): Metrics collected locally, no alerts, works offline
Cloud Mode: Telegram alerts + Web dashboard + Multi-server monitoring + Log collection

Kubernetes Guide

Installation

Prerequisites Check:

# Check Kubernetes version (need 1.19+)
kubectl version --short

# Check Helm installed (need 3.0+)
helm version --short

# Verify metrics-server is working
kubectl top nodes

Install metrics-server (if needed):

kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

# For Docker Desktop, allow insecure TLS:
kubectl patch deployment metrics-server -n kube-system \
  --type='json' \
  -p='[{"op": "add", "path": "/spec/template/spec/containers/0/args/-", "value": "--kubelet-insecure-tls"}]'

Install CatOps:

# Get your auth token from https://catops.app/setup

# Install with Helm
helm install catops oci://ghcr.io/mfhonley/catops/helm-charts/catops \
  --namespace catops-system \
  --create-namespace \
  --set auth.token=YOUR_TOKEN \
  --set prometheus.enabled=true \
  --set kubeStateMetrics.enabled=true

What Gets Monitored

Node Metrics (per node):

CPU, Memory, Disk usage
Network I/O, HTTPS connections
Pod count and status
System information (OS, uptime)

Pod Metrics (per pod):

CPU/Memory usage
Restart count, container count
Pod phase (Running/Pending/Failed)
Namespace, labels, owner info (with Prometheus)

Cluster Metrics:

Total nodes / Ready nodes
Total pods / Running / Pending / Failed
Cluster health percentage

Managing CatOps

Update:

# Update to latest version
helm upgrade catops oci://ghcr.io/mfhonley/catops/helm-charts/catops \
  --namespace catops-system \
  --reuse-values

Uninstall:

# Remove CatOps
helm uninstall catops -n catops-system

# Delete namespace
kubectl delete namespace catops-system

Configuration

Configuration file: ~/.catops/config.yaml

Example:

# Cloud Mode (Set automatically via 'catops auth login')
auth_token: "your_auth_token"
server_id: "507f1f77bcf86cd799439011"

# Monitoring Configuration
collection_interval: 30   # Collect metrics every 30 seconds (default)

Edit configuration:

# Via CLI command (recommended)
catops set interval=30

# Or edit file directly
nano ~/.catops/config.yaml

Metrics Collection Interval

Default: 30 seconds | Range: 10-300 seconds

How often to collect system metrics (CPU, Memory, Disk).

catops set interval=30    # Default - balanced
catops set interval=15    # More frequent - catches brief spikes
catops set interval=60    # Less frequent - minimal resource usage

When to adjust:

Missing short-lived spikes? Decrease to 15 seconds
Want minimal overhead? Increase to 60-120 seconds
Development environment? Increase to 60 seconds

Log Collection

CatOps automatically collects logs from various sources when in Cloud Mode:

Supported Sources:

Docker containers - Logs from all running containers
Docker Compose - Service logs with container name detection
Journald - System logs on Linux (systemd)
Log files - Common log file locations

Log Parsing:

Automatic format detection (JSON, logfmt, syslog, common log formats)
Uvicorn/Gunicorn access logs
Error and warning detection
HTTP request parsing (method, path, status, duration)
Stack trace extraction

View logs in web dashboard at catops.app

Troubleshooting

Standalone Issues

CatOps not starting:

# Check status
catops status

# Force cleanup and restart
catops force-cleanup
catops restart

# Check logs (Linux)
journalctl -u catops --since "10 minutes ago"

# Check logs (macOS)
tail -f ~/Library/Logs/catops.log

# Or check default log location
cat /tmp/catops.log

Telegram alerts not working:

# Verify Cloud Mode is enabled
catops auth info

# Check Telegram is configured on catops.app dashboard
# Connect your Telegram account in Settings

# Restart daemon
catops restart

Cloud Mode not working:

# Check authentication
catops auth info

# Re-login
catops auth logout
catops auth login YOUR_NEW_TOKEN

Kubernetes Issues

Pods in CrashLoopBackOff:

# Check logs for errors
kubectl logs -n catops-system -l app.kubernetes.io/name=catops --tail=100

# Common fix: Install/fix metrics-server
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

High resource usage:

# Check current resource usage
kubectl top pods -n catops-system

# Disable Prometheus to reduce usage
helm upgrade catops oci://ghcr.io/mfhonley/catops/helm-charts/catops \
  --namespace catops-system \
  --reuse-values \
  --set prometheus.enabled=false

Contributing

We welcome contributions!

Quick Start:

# Fork and clone
git clone https://github.com/YOUR_USERNAME/catops.git
cd catops/cli

# Build
go build -o catops ./cmd/catops

# Test
./catops --version

Areas to contribute:

Bug fixes and improvements
Documentation enhancements
Platform support (Windows, FreeBSD)
Feature requests

Support

Get Help:

Telegram: @mfhonley - Fastest response
Email: [email protected]
Issues: GitHub Issues
Discussions: GitHub Discussions

License

MIT License - see LICENSE for details.

Components:

CatOps CLI: Open source (MIT)
Web Dashboard: catops.app
Backend API: Cloud infrastructure for metrics storage

Links

Website: catops.app
Documentation: GitHub
Helm Chart: ghcr.io/mfhonley/catops/helm-charts/catops

Built with love by the open source community

Name		Name	Last commit message	Last commit date
Latest commit History 176 Commits
.github/workflows		.github/workflows
charts/catops		charts/catops
cmd		cmd
config		config
docs		docs
internal		internal
pkg/utils		pkg/utils
.gitignore		.gitignore
Dockerfile.k8s		Dockerfile.k8s
LICENSE		LICENSE
README.md		README.md
go.mod		go.mod
go.sum		go.sum
process.test		process.test

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

CatOps

Table of Contents

Features

Quick Start

Standalone Server

Kubernetes Cluster

Installation

Standalone Servers

Kubernetes Clusters

Usage

Basic Commands

AI Assistant

Telegram Alerts

Cloud Mode (Web Dashboard)

Kubernetes Guide

Installation

What Gets Monitored

Managing CatOps

Configuration

Metrics Collection Interval

Log Collection

Troubleshooting

Standalone Issues

Kubernetes Issues

Contributing

Support

License

Links

About

Uh oh!

Releases 82

Packages

Uh oh!

Languages

License

mfhonley/catops

Folders and files

Latest commit

History

Repository files navigation

CatOps

Table of Contents

Features

Quick Start

Standalone Server

Kubernetes Cluster

Installation

Standalone Servers

Kubernetes Clusters

Usage

Basic Commands

AI Assistant

Telegram Alerts

Cloud Mode (Web Dashboard)

Kubernetes Guide

Installation

What Gets Monitored

Managing CatOps

Configuration

Metrics Collection Interval

Log Collection

Troubleshooting

Standalone Issues

Kubernetes Issues

Contributing

Support

License

Links

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 82

Packages 0

Uh oh!

Languages

Packages