Provider guides
Pterodactyl: configuration and operations
Provision game servers on a Pterodactyl panel from paid service products, with lifecycle actions, plan changes, status sync and optional customer power actions.
On this page
Status and workflow
The Pterodactyl extension creates one panel server per Agovena service instance through the Pterodactyl Application API. It supports creation, suspension, unsuspension, termination, plan changes, status synchronization and a customer panel. With an optional Client API key, customers can also start, stop and restart their server. Location, nest, egg and resource limits are product settings of the Provisioning Module, not Core product columns.
Production-ready for the documented scope. Every operation under Supported operations is implemented against the Pterodactyl Application and Client APIs and verified with automated tests that replace the provider with faked HTTP responses, without network calls. Live acceptance on your own Pterodactyl account remains an operator responsibility: run one paid service through creation, installation, suspension, unsuspension and termination on a disposable server before you sell it. Operations under Not supported are not advertised.
Requirements
- Agovena Core
^0.0.1. - The Provisioning Module, enabled before this extension.
- A Pterodactyl panel that the Agovena server can reach, an Application API key and the panel user ID that will own created servers.
- Optional: a Client API key for customer power actions.
Set up the package
- Enable the Provisioning Module, then install and enable Pterodactyl in Admin > Extensions.
- Save
panel_urlas anhttporhttpspanel root without credentials or API path, for examplehttps://panel.example.com, and the Application API key. The key is encrypted at rest and never redisplayed. - Set
user_idto the Pterodactyl user that owns created servers. This is a panel user ID, not an Agovena customer ID. - Optionally save
client_api_keyto enable customer start, stop and restart. The Application and Client keys are not interchangeable. - Keep
verify_tlsenabled. Disable it only for a known self-signed panel. - Run Test connection.
- On each provisionable product, select Pterodactyl and set
location_id,nest_id,egg_idand the limits:memory,swap,disk,io,cpu,databases,allocations,backupsanddedicated_ip.docker_imageandstartupfall back to the egg values when empty.environmentholds newline-separatedKEY=valueegg variables and is stored as a secret.
Supported operations
- Create a server with external ID
agovena-{serviceInstanceId}for the configured owner, location, nest, egg and limits. The mapping is stored inpterodactyl_servers. - Suspend, unsuspend and terminate the mapped server.
- Change plan by applying the new product limits and egg settings to the mapped server.
- Status sync: a suspended server becomes suspended, an active server becomes active,
installingandrestoring_backupstay provisioning,install_failedbecomes failed and any other or malformed status goes to manual review. - Customer panel for the mapped server.
- Power actions start, stop and restart, only when a Client API key is configured. Stop and restart are marked as dangerous actions.
Not supported
- Power actions without a Client API key, and power signals other than start, stop and restart.
- Using an Agovena customer as panel owner. Servers are always created for the configured
user_id.
Failure handling and ownership
- Creates send the stable external ID
agovena-{serviceInstanceId}. A retry looks that ID up before it creates another server, so an interrupted create does not lead to a duplicate. - Ownership and configuration are checked before a stored mapping is used. A malformed mapping, missing allocation or mismatched owner must be investigated, not bypassed by editing a remote ID.
- Disabling the extension preserves service instance rows and the
pterodactyl_serversmapping table. - Redirects are disabled and provider calls are refused in the
demoenvironment. The Application API key is never shown to customers. - Private-network panel hosts are allowed because self-hosted panels often run on a LAN. An Admin who can configure the extension can therefore point Agovena at an internal URL. This is an accepted operator capability, not customer input.
- A stopped game server process is not the same as a suspended service. Keep queue workers and status synchronization running so long installations are reconciled.
Configuration contract
| Field | Type | Required | Secret | Default |
|---|---|---|---|---|
panel_url |
string |
Yes | No | Empty |
application_api_key |
string |
Yes | Yes | Empty |
client_api_key |
string |
No | Yes | Empty |
user_id |
string |
Yes | No | Empty |
verify_tls |
boolean |
No | No | true |
timeout |
string |
No | No | "15" |
client_api_key is optional in the manifest but required for customer power actions. Product settings such as location_id, nest_id and egg_id are configured per product, not in this table. Store secret values only in the protected extension settings, never in product descriptions, URLs, screenshots or shared examples.