ZeroBlockBridge

Minecraft Server Management with Built-in Tunneling, Backups & Automation

ZeroBlockBridge is a desktop application that simplifies Minecraft server creation and management, designed with the intent to provide a user‑friendly interface that can safely turn any computer into a Minecraft server. Host a server to play with friends and community — without complex setup, port forwarding or unsafe configurations.

---

Features

• Server Management: 6-step creation wizard with a summary/review step, multi-version (Vanilla/Fabric/Forge/Paper/Purpur), server templates, smart caching, RAM allocation, properties editor, integrated console with search and colored log lines, player management dashboard with whitelist controls, right-click server deletion.
• Automation & Backups: One-click ZIP backups, scheduled restarts (interval or daily time), multi-stage warnings with countdown, auto-backup scheduler, .zbbpack export/import for moving a server between machines.
• Performance Monitoring: Lag spike detection, server heartbeat monitoring.
• Modrinth Mod Browser: Search, filter, one-click install, manage installed mods, check updates against Modrinth API. Automatically excludes client-only mods from results and badges mods that also work client-side, so you only see content that actually runs on your server. Loader-aware Optimizer Bundle (Fabric or Forge) for one-click performance tuning.
• Tunneling: Built-in Playit.gg integration, persistent sessions, soft/full reset, DNS recovery chain, agent heartbeat, circuit breaker with exponential backoff.
• Auto-Healing: Watchdog (crash detection + JSON crash reports), heartbeat (zombie detection), lag monitor, command sanitizer, disk space pre-flight check — see ARCHITECTURE.md.
• Notifications: Optional Discord webhooks with per-event custom message templates (crash/ready/backup/player events).
• Theming: Light, dark, and system theme, fully applied across the UI.
• Linux Support (experimental): Native binary and Docker images (GUI or headless) — see Quick Start.
• Developer Experience: JDK auto-installer (bytecode analysis detects required version), event-driven architecture, thread safety, zero bare except: blocks.

---

Quick Start

Prerequisites

• Python 3.10+ (Download)
• Java: Not required manually. The app automatically detects, downloads, and caches the correct JDK (Adoptium, range 8-21) based on the selected Minecraft version.

Installation

1. Clone the repository

   git clone https://github.com/DesvoSoft/ZeroBlockBridge.git

2. Navigate to the project folder

   cd ZeroBlockBridge

3. Install dependencies

   Create a virtual environment (recommended):

   Windows:

   py -m venv venv
   .\venv\Scripts\activate

   Linux/macOS:

   python3 -m venv venv
   source venv/bin/activate

   Install dependencies:

   pip install -r requirements.txt

4. Run the application

   py app/launcher.py

   Depending on your OS, you might need python or python3 instead of py.

First Server

1. Click "Create Server" in the sidebar.
2. Follow the 6-step wizard (identity, engine/version, resources, rules/security, world/network, summary) — optionally tick "Start server after creation" on the summary step.
3. The wizard shows detailed progress (download, verify, scaffold, bytecode analysis, tunnel setup).
4. If you didn't check "start after creation", click "Start Now" when prompted to launch your server.
5. Optional: Click "⚡ Link" to enable Playit tunneling and play with friends online.

---

Project Structure

ZeroBlockBridge/
├── app/
│   ├── ui/              # Presentation layer (main window, wizard, editors, browser)
│   ├── core/             # Orchestration & business logic (ZBBManager, EventBus, logic)
│   └── services/         # Specialized services (watchdog, heartbeat, backups, API clients)
├── docs/                 # Documentation
├── assets/               # App icon and logo
├── servers/              # (Generated) per-server directories
├── backups/              # (Generated) ZIP archives
├── bin/                  # (Generated) playit agent binary
├── .zbb_cache/           # (Generated) JDK cache
└── config/               # (Generated) app configuration

---

Documentation

• ARCHITECTURE.md — Auto-healing system, technical details, architecture overview.
• STANDARDS.md — Master technical standards and architecture guide.
• ROADMAP.md — Development roadmap and phase tracking (local-only, untracked from repo).

---

Contributing

Contributions, issues, and pull requests are welcome!

---

License

ZeroBlockBridge © 2025-2026 by DesvoSoft.

Licensed under the GNU Affero General Public License v3.0 — free software, copyleft.

View Full License Text

---

Support

• Issues: Report bugs or request features via GitHub Issues.
• Discussions: Share setups and get help from the community.

---

Built by a player, for players, Minecraft creators & friends