Development using Vagrant

Prerequisites

Latest version of NodeJS LTS
Vagrant & a Vagrant provider
- On Linux, libvirtd is supported. Otherwise, VirtualBox or VMWare is recommended
- Make sure you also install your provider's Vagrant plugin (i.e. for libvirtd & VMWare)
pnpm (npm install -g pnpm@latest)
Git

Linux-only

You might need nfs-utils. Install your distro's package, then start the nfs-server service. See the Vagrant docs for more information.

Initial setup

Clone the Hydrodactyl panel repository
Install dependencies:
```
pnpm i
```
Build the project:
```
pnpm run ship
```
- Caches build results
- Uploads sourcemaps to Sentry
- Makes subsequent builds without code changes nearly instant
Initialize the environment: vagrant up
- Sets up Wings (backend) and required services
- Configures databases and applications
- Takes approximately 15 minutes
Access Hydrodactyl at localhost:3000 and login with the console-provided credentials

Always use localhost, not 127.0.0.1, to avoid CORS issues!

General usage

You must run Vagrant commands inside the repo folder.

Once you've completed the initial setup:

You can use pnpm run dev to serve a development build with Hot Module Replacement
For a production preview, run pnpm run ship and access it using the address printed by Vagrant in the console
You can stop the Vagrant machine using vagrant halt, and start it back up using vagrant up
You can destroy the VM (which will re-run initial setup next startup) with vagrant destroy

Tips

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

Troubleshooting

Connection issues

If localhost:3000 hangs indefinitely:

Check for port conflicts with other applications (e.g., Steam using port 8080)
After resolving 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

Virtualization Notes

Windows Users: Avoid using Hyper-V with Vagrant. While supported, Hyper-V:

Conflicts with VirtualBox/VMWare (can't run simultaneously)
Has limited Vagrant box compatibility (most boxes are VirtualBox-optimized)
Lacks linked clones (slower provisioning)
Requires manual network configuration

Use VirtualBox or VMWare instead for best results.

If you must use Hyper-V:

Disable other hypervisors first
Use Windows credentials when prompted
Expect reduced performance vs VirtualBox

VM Configuration

Ensure the provider your using has enough RAM specified in the Vagrantfile. Allocating too little RAM can cause packages to fail to install, causing errors.

NFS Mount Error

If you encounter a "Connection refused" error during first vagrant up, retry the command. Otherwise, see the Vagrant troubleshooting guide for NFS.

Permission Issues

Try running commands with sudo:

sudo vagrant up

Development using Vagrant

On this page