Install the Hytale Depot Pterodactyl addon safely

This addon is installed into an existing Pterodactyl Panel checkout. It is not installed into Wings. The examples below assume your panel root is /var/www/pterodactyl, your downloaded addon zip is stored under /srv/pterodactyl-addons/hytaledepot/downloads, and your extracted working copy is stored under /srv/pterodactyl-addons/hytaledepot/releases/1.0.0.

The addon installer itself requires bash, rsync, and python3. The panel rebuild steps continue to use the PHP, Node, and Yarn stack that your current Pterodactyl installation already relies on.

sudo apt update
sudo apt install -y rsync python3 unzip tar

sudo apt update
sudo apt install -y rsync python3 unzip tar

sudo dnf install -y rsync python3 unzip tar

Run the install, build, and artisan commands as the same account that normally maintains your panel checkout. If your panel files are owned by www-data or nginx, keep ownership and build behavior consistent with the rest of that panel deployment.

Your specific failure came from this line in the panel checkout: package.json currently requires node >=22. If the host still uses Node 20, yarn install andyarn build:production will stop before the addon UI can be rebuilt.

Check the live requirement and the installed runtime first:

cd /var/www/pterodactyl
grep -n '"node"' package.json
node --version
yarn --version

On your server, the panel currently expects Node 22 or newer. If the installed version is lower, upgrade Node before you continue.

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
sudo corepack enable
sudo corepack prepare yarn@1.22.22 --activate

node --version
yarn --version

curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo dnf install -y nodejs
sudo corepack enable
sudo corepack prepare yarn@1.22.22 --activate

node --version
yarn --version

If you already finished the addon migration but the frontend build failed on the Node version check, you do not need to reinstall the addon again. Upgrade Node, then rerun only the frontend rebuild steps:

cd /var/www/pterodactyl
php artisan down
yarn install
yarn build:production
php artisan optimize:clear
php artisan up

The safest install flow is backup first, install second. The addon installer now creates a file backup automatically, but you should still take one panel snapshot and one database dump before the first install on a production panel.

sudo mkdir -p /root/ptero-backups
sudo tar   --exclude='node_modules'   --exclude='vendor'   -czf /root/ptero-backups/pterodactyl-panel-before-hytaledepot-addon.tar.gz   /var/www/pterodactyl

For the database backup, do not guess the database name. A normal Pterodactyl panel install usually creates the database as panel, not pterodactyl. Read the real values from your live panel .env first:

cd /var/www/pterodactyl
grep -E '^(DB_HOST|DB_PORT|DB_DATABASE|DB_USERNAME)=' .env

If your panel follows the official Pterodactyl install docs, the values are usually close to:

DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=panel
DB_USERNAME=pterodactyl

Then run the backup with those exact values. A safe example for the common official setup is:

mysqldump   -h 127.0.0.1   -P 3306   -u pterodactyl   -p   --single-transaction   --routines   --triggers   panel   > /root/ptero-backups/pterodactyl-db-before-hytaledepot-addon.sql

If your panel uses a different database host, port, user, or database name, replace those values with the ones you saw in/var/www/pterodactyl/.env.

The addon installer also stores file-level restore data under:

/var/www/pterodactyl/storage/app/hytaledepot-addon-backups/
  <timestamp>/
    manifest.json

That backup contains the original copies of every panel file the installer touched. You can restore from it later with restore.sh.

This is the missing part most people need first: where the addon zip should live, where it should be extracted, and where the installer should point.

Downloaded zip on the panel host:
/srv/pterodactyl-addons/hytaledepot/downloads/hytaledepot-pterodactyl-addon-1.0.0.zip

Extracted addon working directory:
/srv/pterodactyl-addons/hytaledepot/releases/1.0.0/

Real Pterodactyl panel root:
/var/www/pterodactyl/

Run these from the extracted addon directory:
check-compat.sh
install.sh
update.sh
uninstall.sh
restore.sh

Run these from the live panel root:
php artisan ...
yarn install
yarn build:production
grep ... .env

