Migrating from SimpleCloud

This guide covers moving a SimpleCloud v2 install to Nimbus. SimpleCloud and Nimbus have a lot of common DNA — both are console-first, both handle Velocity/proxy + backends, both scale dynamic groups by player count. Most config translates mechanically.

Concept map

Things SimpleCloud has that Nimbus doesn't

• Multi-master HA. Nimbus has exactly one controller.
• Per-process dynamic memory (on top of template). Nimbus sets memory per-group, not per-instance.
• Community plugin ecosystem (notify, chat modules, etc.). Nimbus ships a fixed module set. For bespoke features write a Nimbus module (see Developer: Modules) or an SDK plugin.
• Lobby-plugin fine-grained hub commands. Nimbus's bridge provides /hub + server selector. More elaborate lobby UX is a user-side plugin problem.

Config translation

Cloud group → Group

SimpleCloud group config (storage/groups/Lobby.json, simplified):

{
  "name": "Lobby",
  "templateName": "Lobby",
  "minimumOnlineServiceCount": 2,
  "maximumOnlineServiceCount": 4,
  "maxMemory": 1024,
  "maxPlayers": 50,
  "startPort": 30000,
  "serverVersionName": "PAPER_1_20_4",
  "static": false,
  "maintenance": false
}

Equivalent Nimbus group (config/groups/Lobby.toml):

[group]
name = "Lobby"
software = "paper"
mc_version = "1.20.4"
templates = ["Lobby"]

[group.resources]
memory = "1G"
max_players = 50

[group.scaling]
min_instances = 2
max_instances = 4

Start ports are controller-global in Nimbus (backends: 30000+, proxies: 25565+) — you don't set them per-group.

Proxy group

SimpleCloud treats proxy groups as a separate JSON schema. In Nimbus it's the same schema — only software = "velocity" changes:

[group]
name = "Proxy"
software = "velocity"
templates = ["Proxy"]

[group.resources]
memory = "512M"
max_players = 500

[group.scaling]
min_instances = 1
max_instances = 2

Nimbus generates velocity.toml and the servers {} list automatically. Don't hand-maintain it.

Static group → dedicated service OR sync group

SimpleCloud's "static": true combines two Nimbus concepts. Pick based on intent:

You want a single, named server that never moves (e.g. the Survival world):

name = "Survival"
software = "paper"
mc_version = "1.20.4"
port = 30100
proxy_enabled = true

[dedicated.resources]
memory = "4G"

You want a small pool of persistent services (e.g. Hub-1, Hub-2) whose worlds survive restarts but can fail over across agents:

[group]
name = "Hub"
software = "paper"

[group.sync]
enabled = true

[group.scaling]
min_instances = 2
max_instances = 2

Wrapper → agent

Each SimpleCloud wrapper becomes a Nimbus agent. Install:

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

The setup wizard handles the cluster token + TLS fingerprint pin (no manual wrapper.toml tokens). See Multi-Node Guide.

Permissions

SimpleCloud's permission module exports to flat JSON. The Nimbus Perms module stores in the controller DB and has a simple console interface:

perms group create admin
perms group permission add admin nimbus.cloud.*
perms user group add <uuid> admin

If you're on LuckPerms with SimpleCloud, configure the Perms module to use LuckPerms as its backend — zero migration.

Signs / NPCs

SimpleCloud-signs data doesn't migrate automatically. Install the display module, configure config/modules/display/<Group>.toml, and re-place signs in-game. NPCs (Paper 1.20+) are new to most SimpleCloud setups.

Migration recipe

1. Inventory

List every:

• Cloud group (name, template, min/max, memory, MC version).
• Static group + its working directory location.
• Wrapper + which groups run on it.
• Permission groups (if using SimpleCloud-permissions).
• External integrations hitting the SimpleCloud REST module.

2. Install Nimbus

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

First-run SetupWizard picks modules. Select perms, display, scaling to match a typical SimpleCloud feature set. Consider punishments, resourcepacks, backup — these are Nimbus additions without SimpleCloud equivalents.

3. Templates

Copy storage/templates/<Name>/ → templates/<Name>/. Delete SimpleCloud's own agent/wrapper plugins from the copied templates (simplecloud-*.jar, CloudAPI-*.jar) — Nimbus auto-deploys its SDK, bridge, perms, display, punishments, and resourcepacks plugins at runtime, so templates must remain clean of cloud plugins.

4. Author config/groups/*.toml

Translate each group JSON into TOML using the table above. Keep names identical so players don't notice.

5. Static groups → dedicated services or sync groups

Decide per-group which primitive fits (see concept map). Copy working directories:

• Dedicated: storage/static/<Name>/ → <paths.dedicated>/<Name>/
• Sync group (single instance): seed services/state/<Name>/ with the SimpleCloud working dir before first start.

6. Cluster

For each SimpleCloud wrapper, install nimbus-agent on the same host. Use cluster bootstrap-url on the controller, paste into each agent's setup wizard. Pin pre-existing wrapper affinities via [group.placement] node = "<agent>".

7. Permissions

• LuckPerms users: just configure the Perms module's LuckPerms backend — done.
• SimpleCloud-permissions users: export to JSON, reimport via perms console commands or scripting against the Permissions API.

8. Proxy + bridge

Delete SimpleCloud's CloudBridge-*.jar from the Velocity template. Nimbus auto-deploys nimbus-bridge.jar at every proxy start. It handles:

• Server list sync (no more manual servers {} maintenance)
• /hub command + forced-host rules
• Chat, tab, MOTD sync
• Punishment enforcement on PreLoginEvent (if you enabled the punishments module)
• Modded client routing (Forge/NeoForge detection + group filtering)

9. Smoke test

• start Proxy, start Lobby — verify processes, ports, and that the proxy registers backends.
• Join the network, check the lobby signs repaint (after re-placing), check permissions.
• Trigger scaling: stress start 100 Lobby --ramp 30.
• Hit GET /api/status with your API token; verify the dashboard can connect.

10. Cut over + grace period

Point your public DNS at the Nimbus proxy. Keep SimpleCloud's installed-but-stopped for a week as rollback safety. Revoke SimpleCloud REST tokens once you're confident.

Common pitfalls

Next steps

• Server Groups
• Dedicated Services
• Multi-Node + Cluster Topologies
• Scaling — Smart Scaling (time-based + predictive warmup)