Metadata-Version: 2.4
Name: meshpop
Version: 4.13.57
Summary: MeshPOP Fleet Orchestration — manage mesh VPN servers at scale
Author-email: MeshPOP <hello@mpop.dev>
License: Apache-2.0
Keywords: mesh,vpn,wireguard,fleet,orchestration,ai,mcp
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: all
Requires-Dist: radiomcp; extra == "all"
Requires-Dist: rtlinux; extra == "all"
Dynamic: license-file

# meshpop (mpop)

**All-in-one server fleet management — monitor, manage, and automate multi-server infrastructure through AI.**

```bash
pip install meshpop
```

No external dependencies. Pure Python. Installs in seconds on any Linux or macOS machine.

---

## Why mpop?

### The problem with managing server fleets today

Running more than a handful of servers means constantly jumping between machines, tools, and dashboards:

```bash
# Old way: checking 10 servers one by one
ssh root@web1 "df -h && free -h && uptime"
ssh root@web2 "df -h && free -h && uptime"
ssh root@db1  "df -h && free -h && uptime"
# ... repeat 7 more times
# No unified view. No anomaly detection. Pure manual work.
```

**Monitoring tools** (Prometheus, Grafana, Zabbix) solve the visibility problem but require:
- Dedicated monitoring servers
- Agent installation and configuration on every node
- Dashboard setup and maintenance
- Learning curve for each tool

**Configuration management** (Ansible, Chef, Puppet) automates deployments but:
- Requires a separate control node
- YAML/DSL to learn
- No real-time monitoring built in

**mpop is a single command that does all of this** — and lets an AI manage it for you.

### Before mpop

```bash
# Checking fleet health — manual SSH to each server
for server in web1 web2 web3 db1 db2 worker1 worker2; do
  echo "=== $server ==="
  ssh root@$server "
    echo 'Disk:' && df -h / | tail -1
    echo 'Memory:' && free -h | grep Mem
    echo 'Load:' && uptime
    echo 'Failed services:' && systemctl --failed --no-pager
    echo 'Security:' && last | head -5
  "
done
# 5-10 minutes of work
# Still no unified anomaly detection
# Still have to interpret the output yourself
```

### After mpop

```bash
mpop              # Full fleet dashboard in 3 seconds
mpop heal         # Auto-detect and fix issues on all servers
mpop ask "which server is running low on disk?"
```

Or let AI do it — just describe what you want in plain language.

### Comparison

| | Manual SSH | Monitoring Stack | mpop |
|---|---|---|---|
| Fleet overview | One server at a time | After setup + config | `mpop` — instant |
| Setup time | None | Days to weeks | Minutes |
| Dependencies | SSH keys | Multiple services | None |
| Anomaly detection | Manual inspection | After threshold config | Built-in AI analysis |
| Fix issues | Manual commands | Alerts only | `mpop heal` — auto |
| Natural language queries | ✗ | ✗ | ✓ `mpop ask "..."` |
| AI management (MCP) | ✗ | ✗ | ✓ Full MCP integration |
| Agent deployment | Manual | Manual | `mpop setup <server>` |

---

## Architecture

mpop works as a three-layer system:

```
┌─────────────────────────────────────────────────────────────┐
│  mpop CLI / MCP  ← your machine (or AI agent)               │
│  Talks to all servers simultaneously                         │
└──────────────────────────┬──────────────────────────────────┘
                           │  HTTP :8721
           ┌───────────────┼───────────────┐
           │               │               │
    ┌──────▼──────┐  ┌──────▼──────┐  ┌──────▼──────┐
    │  agent on   │  │  agent on   │  │  agent on   │
    │   web1      │  │   web2      │  │   db1       │
    │  :8721      │  │  :8721      │  │  :8721      │
    └─────────────┘  └─────────────┘  └─────────────┘
         Gossip protocol — agents share stats with each other
         every 30 seconds. Any agent knows the full fleet state.
```

Each server runs a lightweight **agent** (`agent_reporter.py`) on port 8721. Agents collect local stats and gossip them to peer agents. mpop queries any one agent and gets the full fleet picture.

mpop is **Layer 3** of the MeshPOP stack:

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

Each layer is independently installable. mpop works without wire or vssh — it can reach agents over any network (LAN, VPN, public internet).

---

## Installation

### Install mpop

```bash
pip install meshpop
```

This installs:
- `mpop` — CLI command
- `mpop-mcp` — MCP server for AI integration

No external packages required. Pure Python standard library.

### Configure servers

mpop needs to know which servers to manage. Create `~/.mpop/config.json`:

```json
{
  "node": "myserver",
  "node_name": "myserver",
  "dashboard_url": "http://10.0.0.1:8721",
  "servers": {
    "web1":    {"ip": "10.0.0.10"},
    "web2":    {"ip": "10.0.0.11"},
    "db1":     {"ip": "10.0.0.20"},
    "storage": {"ip": "10.0.0.30"}
  },
  "hostname_map": {
    "web-server-1": "web1",
    "web-server-2": "web2"
  }
}
```

`hostname_map` is optional — use it to normalize agent-reported hostnames to short canonical names.

