Introduction

Nimbus is a lightweight, console-only Minecraft cloud system that manages dynamic server instances from a single JAR. It handles everything from downloading server software to auto-scaling game servers based on player count — no web UI, no bloat.

   _  __ __ _   __ ___  _ __  ___
  / |/ // // \,' // o.)/// /,' _/
 / || // // \,' // o \/ U /_\ \`. 
/_/|_//_//_/ /_//___,'\_,'/___,'
            C L O U D

[12:00:01] ▲ STARTING  Proxy-1 (group=Proxy, port=25565)
[12:00:04] ● READY     Proxy-1 (group=Proxy)
[12:00:04] ▲ STARTING  Lobby-1 (group=Lobby, port=30000)
[12:00:08] ● READY     Lobby-1 (group=Lobby)
[12:00:08] ▲ STARTING  BedWars-1 (group=BedWars, port=30001)
[12:00:12] ● READY     BedWars-1 (group=BedWars)
nimbus » list
── Services ──────────────────────────────────────
NAME            GROUP       STATE           PORT    PLAYERS  PID     UPTIME
──────────────────────────────────────────────────────────────────────────────
Proxy-1         Proxy       ● READY          25565   12       12451   2h 15m
Lobby-1         Lobby       ● READY          30000   4        12488   2h 14m
BedWars-1       BedWars     ● READY          30001   8        12523   1h 32m
BedWars-2       BedWars     ● STARTING       30002   0        12567   0m 05s
4 service(s)

Why Nimbus?

Setting up a Minecraft network traditionally means manually configuring each server, writing startup scripts, managing proxy configs, and handling scaling yourself. Heavier cloud systems like CloudNet solve this but come with complexity and overhead.

Nimbus takes a different approach:

Key Features

• Multi-Node Cluster — Distribute services across multiple machines. Agent nodes connect via WebSocket with automatic placement, failover, and template distribution. Built-in TCP load balancer for proxy redundancy.
• Single JAR — One file runs your entire cloud. No external services needed. Scale to multi-node when you're ready.
• Auto-scaling — Dynamically starts and stops server instances based on player count and configurable thresholds — across one or many machines.
• Software auto-download — Automatically fetches Paper, Pufferfish, Purpur, Leaf, Folia, Velocity, Forge, Fabric, and NeoForge server JARs.
• Performance optimization — Automatically applies Aikar's JVM flags and optimized server configs out of the box. Tuned for both standard and large heaps (12G+).
• Bedrock Edition support — Optional Geyser + Floodgate integration lets Bedrock players (mobile, console, Windows) join your Java network. Plugins are auto-downloaded and configured.
• Full modded server support — Forge, Fabric, NeoForge, and Quilt (via Fabric) all work out of the box. Proxy forwarding mods are auto-installed so players connect through Velocity seamlessly.
• Cardboard for Fabric — Optionally install Cardboard (BETA) on Fabric servers to run Bukkit/Paper plugins alongside mods. Auto-downloaded with its iCommon dependency.
• Automatic JDK management — Nimbus detects installed Java versions and downloads missing ones from Adoptium automatically. No manual JDK setup needed.
• Velocity auto-patching — Checks for new Velocity versions every 6 hours and stages updates automatically. No downtime.
• Adaptive forwarding — Automatically selects modern or legacy forwarding based on your server versions. Configures every backend (Paper, Fabric, Forge, NeoForge) with zero manual work.
• REST API + WebSocket — Full API for integration with external tools, bots, and panels.
• Velocity proxy auto-management — Proxy server list is automatically kept in sync as services start and stop.
• Built-in permissions — Permission system included out of the box.
• Interactive console — JLine3-powered REPL with tab completion, command history, and live event streaming.
• Remote CLI — Standalone binary (nimbus-cli) that connects to the controller API for remote management with the same commands and formatting. Session tracking with GeoIP location.
• Web Dashboard (BETA) — Browser-based management UI at dashboard.nimbuspowered.org. Service overview, real-time console, plugin management, stress testing, and more — all from your browser.
• Template system — Global and per-group templates for consistent server configuration.
• Via plugin support — ViaVersion, ViaBackwards, and ViaRewind managed automatically on backend servers. Dependencies are enforced (ViaBackwards auto-includes ViaVersion).

Architecture

┌─────────────────────────────────────┐
│       Nimbus Controller              │
│  ┌─────────┐ ┌──────┐ ┌──────────┐ │
│  │ Console  │ │  API  │ │ Scaling  │ │
│  │ (JLine)  │ │(Ktor)│ │ Engine   │ │
│  └─────────┘ └──────┘ └──────────┘ │
├─────────────────────────────────────┤
│          Server Groups              │
│  ┌─────────┐ ┌───────┐ ┌────────┐ │
│  │ Proxy-1 │ │Lobby-1│ │BedWars │ │
│  │(Velocity)│ │(Paper) │ │ 1..N   │ │
│  └─────────┘ └───────┘ └────────┘ │
└─────────────────────────────────────┘

The Nimbus Controller is the main process. It runs three core systems:

• Console — Interactive command line powered by JLine3. Manage everything from here.
• API — Ktor-based REST API and WebSocket server for external integrations.
• Scaling Engine — Periodically evaluates player counts and starts/stops instances automatically.

Below the controller sit your Server Groups — definitions for each type of server (proxy, lobby, game modes). Nimbus creates running Services from these groups as needed.

Modules

Nimbus is built from several modules:

What's Next?

Ready to get started? Head to the Installation guide to set up Nimbus, or jump straight to the Quick Start for a step-by-step walkthrough.

Want a visual interface? Try the Web Dashboard (BETA) at dashboard.nimbuspowered.org.

Running multiple machines? Check out the Multi-Node & Load Balancer guide to distribute your network across a cluster.