AutoStopper

Stop paying for empty Minecraft servers

AutoStopper puts idle Docker-based backends to sleep and wakes them the moment a player connects
through Velocity. Players keep using your network normally. You stop running servers nobody is
playing on.

Install it on Velocity, list the containers you want managed, and let quiet servers sleep.

Why you will like it

• It wakes servers for you. A player picks a sleeping server through normal Velocity routing.
  AutoStopper starts the container and connects them as soon as it is ready. No client mod, no
  replacement /server command.
• It waits for Minecraft, not just Docker. A running container is not a ready server.
  AutoStopper waits for a real Minecraft status reply, Docker health, or either one, with a bounded
  deadline on every probe and command.
• It handles the rush back in. If ten players arrive at once they share one start and are
  connected together when the server answers.
• It only touches what you map. Hubs, lobbies and anything not listed in monitored_servers are
  never started, stopped or intercepted.
• It fails clearly. Failed stops retry with capped backoff and never pretend the server stopped.
  An invalid reload keeps the previous configuration running. Players see short, friendly
  messages; raw Docker output stays in your logs.

What your players see

Quick start

You need a Linux host with Docker Engine and Docker Compose v2. This sets up Velocity 4.2 on
Java 25 with one Minecraft server that AutoStopper puts to sleep and wakes. There is nothing to
download by hand: the proxy installs AutoStopper from Modrinth.

1. Save this as docker-compose.yml in an empty directory:

services:
  # Lets Velocity inspect, start and stop containers, and nothing else.
  # It is the only service that touches the Docker socket.
  autostopper-docker:
    image: wollomatic/socket-proxy:1.13.1@sha256:3935b709275e4ec35d6ed5a5c4a1f0d01ed31eec5e7234efc3357ecd47689002
    restart: unless-stopped
    user: "0:0"
    read_only: true
    cap_drop:
      - ALL
    command:
      - -listenip=0.0.0.0
      - -allowfrom=velocity
      - -allowGET=^(/v[0-9.]+)?/(_ping|containers/[a-zA-Z0-9_.-]+/json)$
      - -allowPOST=^(/v[0-9.]+)?/containers/[a-zA-Z0-9_.-]+/(start|stop)$
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - autostopper-internal

  velocity:
    image: itzg/mc-proxy:2026.8.0-java25
    environment:
      TYPE: "VELOCITY"
      VELOCITY_VERSION: "4.2.0"
      VELOCITY_BUILD_ID: "30"
      # Installs the latest AutoStopper release at startup. Write
      # autostopper:<version> to pin one. MINECRAFT_VERSION only selects the
      # download (any version from 1.7.2 to 26.2 works).
      MODRINTH_PROJECTS: "autostopper"
      MINECRAFT_VERSION: "1.21.4"
    ports:
      - "25565:25577"
    volumes:
      - ./velocity_server:/server
    networks:
      - minecraft
      - autostopper-internal
    depends_on:
      - autostopper-docker
    restart: unless-stopped

  # A server AutoStopper manages. Add more the same way.
  survival:
    image: itzg/minecraft-server:java21
    container_name: survival-server
    environment:
      EULA: "TRUE"
      TYPE: "PURPUR"
      VERSION: "1.21.4"
      ONLINE_MODE: "FALSE"
    volumes:
      - ./survival_data:/data
    networks:
      - minecraft
    restart: "no"          # AutoStopper starts and stops it; Docker must not restart it
    stop_grace_period: 60s # time to save the world when it is stopped

networks:
  minecraft:
  autostopper-internal:
    internal: true

2. Start it with docker compose up -d. The first start downloads everything and generates
the configuration.

3. Tell Velocity about the server. In velocity_server/velocity.toml, replace the sample
servers and the sample forced hosts, which refer to them:

[servers]
survival = "survival:25565"
try = ["survival"]

[forced-hosts]

In the existing [advanced] section of the same file, set read-timeout = 180000 so a sleeping
server has time to wake before Velocity gives up on the player (the default is 30 seconds).

4. Tell AutoStopper which container to manage. In
velocity_server/plugins/autostopper/config.yml, replace monitored_servers: [] with:

monitored_servers:
  - server_name: survival            # the name in velocity.toml
    container_name: survival-server  # the container_name in docker-compose.yml

5. Restart and check. Run docker compose restart velocity. The proxy log should show
endpoint auto: tcp://autostopper-docker:2375 (socket-proxy sidecar) and
AutoStopper startup preflight healthy: 1 mapping(s) checked.

That's it. After 5 minutes without players the server sleeps, and the next player who joins wakes
it. /autostopper status shows every server's state. Always-on hubs stay out of
monitored_servers. Ready-made files for the other Velocity lines are in the
examples, and the
configuration reference covers tuning.

Docker security warning. Access to /var/run/docker.sock is effectively root on the Docker
host. The examples keep it out of Velocity: a small socket proxy holds the socket and lets
Velocity only inspect, start and stop containers. Velocity can still stop or start any container
and read container environment variables unless you pin the proxy to your backends. Prefer a
dedicated host or VM, install only trusted plugins, and read the
security guidance first.

Sensible defaults

Every value is configurable and validated as one atomic snapshot. See the
configuration reference.

Commands

autostopper.admin grants all of them. AutoStopper never replaces Velocity's /server command.

Tested support

One Java 21 JAR is tested on five complete runtime lines. Keep the proxy image and Velocity build
from one row together.

Velocity 4 needs Java 25. The preview line tracks a PaperMC snapshot and is not a production
baseline. The full release candidate runs against a real Purpur 1.21.4 backend with actual protocol
clients, simultaneous joins, idle stop, restart, never-ready servers and failed-stop retry. Minecraft
versions 1.7.2 through 26.2 are listed because AutoStopper uses only Velocity events and a generic
status request, but only that backend is exercised directly.

Help and docs

• Troubleshooting covers every failure outcome you can see in chat or logs
• Configuration reference
• Security guidance
• Migrating from 2.2.0 to 2.3.0 (drop-in; optional move to the
  socket proxy)
• Migrating from 1.1.2 to 2.0.0
• Full installation guide
• Changelog
• Report an issue

Ready to let empty servers sleep? Pick an example, review the Docker security boundary, and
install the same validated JAR that is published on GitHub Releases.