Last updated on 5th March 2026

Configuring a Pterodactyl Server

This guide explains how to configure DeployHQ to deploy files directly to a game server managed by Pterodactyl, an open-source game server management panel. This is ideal for deploying plugins, configuration files, mods, and other assets to servers running Minecraft, CS2, Rust, and other games.

Prerequisites:

  • A Pterodactyl panel with at least one game server configured
  • A Client API key (not an Application API key) from your Pterodactyl account

Step 1: Create a Client API Key

  1. Log into your Pterodactyl panel
  2. Click your username in the top-right corner
  3. Select API Credentials
  4. Enter a description (e.g. "DeployHQ") and click Create
  5. Copy the API key immediately -- it will only be shown once

The key will start with ptlc_. If your key starts with ptla_, that is an Application API key and will not work. You need a Client API key.

Step 2: Find Your Server Identifier

Your server's short identifier is the 8-character code shown in the panel URL when viewing a server. For example, if the URL is:

https://panel.example.com/server/1a2b3c4d

The server identifier is 1a2b3c4d.

Step 3: Add a Pterodactyl Server in DeployHQ

  1. Navigate to your project in DeployHQ
  2. Go to Servers & Groups and click New Server
  3. Select Pterodactyl as the protocol

Fill in the following fields:

Panel Connection

Enter the full URL of your Pterodactyl panel (e.g. https://panel.example.com). If you omit the protocol, HTTPS will be added automatically.

Authentication

Paste the Client API key you created in Step 1. The key must start with ptlc_.

Server

  • Server Identifier: The 8-character hex ID from Step 2
  • Base Directory: The directory on the game server where files should be deployed. Defaults to / (the server root). For example, set this to /plugins to deploy directly into the plugins folder.

Once you save, DeployHQ will verify the connection by listing the files in the base directory and performing a write test.

Deploying to Pterodactyl

Deployments to Pterodactyl work the same way as other file-based protocols in DeployHQ. On each deployment:

  • New and changed files are uploaded to the game server
  • Deleted files are removed from the game server
  • Directories are created automatically as needed

You can set up automatic deployments to push updates to your game server whenever you commit to your repository.

Common Use Cases

  • Minecraft plugins: Set the base directory to /plugins and deploy your compiled .jar files
  • Server configuration: Deploy server.properties, permission files, and other configs
  • Mod packs: Deploy mod files to the appropriate directory
  • Custom maps or worlds: Deploy world data to the server

Permissions

The Client API key inherits the permissions of the Pterodactyl user who created it. Ensure your user account has file management permissions for the target server. If you receive permission errors, check your user's server subuser permissions in the Pterodactyl panel.

Firewall and Network

DeployHQ connects to your Pterodactyl panel over HTTPS (port 443). Ensure your panel is accessible from the internet. If your panel uses a non-standard port, include it in the panel URL (e.g. https://panel.example.com:8443).

For the list of DeployHQ IP addresses that may need to be whitelisted, refer to our IP addresses guide.