1. Own the addon in Hytale Depot, then click Download addon from the addon product page or your account addon page.
2. Save the zip on your own computer first, then copy it to the panel host, or download it directly on the panel host from the signed URL.
3. Create a permanent download directory on the panel host such as /srv/pterodactyl-addons/hytaledepot/downloads.
4. Create a separate extracted working directory such as /srv/pterodactyl-addons/hytaledepot/releases/1.0.0.
5. Run check-compat.sh and install.sh from that extracted working directory, not from the panel root.

If the file was downloaded to your laptop or desktop browser, copy it to the panel host with a command like this:

sudo mkdir -p /srv/pterodactyl-addons/hytaledepot/downloads
scp "$HOME/Downloads/hytaledepot-pterodactyl-addon-1.0.0.zip"   your-user@your-panel-host:/srv/pterodactyl-addons/hytaledepot/downloads/

If you prefer to download directly on the panel host, open the signed installer URL from Hytale Depot and use it immediately before it expires:

sudo mkdir -p /srv/pterodactyl-addons/hytaledepot/downloads
curl -fL "SIGNED_URL_FROM_HYTALE_DEPOT"   -o /srv/pterodactyl-addons/hytaledepot/downloads/hytaledepot-pterodactyl-addon-1.0.0.zip

Before extracting, list the archive contents and confirm the package includes restore.sh:

unzip -l   /srv/pterodactyl-addons/hytaledepot/downloads/hytaledepot-pterodactyl-addon-1.0.0.zip

If restore.sh is missing from that list, delete the zip and download it again before you continue.

Then extract the zip into the working directory. Do not extract it over the live panel tree:

sudo mkdir -p /srv/pterodactyl-addons/hytaledepot/releases/1.0.0
sudo unzip   /srv/pterodactyl-addons/hytaledepot/downloads/hytaledepot-pterodactyl-addon-1.0.0.zip   -d /srv/pterodactyl-addons/hytaledepot/releases/1.0.0

cd /srv/pterodactyl-addons/hytaledepot/releases/1.0.0
ls -la
chmod +x check-compat.sh install.sh update.sh uninstall.sh restore.sh

The final chmod +x step is only there to make the commands work even if the zip was extracted on a system that dropped shell execute permissions.

After extraction, your addon working directory should look like this:

README.md
check-compat.sh
install.sh
update.sh
uninstall.sh
restore.sh
package-release.sh
overlay/
snippets/

The overlay copies real files into the panel checkout. The addon does not patch random vendor files and it does not touch Wings or daemon configuration.

Before running the installer, open your panel environment file at /var/www/pterodactyl/.env and add or verify these values:

HYTALEDEPOT_ADDON_API_BASE_URL=https://hytaledepot.net/api
HYTALEDEPOT_ADDON_ALLOWED_DOWNLOAD_HOSTS=hytaledepot.net
HYTALEDEPOT_ADDON_VERSION=1.0.0

There is no addon license secret to paste into .env. The panel is linked interactively from the Hytale Depot account that owns the addon.

If your panel sees a 403 page or a temporary connectivity banner, review the packaged addon README from the downloaded addon zip or contact Hytale Depot support. Infrastructure-specific details are intentionally not published on this public docs page.

Run the commands below exactly from the extracted addon working directory. Each command has a specific purpose.

cd /srv/pterodactyl-addons/hytaledepot/releases/1.0.0

# 0. Put the panel into maintenance mode during the file update window
cd /var/www/pterodactyl
php artisan down

# 1. Return to the extracted addon directory
cd /srv/pterodactyl-addons/hytaledepot/releases/1.0.0

# 2. Verify this panel checkout matches the supported layout
./check-compat.sh /var/www/pterodactyl

# 3. Copy the addon overlay into the real panel root
./install.sh /var/www/pterodactyl

# 4. Switch into the real panel root for artisan and yarn commands
cd /var/www/pterodactyl

# 5. Confirm you are editing the expected panel and database config
pwd
grep -E '^(APP_URL|DB_HOST|DB_PORT|DB_DATABASE|DB_USERNAME)=' .env

# 6. Create addon database tables
php artisan migrate --force

# 7. Refresh node dependencies if needed
yarn install

# 8. Rebuild the panel frontend so the Hytale Depot tab appears
yarn build:production

# 9. Clear Laravel caches and bring the panel back up
php artisan optimize:clear
php artisan up

What each step does:

