# mpop

[![PyPI](https://img.shields.io/pypi/v/meshpop)](https://pypi.org/project/meshpop/)
[![Python](https://img.shields.io/pypi/pyversions/meshpop)](https://pypi.org/project/meshpop/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**Server fleet management from one command. Monitor, execute, and heal with AI.**

```bash
pip install meshpop
```

Pure Python. No external dependencies. Linux and macOS.

---

## What mpop does

```bash
mpop                   # Fleet dashboard — all servers at a glance
mpop heal              # Auto-detect and fix issues across the fleet
mpop exec web1 "systemctl restart nginx"
mpop ask "which server is running low on disk?"
```

mpop gives you a single place to see and manage your entire server fleet. It uses a lightweight gossip agent (port 8721) that runs on each server, collects local stats, and shares them with peers every 30 seconds.

```
┌──────────────────────────────────────────┐
│  mpop CLI / MCP  (your machine or AI)    │
└──────────────────┬───────────────────────┘
                   │  HTTP :8721
      ┌────────────┼────────────┐
      │            │            │
┌─────▼─────┐ ┌───▼─────┐ ┌───▼─────┐
│  agent    │ │  agent  │ │  agent  │
│  web1     │ │  web2   │ │  db1    │
└─────┬─────┘ └────┬────┘ └────┬────┘
      └────────────┴────────────┘
        gossip every 30s
```

---

## Installation

```bash
pip install meshpop
```

### Configure your servers

Create `~/.mpop/config.json`:

```json
{
  "connection": {"vpn": "wire", "ssh_method": "vssh"},
  "relays": ["YOUR_RELAY_IP"],
  "servers": {
    "web1": {"ip": "10.99.0.10", "user": "root", "role": "Web server", "public_ip": "203.0.113.10"},
    "web2": {"ip": "10.99.0.11", "user": "root", "role": "Web server", "public_ip": "203.0.113.11"},
    "db1":  {"ip": "10.99.0.20", "user": "root", "role": "Database",   "public_ip": "203.0.113.20"}
  }
}
```

### Deploy the agent

```bash
mpop setup web1     # Install and start the monitoring agent
mpop setup web2
mpop setup db1
mpop servers        # Verify all agents are online
```

The agent runs as a systemd service — ~10MB RAM, negligible CPU.

---

## CLI Reference

### Monitoring

```bash
mpop                       # Main fleet dashboard
mpop servers               # List servers with IPs, roles, agent status
mpop info web1             # Deep dive — CPU, GPU, processes, security
mpop full                  # Comprehensive report with AI summary
mpop watch                 # Real-time monitoring with anomaly alerts
mpop temp                  # CPU/GPU temperatures
mpop gpu                   # GPU status — VRAM, utilization, processes
mpop services              # Running services on each server
mpop logs web1 nginx        # View logs
mpop trend                 # Historical trends
mpop matrix                # Server-to-server connectivity matrix
mpop diff web1 web2        # Compare two servers side-by-side
```

### Network profiles

Manage multiple wire VPN networks (main fleet, private cluster, etc.):

```bash
mpop network               # Show active network + connection status
mpop network list          # List saved profiles
mpop network create        # Create a profile from a relay (auto-discovers peers)
mpop network switch main   # Switch to 'main' profile
mpop network save main     # Save current config as 'main'
```

Profiles: `~/.mpop/networks/<name>.json` · Active: `~/.mpop/.active_network`

### Security

```bash
mpop security              # Security overview — firewall, fail2ban, SSH
mpop audit web1            # Detailed security audit
mpop ssh-attacks           # SSH attack analysis — top IPs, geo distribution
```

### Remote execution

```bash
mpop exec web1 "df -h"
mpop exec web1 "systemctl restart nginx"
mpop python web1 "import os; print(os.uname())"
mpop read-file web1 /etc/nginx/nginx.conf
mpop scp ./config.json web1 /etc/app/config.json
```

### AI diagnostics

```bash
mpop heal                         # Detect and suggest fixes
mpop heal web1 --execute          # Detect and apply fixes
mpop predict web1                 # Predict future issues (disk, memory)
mpop advise                       # Infrastructure optimization recommendations
mpop logai                        # AI cross-server log analysis
mpop ask "which server is low on disk?"
mpop ask "restart nginx on all web servers" --execute
```

### NAS

```bash
mpop nas-ls /backups
mpop nas-read /backups/latest.log
mpop nas-backup web1 /var/data /backups/web1
mpop nas-usage /backups
```

### Agents & automation

```bash
mpop agent-make --name disk-watcher \
  --behavior "Alert when any server disk exceeds 80%"
mpop agent-deploy disk-watcher web1 web2 db1
mpop agent-run disk-watcher
```

---

## AI Management via MCP

```json
{
  "mcpServers": {
    "mpop": { "command": "mpop-mcp" }
  }
}
```

> "Show me the fleet dashboard"
> "Which servers are running low on disk?"
> "Restart nginx on all web servers"
> "Run a security audit on db1"
> "Predict which servers might have issues this week"

### MCP Tools

<details>
<summary>Monitoring</summary>

| Tool | Description |
|---|---|
| `mpop_dashboard` | Main fleet dashboard |
| `mpop_servers` | List servers |
| `mpop_info` | Deep server details |
| `mpop_full` | Comprehensive report |
| `mpop_watch` | Real-time monitoring |
| `mpop_temp` | Temperatures |
| `mpop_gpu` | GPU status |
| `mpop_services` | Running services |
| `mpop_logs` | Server logs |
| `mpop_trend` | Historical trends |
| `mpop_matrix` | Connectivity matrix |
| `mpop_diff` | Side-by-side comparison |

</details>

<details>
<summary>Execution & Files</summary>

| Tool | Description |
|---|---|
| `mpop_exec` | Run shell command |
| `mpop_python` | Run Python code |
| `mpop_raw` | Raw CLI with pipes |
| `mpop_read_file` | Read file |
| `mpop_write_file` | Write file |
| `mpop_scp` | Transfer file |

</details>

<details>
<summary>AI & Diagnostics</summary>

| Tool | Description |
|---|---|
| `mpop_heal` | Auto-detect and fix issues |
| `mpop_predict` | Predict future problems |
| `mpop_advise` | Optimization recommendations |
| `mpop_logai` | AI log analysis |
| `mpop_ask` | Natural language → commands |
| `mpop_ai` | Trend analysis |

</details>

<details>
<summary>Security</summary>

| Tool | Description |
|---|---|
| `mpop_security` | Security overview |
| `mpop_audit` | Detailed audit |
| `mpop_ssh_attacks` | SSH attack analysis |

</details>

---

## MeshPOP Stack

```
mpop     Fleet orchestration — monitor, manage, automate  ← this
vssh     Authenticated transport — remote exec, file transfer
wire     Encrypted mesh VPN — connects all nodes
```

| Package | Role | Install |
|---|---|---|
| [wire](https://github.com/meshpop/wire) | Mesh VPN | `pip install meshpop-wire` |
| [vssh](https://github.com/meshpop/vssh) | Transport | `pip install vssh` |
| **mpop** | Orchestration | `pip install meshpop` |
| [meshclaw](https://github.com/meshpop/meshclaw) | Agent workflows | `pip install meshclaw` |
| [meshdb](https://github.com/meshpop/meshdb) | Distributed search | `pip install meshpop-db` |

---

## License

MIT — [MeshPOP](https://github.com/meshpop)
