Hybrid P2P & Distributed Cloud Infrastructure for Decentralized Game Server Hosting
PeerHost is a distributed, hybrid peer-to-peer (P2P) hosting infrastructure engineered to eliminate the high cost of dedicated 24/7 game servers. By decoupling session coordination from heavy game server execution, PeerHost allows any player in a community to dynamically claim the host role, synchronize world state in real time, and route player traffic securely via Cloudflare Tunnels without requiring port forwarding or public IP exposure.
Hardware and runtime requirements are determined by PeerHost's architecture, which separates the lightweight FastAPI coordinator service from the Java-based Minecraft server process.
The coordinator server handles session locks, REST API routes, and world delta backups. It does not execute game logic or render chunks, making low-cost cloud instances sufficient.
| Hardware Component | Minimum Requirement | Recommended Specification |
|---|---|---|
| CPU Architecture | 1 vCPU (x86_64 / ARM64) | 2 vCPUs |
| System Memory (RAM) | 512 MB | 1 GB to 2 GB |
| Storage Capacity | 5 GB (SSD) | 20 GB+ (SSD, depending on world size) |
| Network Upload/Download | 20 Mbps bandwidth | 100 Mbps+ unmetered |
| Operating System | Linux (Ubuntu 22.04 LTS / Debian 12) or Windows | Linux (Ubuntu 22.04 LTS) |
| Runtime Environment | Python 3.11+ | Python 3.11+ with uvicorn & SQLModel |
When a player claims the active host role, their local machine runs the Minecraft server engine (server.jar), the cloudflared TCP tunnel daemon, and the PeerHost sync engine.
| Hardware Component | Minimum Requirement | Recommended Specification |
|---|---|---|
| Processor (CPU) | Quad-Core 3.0 GHz (e.g., Intel i5 8th Gen / Ryzen 5 2600) | Hexa-Core 3.5 GHz+ (e.g., Intel i5 12th Gen / Ryzen 5 5600X) |
| System Memory (RAM) | 8 GB RAM (4 GB allocated to Java heap -Xmx4G) |
16 GB RAM (8 GB allocated to Java heap -Xmx8G) |
| Java Runtime Engine | JDK 17 (Required for Minecraft 1.20+) | JDK 21 LTS |
| Storage Media | 10 GB High-Speed NVMe / SSD | 30 GB+ High-Speed NVMe |
| Network Upload Speed | 10 Mbps Upload (For 2–4 connected players) | 50 Mbps+ Upload (For 8+ connected players) |
| Operating System | Windows 10/11 64-bit or Linux | Windows 11 64-bit |
Note on Memory Allocation: The Java heap size is configurable in
app/settings.jsonvia thestart_commandproperty (java -Xms4G -Xmx4G -jar server.jar nogui). Ensure the client machine has sufficient physical RAM to support both the Java heap and the operating system.
sequenceDiagram
autonumber
actor Player as Player / Client
actor Host as Host Player
participant Coord as Central Coordinator (FastAPI)
participant CF as Cloudflare Tunnel
Player->>Coord: Check Session Status & Active Host
alt No Active Host
Host->>Coord: Claim Host Lock & Sync World Data
Coord-->>Host: Stream Latest World Backup
Host->>Host: Launch Local Minecraft Server & Cloudflare Tunnel
Host->>Coord: Send Heartbeat & Update Game Hostname
end
Player->>CF: Connect to game.domain.com
CF->>Host: Route TCP traffic (localhost:25565)
Host->>Coord: Periodic Auto-Sync World Delta
| Capability | Traditional VPS | Pure P2P (Hamachi/VPN) | PeerHost |
|---|---|---|---|
| Coordinator Cost | High ($15–$50/mo) | Free | Ultra Low-spec VPS ($3/mo) |
| Server Execution | Always-on VPS RAM/CPU | Host PC | Host PC (Shared Duty) |
| 24/7 Availability | Always Online | Requires Host Online | Dynamic (Anyone can claim Host) |
| World Persistence | Centralized | Host-dependent | Automatic Cloud Sync |
| Port Forwarding | Mandatory | Requires VPN App | None (Cloudflare Tunnel) |
| DDoS Protection | Paid Extra | None | Built-in Cloudflare Protection |
- Download
PeerHost.exefrom the latest GitHub Releases. - Place
PeerHost.exein a dedicated local folder. - Launch
PeerHost.exeand enter your player username. - Wait for automatic world synchronization.
- Launch Minecraft and connect to:
127.0.0.1:2812.
git clone https://github.com/Chouwzi/PeerHost.git
cd PeerHost
pip install -r requirements.txt{
"heartbeat_interval": 2,
"lock_timeout": 7,
"start_command": "java -Xms4G -Xmx4G -jar server.jar nogui",
"mirror_sync": true,
"secret_key": "YOUR_SECURE_RANDOM_SECRET_KEY",
"algorithm": "HS256",
"tunnel_name": "PeerHost",
"game_hostname": "mc.yourdomain.com",
"game_local_port": 2812
}PeerHost uses two distinct Cloudflare Tunnels:
- API Tunnel (HTTP): Exposes the FastAPI coordinator endpoint.
- Game Tunnel (TCP): Routes raw Minecraft TCP traffic to the active host.
Download cloudflared from Cloudflare Releases and place binaries in:
app/storage/server_tunnel/cloudflared.exeapp/storage/world_data/cloudflared-tunnel/cloudflared.exe
cd app/storage/server_tunnel
.\cloudflared.exe tunnel login
.\cloudflared.exe tunnel create peerhost-api
.\cloudflared.exe tunnel route dns peerhost-api peerhost.yourdomain.comcd app/storage/world_data/cloudflared-tunnel
.\cloudflared.exe tunnel create peerhost-game
.\cloudflared.exe tunnel route dns peerhost-game mc.yourdomain.comuvicorn app.main:app --host 0.0.0.0 --port 8000| Option Key | Description | Default |
|---|---|---|
heartbeat_interval |
Active host heartbeat signal interval (seconds). | 2 |
lock_timeout |
Session lock expiration window (seconds). | 7 |
start_command |
Minecraft server launch command. | - |
mirror_sync |
Synchronize and mirror cloud world deltas. | true |
game_hostname |
Public domain for Minecraft connection routing. | - |
game_local_port |
Client local loopback port for Minecraft client. | 2812 |
PeerHost/
├── app/ # FastAPI Central Coordinator Service
│ ├── main.py # Server entry point & API router
│ ├── settings.json # System configuration
│ └── storage/ # Cloud world storage & tunnel configs
├── client/ # Python Client Core & Sync Engine
├── client_launcher/ # GUI / CLI Client Executable Launcher
├── requirements.txt # Python dependency definitions
└── LICENSE.md # MIT License declaration
This project is licensed under the MIT License.
Crafted with ❤️ by @Chouwzi in collaboration with Antigravity