Skip to content
agovena.
agovena.
Get started
Community

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

  1. Enable the Provisioning Module, then install and enable Pterodactyl in Admin > Extensions.
  2. Save panel_url as an http or https panel root without credentials or API path, for example https://panel.example.com, and the Application API key. The key is encrypted at rest and never redisplayed.
  3. Set user_id to the Pterodactyl user that owns created servers. This is a panel user ID, not an Agovena customer ID.
  4. Optionally save client_api_key to enable customer start, stop and restart. The Application and Client keys are not interchangeable.
  5. Keep verify_tls enabled. Disable it only for a known self-signed panel.
  6. Run Test connection.
  7. On each provisionable product, select Pterodactyl and set location_id, nest_id, egg_id and the limits: memory, swap, disk, io, cpu, databases, allocations, backups and dedicated_ip. docker_image and startup fall back to the egg values when empty. environment holds newline-separated KEY=value egg 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 in pterodactyl_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, installing and restoring_backup stay provisioning, install_failed becomes 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_servers mapping table.
  • Redirects are disabled and provider calls are refused in the demo environment. 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.

View the package entry

Sources

Search documentation

Search guides, commands and API endpoints

What are you looking for?

Documentation