Nimbus — Minecraft Cloud System

How to install Nimbus using the one-command installer, build from source, or set up auto-updates.

One-Command Install (Recommended)

The fastest way to get Nimbus running. The installer handles everything — Java 21, the latest release, start scripts, and an optional system service.

Terminal

curl -fsSL https://raw.githubusercontent.com/NimbusPowered/Nimbus/main/install.sh | bash

PowerShell

irm https://raw.githubusercontent.com/NimbusPowered/Nimbus/main/install.ps1 | iex

The installer will:

Check for Java 21 — installs Eclipse Temurin automatically if missing
Download the latest Nimbus release from GitHub
Create a start script (nimbus command on Linux, nimbus.bat on Windows)
Optionally create a system service (systemd on Linux, Windows Service)

After installation, run nimbus to start the setup wizard.

Already have Java 21?

The installer detects it and skips the Java step. Run java -version to check.

Auto-Updates

Nimbus checks for updates automatically on every startup by querying GitHub Releases.

Update type	Behavior
Patch / Minor (e.g. `0.1.0` → `0.1.3` or `0.2.0`)	Downloads and applies automatically. A backup of the previous JAR is kept.
Major (e.g. `0.x` → `1.0.0`)	Shows changelog and prompts `Upgrade now? [y/N]` — you decide.

Nimbus

ℹ Update available: v0.1.0 -> v0.2.0 (minor)
  Downloading v0.2.0... done
✓ Updated to v0.2.0 (backup: nimbus-backup.jar)
  Restart Nimbus to apply the update.

Integrity verification

Downloaded JARs are verified against the expected file size from the GitHub API. The SHA-256 hash is computed and logged for manual verification. If the file size does not match, the update is rejected.

Dev builds

When running from source (version = dev), the auto-updater is skipped.

Prerequisites

If you prefer to install manually, make sure you have:

Java 21 or later (required)
Git (for cloning the repository)
2 GB RAM minimum for the controller plus a few server instances

Checking your Java version

Run java -version in your terminal. You should see version 21 or higher:

Terminal

java -version
openjdk version "21.0.2" 2024-01-16

If you don't have Java 21, download it from Adoptium or use your system package manager.

Java version matters

Nimbus requires Java 21. It will not run on older versions. The Minecraft servers it manages may also need Java 21 (Paper 1.20.5+, Purpur 1.20.5+, Leaf 1.21.4+).

Building from Source

Clone the repository and build the fat JAR:

Terminal

git clone https://github.com/NimbusPowered/Nimbus.git
cd Nimbus
./gradlew shadowJar
> Task :nimbus-bridge:shadowJar
> Task :nimbus-core:processResources
> Task :nimbus-core:shadowJar
BUILD SUCCESSFUL in 12s

The output JAR will be at:

Output Path

nimbus-core/build/libs/nimbus-core-<version>-all.jar

Quick compile check

To verify the code compiles without building the full JAR:

Terminal

./gradlew :nimbus-core:compileKotlin
BUILD SUCCESSFUL in 4s

Running Nimbus

Copy the JAR to your desired directory and run it:

Terminal

mkdir my-network
cp nimbus-core/build/libs/nimbus-core-<version>-all.jar my-network/
cd my-network
java -jar nimbus-core-<version>-all.jar

On first launch, the Setup Wizard starts automatically and walks you through initial configuration.

JLine native access

On Java 21+, Nimbus automatically relaunches itself with the --enable-native-access=ALL-UNNAMED flag to suppress JLine terminal warnings. This is handled transparently — you don't need to add any JVM flags yourself.

Directory Structure

After the setup wizard completes, your directory will look like this:

Directory Structure

