https://github.com/adityaarsharma/perch
Perch — Telegram bot + Claude Code plugin for RunCloud server management. Servers under one wing. Always free.
https://github.com/adityaarsharma/perch
claude claude-code claude-desktop devops linux-server mcp mcp-server model-context-protocol nginx runcloud runcloud-api self-healing server-automation server-health server-management server-monitoring ssh telegram-bot typescript wordpress
Last synced: 1 day ago
JSON representation
Perch — Telegram bot + Claude Code plugin for RunCloud server management. Servers under one wing. Always free.
- Host: GitHub
- URL: https://github.com/adityaarsharma/perch
- Owner: adityaarsharma
- Created: 2026-03-22T10:47:54.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-05-04T11:35:01.000Z (about 2 months ago)
- Last Synced: 2026-05-04T13:31:55.669Z (about 2 months ago)
- Topics: claude, claude-code, claude-desktop, devops, linux-server, mcp, mcp-server, model-context-protocol, nginx, runcloud, runcloud-api, self-healing, server-automation, server-health, server-management, server-monitoring, ssh, telegram-bot, typescript, wordpress
- Language: JavaScript
- Homepage:
- Size: 578 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 🪶 Perch
### The intelligence layer for your servers.
**An AI-native, self-hosted, self-learning brain that watches every server you run, diagnoses what breaks in plain English, and lives wherever you want — Claude Code, Telegram, Slack, your terminal, anywhere that speaks HTTP.**
[](LICENSE)
[]()
[]()
[](https://runcloud.io)
[](https://modelcontextprotocol.io)
[](https://wordpress.org)
[Install](#install-in-5-minutes) · [Why Perch](#why-this-exists) · [Comparison](#the-real-hosting-market) · [Commands](#the-perch-experience) · [Architecture](#whats-inside)
---
## The 30-Second Pitch
- **AI-native, not retrofitted.** Built around Claude Code from day one. Your AI talks to your servers via 150+ MCP tools.
- **Self-hosted intelligence.** Every server, every webapp, every problem, every fix — saved in a local SQLite brain on your hardware. Nobody else owns your operational history.
- **Plain-English diagnosis.** Not "ERROR 500." Try: *"Plugin X just got updated and now conflicts with Theme Y. I deactivated X and the site is back up."*
- **Connectors, not lock-in.** Telegram. Slack. Webhooks. Email. CLI. Anything that talks HTTP. Pick one or use them all.
- **Free forever, no per-server tax.** Run it on 1 VPS or 100. Same price: zero. No "Pro tier," no license keys, no rug-pull.
---
## Why This Exists
In April 2026, you have four ways to host a serious website. All of them are bad:
### The Real Hosting Market
| Option | Real cost / site | What's broken |
|--------|------------------|---------------|
| **GoDaddy / Bluehost** | $7.99–$25/mo | Oversold shared servers. Support reads scripts. Up-charges for SSL, backups, speed. Stuck in 2010. |
| **Cloudways** | $14–$30/mo | [220% markup over raw DigitalOcean/Vultr](https://onlinemediamasters.com/cloudways-review/). No root access. Locked to 5 cloud providers. Bills jump when scaling RAM you don't need. |
| **Kinsta** | $35–$115/mo | Beautiful UX. Container isolation. But $35/site adds up fast — and [no email hosting included](https://divicake.com/blog/kinsta-performance-and-pricing/). Vendor lock-in. |
| **SiteGround** | $2.99–$15/mo | Cheap to start, oversells, slows you down at scale. Renewal pricing 3x intro. |
| **Raw VPS** (Hetzner / DigitalOcean / Linode) | $4–$10/mo | Total power. Zero guardrails. One typo = client site gone. You're the sysadmin now. |
| **RunCloud + your VPS** | $8–$15/mo + $4 VPS | The smart pick. GUI on top of any cloud. Root access. Auto-backups. But it *manages* — it doesn't *watch*, *diagnose*, or *heal*. |
**Most people pick GoDaddy because they don't know better.** The smart ones pick Cloudways for ease — and pay 3x what they should. The rest go raw VPS and become accidental sysadmins.
[**RunCloud**](https://runcloud.io) is genuinely the smartest piece of infrastructure no one's heard of:
- **Provider freedom** — works with any cloud (Hetzner, DigitalOcean, AWS, Vultr, Linode, your own metal). Cloudways locks you to 5.
- **You keep root.** Cloudways doesn't give you root. RunCloud does.
- **Stop paying anytime.** Your VPS keeps running with all your sites. Cloudways = pay or lose everything.
- **Stack flexibility.** Pure NGINX or hybrid Apache+NGINX. Your call. Cloudways = take what they give you.
- **Real isolation.** Each web app runs as its own system user. Mistakes stay scoped.
- **$8/mo flat for the panel.** No per-site tax.
So: **Hetzner CX21 ($5/mo) + RunCloud ($8/mo) = $13/mo total.** You get the equivalent of Kinsta ($35–$115) with WordPress + Laravel + Node + n8n + anything else on the same box. Your data on your hardware.
The catch? RunCloud is a **management panel**. It does not watch. It does not diagnose. It does not heal. It does not learn.
**That's where Perch lives.**
---
## What No One Else Is Doing
| | GoDaddy / Bluehost | Cloudways | Kinsta | SiteGround | RunCloud (alone) | **RunCloud + Perch** |
|---|:---:|:---:|:---:|:---:|:---:|:---:|
| Provider freedom | ❌ | Limited | ❌ | ❌ | ✅ | ✅ |
| Root access | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
| Run any stack (WP+Node+n8n) | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
| **AI-native (Claude Code)** | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| **Self-learning brain** | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| **Plain-English diagnosis** | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| **WordPress deep-audit (DB, plugins, CVE, perf)** | Partial | Partial | ✅ | Partial | ❌ | ✅ |
| **Auto-fix safe issues** | Limited | Limited | ✅ | Limited | ❌ | ✅ |
| **Multi-channel alerts (Telegram/Slack/HTTP)** | ❌ | Email only | Email only | Email only | Email only | ✅ |
| Cost (1 site) | $7.99 | $14 | $35 | $2.99 | $13 | **$13** |
| Cost (10 sites) | $80+ | $140+ | $350+ | Plan upgrade | $13 | **$13** |
| Cost (50 sites) | Unrealistic | $700+ | $1,750+ | Unrealistic | $25 | **$25** |
| Lock-in | High | High | High | Medium | None | None |
| Owns your data | They do | They do | They do | They do | You | **You** |
**The thing nobody is shipping:** an open-source, AI-native intelligence layer that runs on your own server, learns your stack over time, talks to you in any channel you want, and never sends you a renewal email. That's Perch.
---
## The Perch Experience
### From Claude Code
```
You: /perch wp audit mysite.com
Perch: 📊 Running full audit on mysite.com...
Database: 8.4MB autoload (urgent — should be <1MB)
Top offender: elementor_data 2.1MB
47 expired transients (1.8MB recoverable)
Plugins: 34 active, 6 need updates, 2 vulnerable
🔴 Contact Form 7 v5.7 — CVE-2024-XXXX (CVSS 8.1)
Security: 71/100 (Grade C)
Admin username is "admin" — change it
xmlrpc.php is publicly accessible
Backup: Last run 14h ago, 2.1GB to S3 ✓
But: DB backup missing for 3 days (mysqldump connection error)
Want me to fix the safe stuff? (transients, sessions, CF7 update, DB backup creds)
```
### From Telegram
```
🪶 nginx had a moment on production-1
I checked — config snippet added via RunCloud has a typo on line 47.
I've restarted nginx-rc and the site is back up (took 8 seconds).
Want me to fix that snippet so this doesn't happen again?
[✅ Yes, fix it] [📄 Show me] [🔇 Not now]
```
### From your shell
```bash
$ perch status
production-1 ✅ RAM 42% Disk 67% Load 0.21
staging-1 ⚠️ RAM 91% Disk 78% Load 0.84 ← memory pressure
dev ✅ RAM 33% Disk 12% Load 0.05
$ perch wp errors mysite.com
Likely cause: Plugin "my-plugin" updated 2h ago, now conflicts with theme.
Suggested fix: wp plugin deactivate my-plugin --path=/home/user/public_html
Fixable by Perch: yes
$ perch fix mysite.com
[asks for confirmation, runs the fix, reports back]
```
Same intelligence. Three different surfaces. **Connectors are interchangeable.** Use what fits your day.
---
## Architecture
```
┌──────────────────────────────────────────────────────────────────┐
│ CONNECTORS (your choice) │
│ Claude Code MCP · Telegram · Slack · HTTP API · CLI · webhook │
└──────────────────────────────────────────────────────────────────┘
▲
│ same intelligence, multiple surfaces
▼
┌──────────────────────────────────────────────────────────────────┐
│ PERCH CORE │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ Brain │ │ Gateway │ │ SSH + RunCloud │ │
│ │ SQLite KB │ │ Alerts │ │ API clients │ │
│ │ Self-learn │ │ Friendly │ │ Safe execution │ │
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ INTELLIGENCE MODULES │ │
│ │ WordPress · Watcher · Diagnostician · Healer │ │
│ │ (DB · Plugins · Security · Backup · Images · │ │
│ │ Performance · Errors · White Screen Diagnosis) │ │
│ └──────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
▲
│ SSH + RunCloud API v3
▼
┌──────────────────────────────────────────────────────────────────┐
│ YOUR INFRASTRUCTURE (you own everything) │
│ Hetzner · DigitalOcean · AWS · Vultr · Linode · bare metal │
│ WordPress · Laravel · Node · n8n · Python · static · anything │
└──────────────────────────────────────────────────────────────────┘
```
The brain is the moat. Every audit, every fix, every problem gets logged to a SQLite database on **your** server. Over weeks, Perch learns your stack — what's normal for *your* memory baseline, which plugins are problem children on *your* PHP version, what fixes actually worked when *your* nginx crashed at 2am.
Nobody else has this data. Not RunCloud. Not Cloudways. Not Aditya. **You.**
---
## Install in 5 Minutes
### Path A — As a Claude Code MCP (recommended)
Get every `/perch_*` tool inside your Claude Code sessions.
```bash
git clone https://github.com/adityaarsharma/perch
cd perch
npm install && npm run build
```
Add to `~/.claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"perch": {
"command": "node",
"args": ["/absolute/path/to/perch/dist/index.js"],
"env": {
"RUNCLOUD_API_KEY": "your-runcloud-api-key"
}
}
}
}
```
Restart Claude Code. Type `/perch_brain` to verify. Done.
### Path B — Connectors (Telegram / Slack / HTTP)
Run on the server you want to watch. Provides 24/7 alerts when you're away from Claude Code.
```bash
ssh root@your-server
git clone https://github.com/adityaarsharma/perch /opt/perch
cd /opt/perch/telegram-bot
cp config.example.env .env
# Edit .env with your bot token, chat ID, fix-server token
./setup.sh
```
The setup wizard walks you through it. Telegram bot ready in under 5 minutes. (Slack guide: [docs/slack.md](docs/slack.md). Webhook + custom connector: [docs/install.md](docs/install.md).)
### Path C — Both (the agency setup)
Claude Code for deep work. Connector for 4am pages. Same brain, same data, same intelligence, two surfaces.
**Full install guide with screenshots and troubleshooting → [docs/install.md](docs/install.md)**
---
## What's Inside
> **HTTP API tool catalog:** every tool exposed by `perch-api` over HTTP is documented in [`docs/api-tools.md`](./docs/api-tools.md) — 55 tools (brain · conversation · read-only diagnostics · WordPress audit · WordPress mutating · vault · SSH primitives), with required args, mutating-vs-not flags, and which scripts they shell out to.
```
perch/
├── src/
│ ├── index.ts ← MCP server (150+ tools — RunCloud + Perch)
│ ├── core/
│ │ ├── brain.ts ← SQLite knowledge base (your data, your server)
│ │ ├── gateway.ts ← Alert formatter (friendly tone, multi-channel)
│ │ └── ssh-enhanced.ts ← SSH with password + private key + WP-CLI helper
│ └── modules/
│ └── wordpress/ ← The WordPress Audit Modules
│ ├── db.ts ← Autoload audit, transient cleanup, orphan detection
│ ├── plugins.ts ← Plugin audit + Wordfence Intelligence CVE scan
│ ├── security.ts ← 12-check hardening, scored 0–100
│ ├── backup.ts ← Backup health, last run age, destination check
│ ├── images.ts ← CLI image optimization (jpegoptim/optipng/cwebp)
│ ├── perf.ts ← Performance snapshot (cache, cron, PHP, TTFB)
│ └── errors.ts ← Error diagnosis + white screen root cause
│
├── telegram-bot/ ← Telegram connector (one of many)
│ ├── bot.py ← Polling bot with inline keyboards
│ ├── fix-server.py ← Local HTTP API (127.0.0.1 only)
│ ├── monitor.sh ← Cron-based health alerting
│ ├── setup.sh ← Interactive setup wizard
│ └── scripts/ ← Shell scripts for each fix action
│
├── docs/
│ ├── runcloud.md ← Full RunCloud server reference (nginx-rc, paths, gotchas)
│ ├── install.md ← Setup guides — MCP, connectors, both
│ ├── telegram.md ← Telegram connector deep-dive
│ ├── slack.md ← Slack connector setup
│ └── safety.md ← What Perch will and won't do (read this)
│
└── README.md ← You are here
```
---
## WordPress Audit Modules — what Perch sees on your sites
No plugin needed on the WordPress side. Everything runs via SSH and WP-CLI. RunCloud-aware (knows about `nginx-rc`, `/etc/nginx-rc/`, per-app users at `/home/{user}/webapps/`).
| Module | Catches |
|--------|---------|
| **Database** | Autoload bloat (Elementor, expired transients, orphaned WC sessions, postmeta orphans, table fragmentation, slow queries) |
| **Plugins** | Vulnerable plugins via Wordfence Intelligence (free, no API key), abandoned plugins (no updates 2+ years), hidden inactive plugins still on disk |
| **Security** | Admin username = "admin", xmlrpc.php exposed, wp-config permissions, file editor enabled, debug.log publicly accessible, missing rate limits, WP version exposed in headers, core checksum mismatches |
| **Backup** | Last run age, missing DB dumps, truncated backup files, S3/destination unreachable, mismatched retention |
| **Images** | Lossless JPEG/PNG compression (jpegoptim, optipng, pngquant), WebP generation alongside originals, savings estimate before run, scheduled or on-demand |
| **Performance** | PHP version EOL, object cache (Redis/Memcached) connected?, page cache type, WP cron health and backlog, TTFB from server, plugin count thresholds |
| **Errors** | Parses PHP error logs, classifies by type, identifies offending plugin/theme, detects plugin conflicts, white screen root cause, suggests one-line WP-CLI fix |
When something breaks, you get this:
```
🔴 White screen on mysite.com
Fatal error: Cannot redeclare 'my_custom_helper'
Conflict between:
wp-content/plugins/my-plugin/includes/helpers.php:23
wp-content/themes/mytheme/functions.php:89
my-plugin was updated 2 hours ago — likely introduced this.
[🔇 Deactivate my-plugin] [📋 Full Error Log] [↩️ Roll Back Plugin]
```
Not a stack trace. Not "Internal Server Error." A **diagnosis**.
---
## Automation Rules
Every Perch install ships with **14 built-in monitoring rules** that run via cron every 5 minutes. No n8n. No Zapier. No SaaS. The whole engine is a self-contained shell script (`telegram-bot/monitor.sh`) — about 400 lines, runs in under 2 seconds.
| # | Rule | Default trigger | Auto-action |
|---|---|---|---|
| 1 | nginx / nginx-rc down | service inactive | Telegram alert + restart button |
| 2 | PHP-FPM down (any version) | any `php*-fpm-rc` inactive | Restart button |
| 3 | MySQL / MariaDB down | service inactive | Restart button + OOM context |
| 4 | Disk usage tiered | 80% / 90% / 95% | Tiered alerts + cleanup button |
| 5 | RAM usage tiered | 85% / 93% | Top consumers + smart fix |
| 6 | CPU sustained load | 100% / 200% of cores | Top processes |
| 7 | Orphan processes (PPID=1) | >10 orphans | Smart fix |
| 8 | Failed systemd services | any in `systemctl --failed` | Smart fix |
| 9 | SSL expiry per site | 30d / 7d remaining | Renew SSL button |
| 10 | Site HTTP availability | 5xx or unreachable | Diagnose + fix buttons |
| 11 | Custom port checks | any configured port closed | Smart fix |
| 12 | fail2ban ban-rate spike | >50 bans/hour | Acknowledge |
| 13 | Backup age | >36h since last backup | Acknowledge |
| 14 | Daily heartbeat | 09:00 local time | "All systems good 🪶" |
Every threshold is overridable in `~/.perch/.env`. Every alert is friendly, contextual, and ships with one-tap action buttons. Cooldown logic prevents alert spam (default: 30 min between identical alerts).
`bash scripts/setup.sh` installs the cron line and prompts you for thresholds. Full reference: [docs/automation.md](docs/automation.md).
---
## Connectors
Connectors are how Perch talks to you. Pick one. Pick all. Add your own — the gateway is just a function that takes a structured alert and returns a payload.
| Connector | Status | Best for |
|-----------|--------|----------|
| **Claude Code MCP** | ✅ First-class | Deep work — auditing, planning, debugging |
| **Telegram bot** | ✅ Ready | 24/7 alerts on your phone, inline-button fixes |
| **Slack webhook** | ✅ Alerts work | Team channels, daily digests |
| **Slack bot** (slash commands + buttons) | 🔜 Q2 2026 | Full Slack parity with Telegram |
| **HTTP webhook** | ✅ Ready | Plug into anything (n8n, Zapier, Make, custom) |
| **Email** | 🔜 Coming | Stakeholders who don't live in chat |
| **Discord** | 🔜 Community PR welcome | Indie devs / community servers |
| **Custom** | ✅ Build your own | Implement `formatAlert(opts)` — done |
Telegram and Slack are working today. Slack inline buttons + slash commands ship Q2 2026. Other connectors are 50–200 lines each — PRs welcome.
---
## Safety
Perch is paranoid by default. Read this before installing on a production box: **[docs/safety.md](docs/safety.md)**
**The four promises:**
1. **Never destructive without confirmation.** Plugin deactivation, file deletion, config changes — all require an explicit confirm tap.
2. **Credentials never leak.** Passwords / SSH keys / API tokens are encrypted at rest with AES-256-GCM. Redacted from every log, every alert, every error message.
3. **Always reversible.** Last 10 confirmed actions logged. `/perch undo` reverts the most recent. DB content modifications never auto-run.
4. **Always honest.** When Perch fixes something, you get a complete report of what changed before, after, and why.
**Auto-fix whitelist** (no confirm needed): restart crashed services, kill orphan processes, truncate logs >50MB, renew SSL <7d, clear expired transients, clear `/tmp` PHP sessions older than 24h.
**Confirm-required**: anything that modifies content, deactivates plugins, edits configs, stops services, reboots.
**Never auto, ever**: backup restoration, DB content `DELETE`/`UPDATE` on user data, file system `rm` outside `/tmp`, user account changes, Hetzner-level shutdown.
---
## Why Free Forever
Three reasons, all of them honest:
1. **The brain belongs to you.** A free tool that lives on your server can't be paywalled, ad-funded, or rug-pulled. The data is yours. The code is yours. The whole stack is yours.
2. **Per-server tax is the wrong business model.** Cloudways charges 220% over the underlying VPS. Kinsta charges $35/site. Charging you per server you already own is rent-seeking. Perch refuses to play that game.
3. **Free tools build trust.** Aditya runs other paid products ([Pickle](https://github.com/adityaarsharma/pickle), [RankReady](https://github.com/adityaarsharma/rankready), [Jyotisha](https://adityaarsharma.com/astrology)). The ones who try Perch and find it solid become the audience for those. That's the funnel — built on usefulness, not a paywall.
No "Pro tier." No license keys. No telemetry by default. No SaaS dependency. **Forever.**
---
## Roadmap
**Now (April 2026)** — Sprint 1 shipped
- ✅ MCP server with 150+ tools
- ✅ WordPress Audit Modules (7 deep modules)
- ✅ SQLite self-learning brain
- ✅ Telegram bot with inline buttons + fix-server
- ✅ Slack alert delivery via webhook
- ✅ RunCloud-aware paths (`nginx-rc`, `/etc/nginx-rc/`, per-app users)
**Next 60 days**
- 🔜 Credential vault (AES-256-GCM encryption)
- 🔜 Undo system (`/perch undo`)
- 🔜 Slack bot (slash commands + buttons, full Telegram parity)
- 🔜 Multi-server dashboard (Telegram-first agency view)
- 🔜 Uptime Kuma webhook integration
- 🔜 Self-update flow (`/perch update`)
**Q3 2026**
- 🔜 Laravel module (queue health, schedule runner, artisan automation)
- 🔜 Node.js module (PM2 deep monitoring, memory leak detection)
- 🔜 n8n module (workflow health, execution audit)
- 🔜 Pattern recognition v2 (Perch correlates issues across servers — "this is the 3rd time this month, here's the permanent fix")
**2027**
- Cross-server federated learning (opt-in, anonymized) — Perch learns from the network without anyone giving up their data
---
## Built by Aditya
Aditya Sharma — solo builder, open-source. Marketing & growth lead at [POSIMYTH Innovation](https://posimyth.com). Runs his own infrastructure. Built Perch because he was tired of the choice between $200/mo Kinsta and 4am SSH panic.
[Website](https://adityaarsharma.com) · [Twitter/X](https://x.com/adityaarsharma) · [Pickle](https://github.com/adityaarsharma/pickle) · [RankReady](https://github.com/adityaarsharma/rankready)
Not affiliated with RunCloud. Perch works **with** RunCloud — RunCloud is the safety layer (GUI + isolation + backups), Perch is the intelligence layer on top. Both are needed. Together they replace $35–$115/month managed hosting at $13/month.
---
**Stop renting your server's intelligence. Start owning it.**
[Install Perch](#install-in-5-minutes) · [Read the docs](docs/) · [Star on GitHub](https://github.com/adityaarsharma/perch) · [File an issue](https://github.com/adityaarsharma/perch/issues)