lazymc: a proxy that puts an idle Minecraft server to sleep

The proxy that hides the wait

lazymc puts a Minecraft server to rest when it is idle and wakes it when players connect, and the reason it exists is resource use. Some servers, especially modded ones, use a lot of memory and CPU when nobody is playing, and lazymc's answer is to stop the server entirely until someone joins, then bring it back. The mechanism is a proxy. lazymc sits between the clients and the server, and it handles all incoming status connections until the server has been started, at which point it transparently relays and proxies the rest of the traffic without the clients noticing. That word, transparently, is the whole product. A naive implementation would show the player a connection error or a timeout while the server boots, and the design goal here is that the client never learns that anything unusual happened. The screenshots in the repository follow that arc exactly, with a sleeping server, a join, a starting server and a started server.

Four ways to treat the player who arrives early

The join methods are where the design gets interesting, because a sleeping server has to be woken while a client is already waiting, and there is no single right answer to what that client should see. Hold keeps the clients held while the server starts and relays them when it is ready, without them noticing, which is the least intrusive option. Kick disconnects the clients when the server starts and shows them a starting message, which at least tells the truth. Forward sends the client to a different IP when the server starts, which fits a setup where a second machine takes over. Lobby keeps the client in an emulated server with a lobby world and teleports them to the real server once it is ready, and this one is marked as experimental with its own document at docs/join-method-lobby.md. The choice is a trade-off between honesty and waiting, and the fact that the project ships four of them rather than picking one is the clearest statement of the problem it is solving.

It also manages the server it proxies to

The feature list goes well beyond the wake-up trick. The MOTD and the login messages are customisable, so the server description a player sees while it is starting is yours to write. lazymc automatically manages server.properties, specifically the host, port and RCON settings, which means the port the proxy listens on and the port the real server runs on are kept consistent without you editing the properties file by hand. Banned IPs are blocked from the server within lazymc, so the ban list is enforced at the proxy even while the server sleeps. Shutdown is graceful, through RCON or through SIGTERM, so the world gets a chance to save rather than being cut off. The real client IP reaches the Minecraft server through a PROXY header, documented separately at docs/proxy-ip.md, which matters because a server behind a proxy otherwise sees the proxy's address for every player. There is also restart on crash and a lockout mode, and the extras document points out how to fix incorrect client IPs and IP banning on the server side.

Installing it and running it for the first time

The requirements are modest but specific. Linux, macOS or Windows, a Minecraft Java Edition server, with the feature list stating support for Java Edition 1.20.3 and later, and RCON on Windows, which lazymc manages automatically. Building from source needs Rust 1.74 as the minimum supported version. There is also a constraint that decides the project for a lot of people: you must have access to the system to run the lazymc binary, so if you are on a Minecraft shared hosting provider with a custom dashboard you will probably not be able to set this up. For the day to day use, you download the binary for your system from the latest release page, except on macOS where the documentation says you must compile from source. You place the binary in the server directory, rename it if you like, and check that you can invoke it:

chmod a+x ./lazymc
./lazymc --help

Then you move into the server directory, generate a configuration, edit it, and start the proxy:

# Change into your server directory (if you haven't already)
cd server

# Generate lazymc configuration
lazymc config generate

# Edit configuration
# Set the correct server address, directory and start command
nano lazymc.toml

# Start lazymc
lazymc start

The generated file is lazymc.toml, and the three values you are expected to set are the server address, the directory and the start command. After that, connecting with your Minecraft client is what wakes the server.

Compiling from source, two ways

The source route needs Rust, installed through rustup, and then there are two ways to do it. The first installs straight from the git repository and forces a reinstall, which is the command to use when you are tracking the branch rather than a release:

# Compile and install lazymc from source
cargo install -f --git https://github.com/timvisee/lazymc

# Ensure lazymc works
lazymc --help

The second clones the repository and builds it yourself, which is what you want if you intend to read or change the code:

# Clone repository
git clone https://github.com/timvisee/lazymc
cd lazymc

# Compile
cargo build --release

# Run lazymc
./target/release/lazymc --help

The documentation notes that installation options are limited at the moment, that a binary may not exist for your system, and that more will be added later. Windows users are pointed to a separate usage document, docs/usage-windows.md, since the RCON requirement makes the setup there different. A third party Docker image is also listed, papermc-lazymc by crbanman, which packages PaperMC together with lazymc for people who would rather not run a bare binary.

Two Cargo features carry the optional behaviour

The manifest explains the design better than the prose does. The default feature list is rcon and lobby, and each maps to one of the behaviours described earlier. The rcon feature allows RCON to manage and stop the server, and it is marked as required on Windows, which is why the requirements section calls it out there. The lobby feature adds the lobby join method, the one that keeps a client in a fake lobby world until the server is ready, and it pulls in md-5 and uuid for the protocol work. The package itself is version 0.2.11, edition 2021, with a rust-version of 1.74.0, and the release profile is tuned for a small binary with codegen-units set to 1, lto enabled and strip on, which fits a project whose selling point is a few kilobytes of memory. The dependency list is the interesting part for a reader: minecraft-protocol comes from a git revision rather than a published crate, proxy-protocol handles the client IP header, nix provides the process and signal support used for graceful shutdown, notify watches the filesystem, and tokio, clap, serde and futures make up the rest of the runtime.

Where the project stands

The licence is GNU GPL-3.0, which is a sensible choice for a tool that most people deploy rather than modify, and the LICENSE file at the root carries the text. The release history is short and slow, with v0.2.9 and v0.2.10 both in February 2023 and v0.2.11 in March 2024, so the project is not on a monthly cadence. The last push to the master branch was on 2026-07-16 and the repository is not archived, which means development continues without a stream of tagged releases. One detail is easy to trip over: the build badge at the top of the README points at GitLab CI, and the repository and homepage fields in the Cargo manifest point at a gitlab.com address, while the installation instructions and the release links point at GitHub. The source of truth is the GitHub repository, and the GitLab one appears to be where the continuous integration lives. The tree carries a CHANGELOG.md and a TODO.md, a clippy.toml, a build.rs, an .env template file with a single RUST_LOG=info line, and a docs directory holding the extras, Windows usage, lobby and proxy IP guides.

Editorial conclusion

lazymc fits a self-hosted server, especially a modded one, whose memory or CPU cost when empty is larger than the value of keeping it up, and it suits an operator who would rather not script a cron job because the wake-up has to be invisible to the player. It is the wrong choice on shared hosting, since the documentation says you need system access to run the lazymc binary, and it is a poor fit if your players expect to be in the world within a second, because the server has to start first. Before you deploy it, read the join method documentation and pick the behaviour your players will tolerate, check the Rust 1.74 minimum for a source build, and confirm that the RCON feature is what you want for stopping the server, since that is the part that is required on Windows.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. timvisee/lazymc on GitHub