my-network/
├── nimbus-core-<version>-all.jar    # The Nimbus application
├── config/                       # All configuration files
│   ├── nimbus.toml               #   Main configuration
│   ├── groups/                   #   Server group definitions
│   │   ├── proxy.toml            #     Velocity proxy group
│   │   ├── lobby.toml            #     Lobby server group
│   │   └── bedwars.toml          #     (example game mode)
│   └── modules/                  #   Module-specific configs
│       ├── display/              #     Sign/NPC display configs
│       └── syncproxy/            #     Proxy sync (MOTD, tab list, chat, maintenance)
├── templates/                    # File templates for services
│   ├── global/                   #   Shared across all backends
│   │   └── plugins/              #     nimbus-sdk.jar (auto-deployed)
│   ├── global_proxy/             #   Shared across all proxies
│   │   └── plugins/              #     nimbus-bridge.jar (auto-deployed)
│   ├── proxy/                    #   Velocity template files
│   ├── lobby/                    #   Lobby template files
│   └── bedwars/                  #   Game mode template files
├── services/                     # Running service instances
│   ├── static/                   #   Persistent services (proxy)
│   └── temp/                     #   Ephemeral services (lobbies, games)
├── permissions/                  # Permission data files
├── plugins/                      # Optional plugins (SDK, Signs)
└── logs/                         # Log files
    └── latest.log                #   Current session log

Key Directories

Directory	Purpose
`config/nimbus.toml`	Main configuration file for Nimbus.
`config/groups/`	One TOML file per server group. This is where you define your server types.
`templates/`	Template files that get copied to each service instance on startup.
`templates/global/`	Files shared across all backend servers (Paper, Purpur, Leaf, etc.).
`templates/global_proxy/`	Files shared across all proxy servers (Velocity).
`services/static/`	Persistent service instances that survive restarts (e.g., proxy).
`services/temp/`	Ephemeral instances created and destroyed by the scaling engine.
`permissions/`	Built-in permission system data.
`plugins/`	Optional Nimbus plugins available for manual installation.

Daemon Mode

Nimbus auto-detects whether it is running attached to a terminal by checking System.console() == null. When no console is available (e.g., started via systemd or a shell redirect), it enters headless mode:

The JLine3 interactive REPL is not started — no terminal is required.
The JVM stays alive serving the REST API and WebSocket event stream.
SIGTERM triggers a clean, ordered shutdown (same sequence as the shutdown confirm command).
All log output goes to logs/latest.log and stdout for journal capture.

A minimal systemd unit:

/etc/systemd/system/nimbus.service

[Unit]
Description=Nimbus Minecraft Cloud Controller
After=network.target

[Service]
Type=simple
User=nimbus
WorkingDirectory=/opt/nimbus
ExecStart=java -jar /opt/nimbus/nimbus-core.jar
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable and start with:

Terminal

sudo systemctl daemon-reload
sudo systemctl enable --now nimbus

You can still issue commands remotely when running in daemon mode using the Remote CLI (nimbus-cli).

Remote CLI Installation

The Remote CLI (nimbus-cli) is a standalone tool for managing Nimbus from any machine. It connects to the controller's REST API and provides the same commands, tab completion, and formatting as the local console.

Terminal

curl -fsSL https://raw.githubusercontent.com/NimbusPowered/Nimbus/main/install-cli.sh | bash

PowerShell

irm https://raw.githubusercontent.com/NimbusPowered/Nimbus/main/install-cli.ps1 | iex

Or download nimbus-cli-<version>.jar from GitHub Releases and run it directly:

Terminal

java -jar nimbus-cli-<version>.jar

On first launch without arguments, the CLI starts an interactive setup wizard:

Nimbus CLI

Nimbus Remote CLI — Connection Setup
No connection configured. Enter your controller details.

Host [127.0.0.1]: 192.168.1.10
Port [8080]: 8080
API Token: your-api-token-here

Save as profile? (name or empty to skip): prod
Saved as 'prod' (set as default).

After saving a profile, subsequent launches connect automatically. You can also pass credentials directly:

Terminal

nimbus-cli --host 192.168.1.10 --port 8080 --token your-api-token

API must be enabled

The controller's REST API must be running and accessible from the CLI machine. Configure [api] bind = "0.0.0.0" in nimbus.toml if you need remote access (default is 127.0.0.1).

See the Remote CLI guide for full usage documentation.

What's Next?

Follow the Quick Start guide to walk through your first network setup, or read about Core Concepts to understand how Nimbus works.

Installation

On this page