### Deploy the agent to each server

The agent collects stats (CPU, memory, disk, GPU, processes, services) and serves them on port 8721.

```bash
# Install and start the agent on a remote server:
mpop setup web1

# Or deploy to multiple servers:
mpop setup web1 && mpop setup web2 && mpop setup db1

# Check that agents are running:
mpop servers
```

The agent runs as a lightweight Python process — typically ~10MB RAM, negligible CPU.

### Start monitoring

```bash
mpop          # Full dashboard — all servers at a glance
```

```
mpop dashboard  v4.13.52
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  NODE   STATUS   CPU   MEM    DISK    GPU    UPTIME
  web1   ONLINE   12%   45%    38%     —      14d 3h
  web2   ONLINE    8%   32%    41%     —      14d 3h
  db1    ONLINE   23%   67%    55%     —       7d 12h
  gpu1   ONLINE   91%   78%    44%    94%      2d 6h
  ○ backup  OFFLINE  —     —      —       —      —
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  5 servers  4 online  1 offline   14:23:07
```

---

## CLI Reference

### Dashboard and monitoring

```bash
mpop                       # Main dashboard
mpop servers               # List all servers with IPs and roles
mpop info web1             # Deep dive — GPU, processes, security, agent
mpop full                  # Comprehensive 9-table report with AI summary
mpop hw                    # Local hardware — CPU, GPU, RAM, disk, NIC
mpop temp                  # CPU/GPU temperatures across fleet
mpop gpu                   # GPU status — VRAM, utilization, processes
mpop services              # Running services on each server
mpop logs web1 auth        # View logs (auth / nginx / system)
mpop watch                 # Real-time monitoring with anomaly alerts
mpop trend                 # Historical trends — memory, disk, uptime
mpop matrix                # Server-to-server connectivity matrix
mpop diff web1 web2        # Compare two servers side-by-side
```

---

### Security

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

---

### Network and VPN

```bash
mpop vpn                   # VPN status (WireGuard / Tailscale)
mpop peers                 # Connected VPN peers and IPs
mpop watchdog start        # VPN watchdog — auto-restart on disconnect
```

---

### Remote execution

```bash
mpop exec web1 "df -h"             # Run command on a server
mpop exec web1 "systemctl restart nginx"
mpop python web1 "import os; print(os.uname())"   # Run Python code
```

---

### File operations

```bash
mpop read-file web1 /etc/nginx/nginx.conf
mpop scp ./config.json web1 /etc/app/config.json
```

---

### NAS operations

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

---

### AI diagnostics

```bash
mpop heal                  # Auto-detect problems and suggest fixes
mpop heal web1 --execute   # Auto-detect AND apply fixes
mpop predict web1          # Predict future issues (disk full, memory pressure)
mpop ai                    # AI trend analysis across fleet
mpop advise                # Infrastructure optimization recommendations
mpop logai                 # AI-powered cross-server log analysis
mpop ask "which server is low on disk?"   # Natural language → mpop command
mpop ask "restart nginx on all web servers" --execute
```

---

### Deployment and config

```bash
mpop setup web1            # Install agent on remote server
mpop deploy web1           # Deploy mpop binary to a server
mpop config show           # View current config
mpop config set key value  # Modify config
mpop backup web1           # Backup server configurations
```

---

### Agents and automation

```bash
# Create a custom automation agent from a description:
mpop agent-make --name disk-watcher \
  --behavior "Alert when any server disk exceeds 80%"

# Deploy it to servers:
mpop agent-deploy disk-watcher web1 web2 db1

# Run it:
mpop agent-run disk-watcher

# Chain multiple agents (pipe output between them):
mpop agent-chain run my-workflow
```

---

### Knowledge and notifications

```bash
mpop brain search "nginx config"        # Search knowledge base
mpop notify slack "Deploy complete"     # Send Slack / Discord / Telegram message
mpop export                             # Generate shareable HTML status report
```

---

## AI Management via MCP

mpop ships with an MCP server that lets AI agents (Claude, etc.) manage your entire fleet through natural language — from the first server setup through ongoing operations and incident response.

### Setup

```bash
pip install meshpop   # installs mpop-mcp automatically
```

Add to Claude config (`~/.claude/settings.json`):

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

If `mpop-mcp` is not on PATH:

```json
{
  "mcpServers": {
    "mpop": {
      "command": "python3",
      "args": ["-m", "mpop_mcp_server"]
    }
  }
}
```

### What the AI can do

Once connected, you can describe what you want in plain language:

> "Show me the fleet dashboard"
> "Which servers are running low on disk?"
> "Restart nginx on all web servers"
> "What's using GPU memory on gpu1?"
> "Run a security audit on db1 and tell me what you find"
> "Set up the monitoring agent on the new server at 10.0.0.50"
> "Are there any SSH attack patterns I should know about?"
> "Predict which servers might have issues in the next week"

The AI handles everything — it runs the right mpop commands, interprets the output, and gives you a clear answer.

### From zero to monitored fleet with AI

