Pterodactyl Manager

A Discord-native operations center for Pterodactyl hosting. It connects multiple panels, gives clients a graphical server control dashboard, records privileged actions, collects historical metrics, and opens infrastructure incidents when a server or panel becomes unhealthy.

Built and maintained by WroxExM.

Version 2 is a ground-up upgrade of the original ECH Host Manager. Existing server assignments and administrator records remain compatible, while the new design adds encrypted credentials, proper access boundaries, multi-panel support, monitoring history, and Discord Components V2.

What works today

• Multi-panel connections with separate Application and Client API credentials
• AES-256-GCM encryption for every stored Pterodactyl API key
• Discord account to Pterodactyl Client API identity linking
• Owner, administrator, operator, viewer, and per-server access checks
• Component V2 server dashboards with live CPU, RAM, disk, network, uptime, allocation, and power controls
• Confirmations for dashboard power actions and administrator-only process kill
• Live console command delivery with an audit record
• Background collection of server metrics with 30-day retention and locally rendered PNG trend charts
• CPU, memory, disk, API availability, and metrics incidents with cooldown-based deduplication
• Incident list and resolution workflow
• Panel API latency and node diagnostics
• Searchable and exportable audit history with automatic secret redaction
• Global slash-command registration, or instant single-guild registration during development
• Graceful startup and shutdown with no artificial delays

Architecture

Discord commands, buttons and modals
                |
       Authorization policy
                |
    +-----------+-----------+
    |                       |
Application API          Client API
ptla_: panels, nodes     ptlc_: power, console,
and administration       resources and account link
    |                       |
    +------ Pterodactyl ----+
                |
   SQLite audit, metrics and incidents

Pterodactyl deliberately separates its APIs. An Application key alone cannot power a server or read live resource usage; a Client key alone cannot inspect the full infrastructure. The setup validates both keys before saving a connection.

Requirements

• Node.js 20.17 or newer
• A Discord application and bot token
• Pterodactyl Panel 1.x reachable over HTTPS
• An Application API key (ptla_…) created by a panel administrator
• A Client API key (ptlc_…) with access to the servers being monitored

The bot needs these Discord permissions:

• View Channels
• Send Messages
• Use Application Commands
• Embed Links
• Attach Files
• Read Message History

The Message Content intent is not required unless legacy prefix commands are explicitly enabled.

Installation

git clone https://github.com/WroxExM/PETRODTYL-MANAGER.git
cd PETRODTYL-MANAGER
npm install

Copy .env.example to .env, then create an encryption key:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Paste the result into ENCRYPTION_KEY. Fill in TOKEN and CLIENT_ID. During development, set GUILD_ID so command updates appear immediately. Leave it empty for global commands; Discord may take time to distribute global updates.

Start the bot:

npm run check
npm start

In Discord, an administrator runs /panel setup. The modal verifies both API keys against the supplied HTTPS panel URL and only then stores their encrypted values.

Commands

Command	Purpose	Minimum access
/panel setup	Add or update a secure panel connection	Administrator
/panel overview	List connected panels	Viewer
/panel health	Test API latency and node availability	Viewer
/account link	Link a personal Pterodactyl Client API identity	User
/account status	Inspect the active link without revealing its key	User
/account unlink	Revoke the stored linked credential	User
/access assign	Grant expiring viewer or operator server access	Administrator
/access revoke	Revoke a server assignment	Administrator
/access list	Review the assignment registry	Administrator
/access emergency-lock	Lock all non-admin controls during an incident	Administrator
/server list	List accessible servers	Viewer/server assignment
/server dashboard	Open live resource and power controls	Viewer/server assignment
/server power	Start, stop, restart, or kill a server	Operator; admin for kill
/server console	Send and audit a console command	Operator
/monitor history	Show raw-measurement resource summaries	Viewer/server assignment
/incident list	Review active monitoring incidents	Operator
/incident resolve	Close an incident with a resolution	Operator
/audit search	Search action history	Administrator
/audit export	Download the latest audit records as JSON	Administrator

Every /server command accepts an optional panel connection ID from /panel overview. When omitted, the default connection is used. This lets one bot installation manage panels in different regions or hosting brands without mixing their credentials.

The old prefix command files remain for existing installations but are disabled by default. Legacy embed-based slash commands are no longer registered because they bypass the version 2 policy layer. Set ENABLE_PREFIX_COMMANDS=true only when the prefix commands are required, and enable Discord's Message Content intent.

Access model

Global owners are configured with OWNER_IDS. Discord administrators and roles listed in ADMIN_ROLE_IDS are administrators. OPERATOR_ROLE_IDS can control assigned servers, while VIEWER_ROLE_IDS receives read-only access. IDs are comma-separated.

Server-specific assignments are stored in user_servers. An assignment can include a permission level and expiry time. Every protected interaction rechecks authorization at execution time, including after a confirmation button is pressed.

Monitoring and incidents

The monitoring worker runs every 60 seconds by default. Change this with MONITOR_INTERVAL_SECONDS (minimum 30 seconds). It collects:

• process state and uptime
• absolute CPU usage
• memory and disk bytes
• inbound and outbound network bytes

Thresholds are controlled by CPU_WARNING_PERCENT, MEMORY_WARNING_PERCENT, and DISK_WARNING_PERCENT. Incidents are deduplicated for INCIDENT_COOLDOWN_MINUTES, so one unhealthy server does not flood Discord. Set ALERT_CHANNEL_ID to publish Component V2 incident cards.

Health scores and future predictions should always be based on stored measurements. The bot does not invent approximate scores when the panel has not supplied enough data.

Security notes

• Never commit .env or paste an API key into a normal Discord message.
• Rotate any key that was previously published in source code, screenshots, or logs.
• Use a dedicated panel service account with only the permissions the bot needs.
• Keep ENCRYPTION_KEY outside the repository and back it up securely. Existing encrypted keys cannot be recovered if it is lost.
• kill, restore, reinstall, delete, and bulk destructive operations should remain approval-gated. Version 2 currently exposes kill only to administrators and confirms button-based power actions; delete/reinstall/restore are intentionally not exposed yet.
• The audit exporter redacts fields whose names contain token, key, secret, or password.

Project layout

commands/       Slash and compatibility commands
database/       SQLite connection and migrations
interactions/   Persistent button and modal handlers
services/       Authorization, audit, incidents and monitoring
ui/             Reusable Discord Component V2 layouts
utils/          Pterodactyl API and encrypted-secret helpers
scripts/        Local validation

Planned expansion

The full product direction is documented in message.txt. The foundation is designed for phased additions without putting unsafe placeholders in production:

1. backup, schedule, file, allocation and database managers
2. two-person approvals for delete, reinstall, restore and bulk actions
3. WebSocket console threads and rendered historical charts
4. automation rules with trigger, condition, action, cooldown and fallback
5. Discord OAuth web dashboard and device/session management
6. deployment pipelines, expiry policies, billing hooks and external storage
7. PostgreSQL/Redis workers for high-availability multi-instance deployments

Contributions should preserve the API separation, authorization checks, redacted audit trail, and confirmation requirements used by the current commands.

License

Released under the MIT License.