WHAT IS THIS

This is a lightweight Minecraft limbo server. It can be used as a fallback server on your proxy network (Velocity / BungeeCord / Waterfall), or as an authorization holding server on offline-mode projects.

The main goal of the project is maximum simplicity with a minimum number of sent and handled packets.

This limbo is empty — there is no ability to load schematic buildings, since this is not necessary. You can send useful information in chat, boss bar, title, or player list header/footer. The server is only meant to keep many players connected while your main server is down or during authentication.

Important!
The server cannot run Bukkit/Spigot/Paper plugins — it is not a fork of any of them. Please do not ask for Spigot-plugin support. If you need a feature while the player is in limbo, implement it on your proxy side (BungeeCord / Velocity).

FEATURES

• High performance. The server does not save or cache any useless (for a limbo) data.
• Does not spawn a thread per player. Uses a fixed thread pool.
• Native Netty transports out of the box — epoll and io_uring on Linux (x86_64 / aarch64), kqueue on macOS (x86_64 / aarch64), with automatic NIO fallback if the native transport is unavailable.
• Wide protocol coverage — from 1.7.2 all the way to the latest 1.21.11 and 26.1 clients (see the version list below).
• BungeeCord and Velocity info forwarding, plus BungeeGuard handshake format.
• External secret files — Velocity-MODERN secret and BungeeGuard tokens can be loaded from a file using the @-prefix (e.g. secret: '@secret.txt'). Great for Docker secrets, Kubernetes secrets, or SOPS-managed credentials.
• MiniMessage text format supported in every text field (chat, title, subtitle, boss bar, player-list header/footer, MOTD). Legacy &-codes and raw JSON are still accepted for backwards compatibility.
• Per-connection packet rate limiting — optional traffic block in the config throttles clients that try to flood packets or bytes.
• Privacy-friendly logging — the logPlayersIp config flag hides player IP addresses from connect logs (GDPR-friendly).
• Fully configurable and lightweight (~5 MB jar, natives bundled).

VERSIONS SUPPORT

Symbol X means all minor versions.

• 1.7.X
• 1.8.X
• 1.9.X
• 1.10.X
• 1.11.X
• 1.12.X
• 1.13.X
• 1.14.X
• 1.15.X
• 1.16.X
• 1.17.X
• 1.18.X
• 1.19.X
• 1.20.X
• 1.21.X (incl. 1.21.2, 1.21.3, 1.21.4, 1.21.5, 1.21.6, 1.21.7, 1.21.8, 1.21.9, 1.21.10, 1.21.11)
• 26.1.X

The server does not support snapshots.

COMMANDS

These commands are available in the server console:

help - Show the help message
conn - Display the number of connections
mem - Display memory usage stats
version (or ver) - Display the limbo version
stop - Stop the server

The server also shuts down correctly on Ctrl+C.

INSTALLATION

Requires Java 17 or higher.

The installation process is simple.

1. Download the latest version from: https://github.com/Nan1t/NanoLimbo/releases
2. Place the jar file in the folder of your choice.
3. Create a start script, similar to what you would do for Spigot/BungeeCord:
   Code (Bash):

   java -jar NanoLimbo.jar
4. The first run will create a settings.yml file. Configure it as you wish and restart the server.

UPGRADING FROM 1.8.x

Since 1.12.0 (the 1.21.2+ protocol rewrite) a few breaking changes apply to existing configs:

• Java 17+ is required (was Java 11).
• dimension: NETHER was renamed to dimension: THE_NETHER.
• useEpoll: true was replaced by netty.transportType: EPOLL (other values: NIO, IO_URING, KQUEUE).
• New top-level keys: secureProfile, logPlayersIp, and the traffic block. Default values are safe; no manual edit is required if you don't care.
• The built jar is now simply NanoLimbo.jar (no version suffix).
• Text fields accept MiniMessage by default, but your existing legacy &-codes and raw-JSON values keep working unchanged.

PLAYER INFO FORWARDING

The server supports three forwarding types:

• LEGACY - BungeeCord IP forwarding.
• MODERN - Velocity native info forwarding. Paste the secret from Velocity's config into the secret field, or use secret: '@secret.txt' to load it from a file.
• BUNGEE_GUARD - BungeeGuard handshake format. List tokens inline, or point at an external file with tokens: '@tokens.txt' (one token per line).

CREDITS

NanoLimbo 1.12.0 is the result of community work across several forks. Thanks to:

• Nan1t - original author and maintainer of NanoLimbo.
• BoomEaro (Valentine) - the 1.21.2 through 1.21.11 / 26.1 protocol rewrite, MiniMessage stack, native-transport support, build modernization, and GitHub Actions CI. The bulk of this release.
• YueMi-Development - external secret/token file support via the @-prefix.
• Biquaternions - the logPlayersIp privacy flag.

Full credits and per-feature links are in the project README.

LINKS

• Source code and releases: https://github.com/Nan1t/NanoLimbo
• Report bugs or request features: https://github.com/Nan1t/NanoLimbo/issues
• Discord: https://discord.gg/4VGP3Gv