```
You: "I have 3 new servers at 10.0.0.10, 10.0.0.11, 10.0.0.20.
     Set them up for monitoring as web1, web2, and db1."

AI:
1. Updates ~/.mpop/config.json with the three servers
2. mpop_setup(web1) — deploys agent
3. mpop_setup(web2) — deploys agent
4. mpop_setup(db1)  — deploys agent
5. mpop_servers     — verifies all three are online
6. mpop_dashboard   — shows the fleet dashboard
7. Reports: "All three servers are online and being monitored.
             web1: 45% disk, 32% mem. web2: 41% disk, 28% mem.
             db1: 55% disk, 67% mem — you may want to watch that."
```

### MCP Tools Reference

#### Overview and monitoring

| Tool | Description |
|---|---|
| `mpop_dashboard` | Main fleet dashboard |
| `mpop_servers` | List all servers with names, IPs, roles |
| `mpop_info` | Deep server details — GPU, processes, security, agent |
| `mpop_full` | Comprehensive 9-table report with AI summary |
| `mpop_hw` | Local hardware — CPU, GPU, RAM, disk, NIC |
| `mpop_temp` | CPU/GPU temperatures across servers |
| `mpop_gpu` | GPU status — VRAM, utilization, processes |
| `mpop_services` | Running services on each server |
| `mpop_logs` | View server logs (auth, nginx, system) |
| `mpop_watch` | Real-time monitoring with anomaly alerts |
| `mpop_trend` | Historical trends — memory, disk, uptime |
| `mpop_matrix` | Server-to-server connectivity matrix |
| `mpop_diff` | Compare two servers side-by-side |

#### Security

| Tool | Description |
|---|---|
| `mpop_security` | Security overview — firewall, fail2ban, ports, SSH |
| `mpop_audit` | Detailed security audit of a server |
| `mpop_ssh_attacks` | SSH attack analysis — patterns, top IPs, geo |

#### Network and VPN

| Tool | Description |
|---|---|
| `mpop_vpn` | VPN status (WireGuard + Tailscale) |
| `mpop_peers` | Connected VPN peers |
| `mpop_watchdog` | VPN watchdog daemon — auto-restart on disconnect |

#### Execution

| Tool | Description |
|---|---|
| `mpop_exec` | Run shell command on any server |
| `mpop_python` | Run Python code on local or remote server |
| `mpop_raw` | Run raw mpop CLI command with pipes/redirects |
| `mpop_delete` | Safe file deletion (system paths blocked) |

#### File operations

| Tool | Description |
|---|---|
| `mpop_read_file` | Read file (local or remote) |
| `mpop_write_file` | Write to local file |
| `mpop_scp` | Transfer file to/from server |

#### NAS

| Tool | Description |
|---|---|
| `mpop_nas_ls` | List NAS files |
| `mpop_nas_read` | Read NAS file |
| `mpop_nas_write` | Write to NAS |
| `mpop_nas_backup` | Backup server data to NAS |
| `mpop_nas_usage` | NAS disk usage summary |

#### AI and diagnostics

| Tool | Description |
|---|---|
| `mpop_ai` | AI trend analysis — predicts status changes |
| `mpop_heal` | Auto-detect problems and suggest/apply fixes |
| `mpop_predict` | Predict future issues (disk full, memory pressure) |
| `mpop_advise` | Infrastructure optimization advisor |
| `mpop_logai` | AI-powered cross-server log analysis |
| `mpop_ask` | Natural language → mpop commands |

#### Config and deploy

| Tool | Description |
|---|---|
| `mpop_config` | View/modify mpop configuration |
| `mpop_setup` | Install mpop agent on remote server |
| `mpop_deploy` | Deploy files or binary to servers |
| `mpop_backup` | Backup server configurations |
| `mpop_secret` | Encrypted credential management |

#### Agents and automation

| Tool | Description |
|---|---|
| `mpop_agent_list` | List custom automation agents |
| `mpop_agent_make` | Create agent from description |
| `mpop_agent_deploy` | Deploy agent to servers |
| `mpop_agent_run` | Run an agent |
| `mpop_agent_workflow` | Multi-agent sequential workflows |
| `mpop_agent_chain` | Pipe agent outputs via JSON |

#### Knowledge and integration

| Tool | Description |
|---|---|
| `mpop_brain` | Search knowledge base |
| `mpop_project` | Project management — status, history |
| `mpop_memory` | Code knowledge base + Q&A |
| `mpop_rag` | Document Q&A with RAG |
| `mpop_notify` | Send via Slack / Discord / Telegram / Email |
| `mpop_webhook` | Webhook management |
| `mpop_workflow` | Predefined workflows (health, security, deploy) |
| `mpop_export` | Generate shareable HTML status report |

---

## Requirements

- Python 3.8+
- Servers accessible via SSH or VPN (wire, Tailscale, or any network)
- `psutil` on each monitored server (for memory/disk stats) — `pip install psutil`

---

## Links

- Wire VPN: [github.com/meshpop/wire](https://github.com/meshpop/wire)
- vssh transport: [github.com/meshpop/vssh](https://github.com/meshpop/vssh)
- PyPI: [pypi.org/project/meshpop](https://pypi.org/project/meshpop)

## License

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