PteroOps

PteroOps turns Pterodactyl into an AI-operable SRE platform: persistent console intelligence, application detection, crash-loop and health diagnosis, incidents, change correlation, and policy-controlled remediation with rollback, exposed through the Model Context Protocol.

Docs · Getting Started · Installation · Capability Map · Issues

Install

Pick a method, every one below is supported, tested and documented in Installation.

Commands that call scripts/install.sh assume you are inside a checkout. If you downloaded the script instead, drop the scripts/ prefix, the file itself is named install.sh.

Installer details: it checks Node.js ≥ 22 (and can install it: PTEROOPS_INSTALL_NODE=1 / -InstallNode), installs with your choice of --method source|release|npm, drops a pteroops launcher on your PATH, creates the data directory and prints the exact MCP config block. Updating = re-running the same one-liner. Uninstalling keeps your data unless you purge:

bash scripts/install.sh --uninstall [--purge]

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/PotenFYR-Studios/PteroOps-MCP/main/scripts/install.ps1))) -Uninstall [-Purge]

Where things land: macOS/Linux ~/.pteroops/{app|runtime,data} + ~/.local/bin/pteroops; Windows %LOCALAPPDATA%\PteroOps\{app|runtime,data} + …\bin\pteroops.cmd. Manual installs and Docker are unchanged.

Related MCP server: MemoryOS VPS Guardian

Why PteroOps

Posting GET /status is table stakes. PteroOps is the layer that actually understands what runs inside your servers:

• Persistent console intelligence, every line stored, classified and fingerprinted, so 10,000 identical errors become one issue with a count, first/last occurrence and evidence.

• Application awareness, detects paper 1.21.4, node/express, python, Valheim, … from egg/docker/files/console with confidence + evidence, then applies a real profile (fatal signatures, ready markers, config locations, rollback targets).

• Change correlation, every mutation lands in a change ledger with before/after hashes. "What changed 4 minutes before the first error?" is one tool call.

• Cross-server reasoning, shared nodes, databases and proxies are checked before touching anything; correlated outages become one parent incident, not twelve alerts.

• Transactional remediation, plan → risk → approval → backup → apply → verify → stabilize → or automatic rollback. Success means the app is healthy, not that HTTP returned 200.

• AI code debugging, stack frames are mapped back to server files with bounded, numbered snippets; config files are syntax-validated; failing symbols are matched to shipped plugins.

• Never gets ahead of you, policy engine, approvals, dry-runs, maintenance windows, crash-loop restart guard, protected files, redacted secrets.

Use it

PteroOps runs in two modes; both serve the same tools, the same incidents and the same audit trail:

1. Grab an API key. Panel → avatar → Account → API Credentials → Create API Key (ptlc_…; add a ptla_… key for admin tools). Step-by-step: https://docs.potenfyr.in/repo/pteroops-mcp/getting-started.

2. Point your AI app at it. Claude Desktop (stdio):

{
  "mcpServers": {
    "pteroops": {
      "command": "node",
      "args": ["~/.pteroops/app/dist/index.js"],
      "env": {
        "PTERO_PANEL_PROD_URL": "https://panel.example.com",
        "PTERO_PANEL_PROD_CLIENT_KEY": "ptlc_...",
        "PTERO_DEFAULT_PANEL": "prod"
      }
    }
  }
}

Zero-install alternative, the client runs it via npx (published builds):

{ "mcpServers": { "pteroops": { "command": "npx", "args": ["-y", "pteroops-mcp"],
  "env": { "PTERO_PANEL_PROD_URL": "https://panel.example.com",
           "PTERO_PANEL_PROD_CLIENT_KEY": "ptlc_..." } } } }

Remote/server mode. Claude Code, Cursor, VS Code and custom agents can also speak Streamable HTTP: pteroops --transport http behind TLS, then claude mcp add pteroops --transport http https://pteroops.example.com/mcp --header "Authorization: Bearer $PTERO_HTTP_TOKEN". Reverse-proxy examples: deploy/nginx.conf.example, deploy/Caddyfile.example. Full recipes: Integrations.

On Windows the installed path is %LOCALAPPDATA%\PteroOps\app\dist\index.js (the installer prints the exact block). Prefer a config file to env vars? Point PTEROOPS_CONFIG=~/pteroops.yaml at a config file and drop the env block.

3. Ask.

• "Use pteroops to check the health of all my servers and explain anything unhealthy. Do not restart anything."

• "The creative server broke after last night's update, what changed and why?"

• "Several servers went down at once. Investigate the shared cause before restarting anything."

• "Propose a fix for the crash loop, show me the risk and rollback, then wait for my approval."

Watch instead of asking? The HTTP mode serves a read-only console at http://127.0.0.1:8080/ui (append ?token=… once), plus Prometheus metrics at /metrics.

The whole loop, one story

"My Minecraft server keeps restarting. Find out why."

