Local Dev on Windows (Vagrant)

Prerequisites

• NodeJS (latest LTS version)
• Vagrant
• Git

Installing

Pyrodactyl is the world's first Pterodactyl panel that can be developed and run locally (with Wings) on Windows machines through Vagrant. Verify you have met the prerequisites above, then follow the steps below.

1. Clone the Pyrodactyl panel repository
2. Install dependencies: npm i
3. Build the application: npm run ship
   • This caches build results and uploads sourcemaps to Sentry
   • Subsequent builds are much faster if code hasn't changed
4. Run vagrant up. This will setup Pterodactyl Wings and the necessary services in order to run Pyrodactyl's databases, services, and app (~15 mins)
5. Login using the credentials shown in your console

   ⚠️ Important: Always use localhost:8000, not 127.0.0.1, to avoid CORS issues!

6. Visit http://localhost:8000/admin to create your first server

Notes

🔄 Development Server

• Running npm run dev serves a development build at localhost:3000 with Hot Module Replacement (HMR)
• For production preview, stop the dev server, run npm run ship, and access http://localhost:3000

🚫 Troubleshooting Connection Issues

• If localhost:3000 hangs indefinitely, check for port conflicts with other applications (e.g., Steam using port 8080)
• After resolving port conflicts, run vagrant reload to reset port mappings

📦 VirtualBox Shared Folders

• If encountering Vagrant was unable to mount VirtualBox shared folders, install vbguest plugin:

  vagrant plugin install vagrant-vbguest

• For existing installations, update with:

  vagrant plugin update vagrant-vbguest

⚡ Performance Tips

• Set up Remote Caching via Turbo for faster builds
• Cached results allow production server builds to complete in milliseconds

🔧 Virtualization Notes

• Avoid Hyper-V as your virtualization layer
• Recommended: VMWare Workstation or VirtualBox
• If prompted for password with Hyper-V, use your Windows credentials