https://github.com/tailscale/hyscale
Hytale on Tailscale Server Manager
https://github.com/tailscale/hyscale
hytale hytale-server hytale-servers tailscale
Last synced: 4 months ago
JSON representation
Hytale on Tailscale Server Manager
- Host: GitHub
- URL: https://github.com/tailscale/hyscale
- Owner: tailscale
- License: bsd-3-clause
- Created: 2026-01-22T08:20:08.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-01-26T20:13:32.000Z (4 months ago)
- Last Synced: 2026-01-28T19:31:47.098Z (4 months ago)
- Topics: hytale, hytale-server, hytale-servers, tailscale
- Language: Go
- Homepage: https://github.com/tailscale/hyscale
- Size: 1.55 MB
- Stars: 35
- Watchers: 2
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# hyscale
**The easiest way to host a private Hytale server for you and your friends**
*A web-based server manager that runs on your private Tailscale network - no port forwarding, no exposing your IP, no firewall headaches.*
---
## Why hyscale?
| Traditional Server Hosting | With hyscale |
|---------------------------|--------------|
| Configure port forwarding on your router | Nothing to configure |
| Share your home IP address with everyone | Only your Tailscale network can see it |
| Dynamic IP? Set up DDNS | Automatic DNS name (e.g., `hytale.your-tailnet.ts.net`) |
| Manage via command line | Web dashboard in your browser |
| FTP for mods | Map a network drive directly! |
## Quick Start
### 1. Download and Run
Download the latest release for your platform and run it:
```
./hyscale
```
### 2. Authenticate with Tailscale
On first run, you'll see an authentication URL:
```
====================================================
AUTHENTICATION REQUIRED
====================================================
Visit this URL to authenticate:
https://login.tailscale.com/...
====================================================
```
Visit the URL and sign in to connect hyscale to your Tailnet.
### 3. Open Dashboard and Start Your Server
Once authenticated, hyscale prints your dashboard URL (something like `https://hytale.your-tailnet.ts.net`).
From the dashboard:
1. Click **Authenticate** and sign in with your Hytale account
2. Click **Download Server** to fetch the server files
3. Click **Start** - you're running!
## Invite Friends
Getting friends connected is simple:
1. **They install Tailscale** - free for personal use at [tailscale.com](https://tailscale.com)
2. **You share your node** - In the [Tailscale admin console](https://login.tailscale.com/admin/machines), click on your hyscale machine, then **Share** to email an invite or create an invite link
3. **They join and connect** - Friends accept your invite and use your server's Tailscale DNS name (shown in your dashboard) to connect in-game
### Allow Game Traffic
Add this rule to your [Tailscale ACL policy](https://login.tailscale.com/admin/acls/file) so shared users can connect:
**ACLs syntax:**
```json
{
"action": "accept",
"src": ["autogroup:member", "autogroup:shared"],
"dst": ["tag:hytale:5520"],
"proto": "udp"
}
```
**Grants syntax:**
```json
{
"src": ["autogroup:member", "autogroup:shared"],
"dst": ["tag:hytale"],
"ip": ["*:5520"],
"proto": "udp"
}
```
Replace `tag:hytale` with your node's actual tag or IP address.
## Features
- **Web Dashboard** - Manage everything from your browser, no terminal required
- **Real-Time Console** - Full terminal emulator with xterm.js
- **Config Editor** - Edit server settings with Monaco (the same editor as VS Code)
- **One-Click Backups** - Back up your entire universe or individual worlds
- **Mod Support** - Enable/disable mods through the UI, upload via WebDAV
- **Auto Updates** - Keep your server up to date automatically
- **Developer Mode** - JDWP debugging support for mod developers
- **Private by Default** - Only devices on your Tailscale network can connect
## Requirements
- A computer to run the server (Windows, macOS, or Linux)
- A Tailscale account (free for personal use)
- A Hytale account (for downloading server files)
That's it. No Java installation needed - hyscale can download and configure it for you.
## Advanced Configuration
Mod Development (JDWP Debugging)
Enable developer mode in the dashboard settings to start the server with JDWP debugging enabled. Connect your IDE's remote debugger to the displayed port.
Multi-Server (Federation)
hyscale supports running multiple servers that can transfer players between them. Configure federation settings in your server's `config.json`.
Running with Docker
**Image:** `ghcr.io/tailscale/hyscale:latest`
Run hyscale in a container:
```bash
docker run -d \
--name hyscale \
-v ./config:/app/config \
-v ./server:/app/server \
-v ./tsstate:/app/tsstate \
ghcr.io/tailscale/hyscale:latest
```
**Volume mounts:**
| Mount | Purpose |
|-------|---------|
| `/app/config` | Configuration files (`hyscale.json`, credentials) |
| `/app/server` | Server files, worlds, mods, backups |
| `/app/tsstate` | Tailscale state (preserves node identity) |
**Docker Compose:**
```yaml
services:
hyscale:
image: ghcr.io/tailscale/hyscale:latest
volumes:
- ./config:/app/config
- ./server:/app/server
- ./tsstate:/app/tsstate
restart: unless-stopped
```
**First-run authentication:** Check logs for the Tailscale auth URL:
```bash
docker logs hyscale
```
**Headless/automated setup:** Set `TS_AUTHKEY` for unattended setup:
```bash
docker run -d \
--name hyscale \
-e TS_AUTHKEY=tskey-auth-xxx \
-v ./config:/app/config \
-v ./server:/app/server \
-v ./tsstate:/app/tsstate \
ghcr.io/tailscale/hyscale:latest
```
Generate auth keys at https://login.tailscale.com/admin/settings/keys
## Troubleshooting
**Friends can't connect?**
- Verify they've joined your Tailnet via the share link
- Check that your ACL policy allows UDP traffic on port 5520
- Have them verify Tailscale is running (`tailscale status`)
**Server won't start?**
- Check the console output in the dashboard for error messages
- Ensure you have enough disk space for server files
- Verify the server files downloaded completely
**Download fails?**
- Re-authenticate with your Hytale account in the dashboard
- Check your internet connection
- Try the download again
## License
BSD-3-Clause License. See [LICENSE](LICENSE) for details.