ptero_get_health → crash_loop, 4 short exits, avg runtime 38s · ptero_analyze_logs → java.lang.OutOfMemoryError ×4 with grouped stack trace · ptero_detect_application → paper 1.21.4 (0.94, with evidence) · ptero_debug_context → the failing class and the config around it · ptero_get_change_history → EssentialsX.jar replaced 4 minutes before the first OOM · ptero_diagnose → causes with confidence, recommendations with risk + rollback, incident opened · you approve → ptero_execute_remediation → restart → health check → stabilization → succeeded, or rollback if it got worse. Fully audited, fully reversible.

A real captured session is in Demo transcript, regenerate it yourself with npm run demo.

Capability coverage

Everything in the classic comparison matrix is implemented, discovery, status, resources, power, console, files, backups, databases, schedules, allocations, subusers, admin API, auth, multi-tenancy, audit, plus the parts that make it an SRE layer:

The full mapping (including the honest PARTIAL on Git dirty-state) lives in Capability Map.

MCP surface

63 tools · 14 resources · 8 prompts, all capability-gated, annotated and audited:

Plus resources (ptero://servers, ptero://server/{id}/health, …) and prompts (diagnose-server, investigate-crash-loop, prepare-remediation, …). Schemas, annotations and when-NOT-to-use notes: MCP reference.

Configuration at a glance

# pteroops.config.yaml  (or pure env vars, the installer's JSON block works too)
panels:
  production:
    url: https://panel.example.com
    clientKey: ${PTERO_PROD_CLIENT_KEY}       # ptlc_…
    applicationKey: ${PTERO_PROD_APP_KEY}     # ptla_… (admin tools)

defaultPanel: production
groups:                { minecraft: ["production/*"] }        # drift + canary
schedules:
  - { name: nightly-audit, kind: dependency_audit, every: 24h, scope: ["*"] }
policy:
  blockedCommands: ["^rm\\s+-rf\\s+/", "^mkfs"]
  networkProbeAllowed: false               # probes are opt-in and scoped
approval:
  requireApproval: [file_write, restore_backup, git_rollback]
storage:
  driver: sqlite                           # or postgres for multi-instance
  # redisUrl: redis://127.0.0.1:6379      # distributed locks

Every option and env var: Configuration.

Security by default

• Tools whose capabilities the configured keys can't satisfy are never registered (ptero_get_capabilities proves it).

• Risk levels LOW→CRITICAL; MEDIUM+ needs approval; CRITICAL cannot be automated at all.

• File edits require the current hash (stale-write refusal), snapshot first, diff and re-verify.

• Crash-loop guard refuses blind restarts; restart budgets are enforced.

• Every secret-bearing string passes the redaction engine (logs, errors, MCP, audit, console, incidents), covered by a dedicated test corpus.

• Multi-tenant isolation is enforced in repositories, not just handlers.

Threat model: SECURITY.md.

Deployment

Docker (single command):

docker run -d --name pteroops -v pteroops-data:/app/data \
  -e PTERO_PANEL_PROD_URL=https://panel.example.com \
  -e PTERO_PANEL_PROD_CLIENT_KEY=ptlc_... \
  -e PTERO_HTTP_TOKEN=$(openssl rand -hex 32) \
  -p 127.0.0.1:8080:8080 pteroops --transport http
# MCP: http://127.0.0.1:8080/mcp · console: /ui · metrics: /metrics

Docker Compose: docker compose up -d (edit the env defaults in docker-compose.yml).

Kubernetes: kubectl apply -f deploy/k8s.yaml. Deployment + PVC + Service + probes; create the pteroops-secrets secret first (the manifest documents the command). For multi-instance replicas switch storage to PostgreSQL and set a Redis URL for distributed locks.

systemd: copy dist/ and deploy/pteroops.service to the server, create the pteroops user, put your env in /etc/pteroops/pteroops.env and systemctl enable --now pteroops.

Remote access: run with --transport http behind TLS (deploy/nginx.conf.example or deploy/Caddyfile.example); always set PTERO_HTTP_TOKEN off-loopback. Every deployment option (plus upgrading, uninstalling and air-gapped installs) is covered in Installation.

Documentation

Rendered documentation: **https://docs.potenfyr.in/repo/pteroops-mcp · Every table row below is mirrored in the hub.

Development

npm run lint        # eslint (incl. no-floating-promises)
npm run typecheck   # strict TypeScript
npm run test        # vitest: 270 tests (SQLite); 273 with PostgreSQL + Redis env vars
npm run build       # tsc → dist/
npm run demo        # regenerate https://docs.potenfyr.in/repo/pteroops-mcp/demo-transcript from a real run

All four gates must pass before a change is complete. CI runs Node 22 + 24, a PostgreSQL 16 service job and a Redis 7 job; the mock panel + in-memory MCP transport exercise the full investigation and remediation flows end-to-end.

Contributing

Small slices, tests with every behavior change, the docs hub updated in the same change, see CONTRIBUTING.md and AGENTS.md for coding agents.

License

MIT, see LICENSE.