• php artisan down puts the panel into maintenance mode while files are being changed.
• check-compat.sh /var/www/pterodactyl stops early if your panel source tree is not compatible.
• install.sh /var/www/pterodactyl copies the overlay from the current extracted addon directory into the panel root and injects route snippets.
• pwd and grep ... .env confirm you are inside the real panel root and looking at the actual live database settings.
• php artisan migrate --force creates the addon installation and installed-resource tables.
• yarn install makes sure the panel frontend dependencies are in place before rebuilding.
• yarn build:production rebuilds the panel frontend with the new Hytale Depot tab and route.
• php artisan optimize:clear clears cached routes, config, and views so the new files are used immediately.
• php artisan up takes the panel back out of maintenance mode.

Once those commands are complete, restart the panel service stack in the same way you normally apply panel code changes on that host.

Panel-level linking now belongs in the Pterodactyl admin control panel, not on normal server pages. A panel root admin should open /admin/settings/hytaledepot-addon after installation.

1. Open the Pterodactyl admin control panel and go to Settings → Hytale Depot Addon.
2. Click Start Link there. The admin page will show the installation code and approval link.
3. Open your Hytale Depot account page at /pl/account/pterodactyl-addon.
4. Approve the pending panel installation with the Hytale Depot addon license you want to use.
5. Return to the Pterodactyl admin addon page and click Refresh Link Status.
6. Choose whether the addon is enabled, whether it is limited to selected eggs, and which default install paths it should use.

After approval, normal server users no longer need to see panel installation details. They only see the Hytale Depot tab on servers whose eggs are allowed by the panel admin settings.

Once the panel admin has linked the panel and enabled the addon for selected eggs, the server tab shows only free, public, approved, addon-enabled resources on those allowed servers. Panel installation details are reserved for panel admins in the admin settings page.

plugin      -> /plugins
mod         -> /mods
config      -> /config/hytaledepot
server_pack -> /packs
map_build   -> /data/hytaledepot

Archive-based resources are checked before extraction, and the panel only accepts download URLs from the hosts you allow inHYTALEDEPOT_ADDON_ALLOWED_DOWNLOAD_HOSTS.

Updating the addon re-runs the install flow on top of the existing panel checkout and creates a fresh backup before making changes.

cd /srv/pterodactyl-addons/hytaledepot/releases/1.0.0

cd /var/www/pterodactyl
php artisan down

cd /srv/pterodactyl-addons/hytaledepot/releases/1.0.0
./update.sh /var/www/pterodactyl

cd /var/www/pterodactyl
php artisan migrate --force
yarn install
yarn build:production
php artisan optimize:clear
php artisan up

If you need to back out quickly, restore the latest automatic backup:

cd /srv/pterodactyl-addons/hytaledepot/releases/1.0.0
./restore.sh /var/www/pterodactyl

To restore from a specific saved backup directory:

./restore.sh   /var/www/pterodactyl   /var/www/pterodactyl/storage/app/hytaledepot-addon-backups/20260531-210000

If you want a full addon removal instead of a quick file restore, run:

cd /srv/pterodactyl-addons/hytaledepot/releases/1.0.0

cd /var/www/pterodactyl
php artisan down

cd /srv/pterodactyl-addons/hytaledepot/releases/1.0.0
./uninstall.sh /var/www/pterodactyl

cd /var/www/pterodactyl
yarn install
yarn build:production
php artisan optimize:clear
php artisan up

The uninstall script now tries the backup restore path first. If no backup exists, it falls back to marker-based removal of the injected routes and addon files.

These new files are copied into the panel checkout:

app/Http/Controllers/Api/Client/Servers/HytaleDepotAddonController.php
app/Models/HytaleDepotAddonInstallation.php
app/Models/HytaleDepotAddonServerResource.php
app/Services/HytaleDepot/HytaleDepotAddonManager.php
database/migrations/2026_05_31_000001_create_hytaledepot_addon_tables.php
resources/scripts/components/server/hytaledepot/HytaleDepotAddonContainer.tsx

These existing files are modified by snippet injection:

routes/api-client.php
resources/scripts/routers/routes.ts

The installer backup contains original copies of both modified files and any overlay target that existed before the addon was installed.