universe docs source
README.md 42 lines

single-binary minecraft orchestrator

# One JAR.
# The whole cluster.

Master and wrapper live in the same fat JAR. Form a Hazelcast cluster, expose one REST + WebSocket API, and deploy instances across screen, tmux, docker and kubernetes. Same config, swap one field.

java 21+ apache-2.0 v0.0.1
❯ get started git clone universe
loader.log · na-game-1
❯ docker compose up -d && docker compose attach universe
→ Starting Universe in MASTER mode
→ Hazelcast advertising 100.64.0.8:6000
→ Registered built-in runtimes (tmux, screen, process)
→ Installing extensions...
✓ S3 template storage loaded (bucket=templates)
✓ Docker runtime loaded (image=azul-zulu:21-jdk)
✓ Kubernetes runtime loaded (namespace=universe)
✓ Tailscale loaded (ip=100.64.0.8)
✓ Ktor REST API started on 0.0.0.0:7000
✓ Auto-spawned instance 564574 · config 'game-server-na'
stack.txt 21 lines 
# one jar, no external services to run

  runtime      jvm · single fat jar  # one process runs master + wrappers
  clustering   hazelcast             # peer-to-peer · unlimited nodes
  api          rest + websocket      # :7000 · bearer auth, rate limited
  templates    versioned file-trees  # %variable% replacement

# runtimes · same config, any target

  built-in     screen · tmux
  extensions   docker · kubernetes   # 5+ targets, laptop to fleet

# integrations · 14 official drop-in extensions

  storage      aws s3
  databases    postgresql · redis · mongodb
  metrics      prometheus
  networking   tailscale
  gitops       argocd
  proxies      velocity · paper
  chat-ops     discord
features.yaml 18 lines
features: # click a key to unfold (za)

  • # One master exposes the REST API; any number of wrapper nodes execute instances. Work is dispatched cluster-wide over Hazelcast, no extra message broker to run.

  • # Instances are built from versioned template file-trees with dynamic %VARIABLE% replacement. Compose templates per group, choose one-of, or install whole groups.

  • # Built-in screen and tmux. Docker and Kubernetes via extensions. The same configuration deploys to a laptop, a VM fleet, or a cluster without changes.

  • # Full lifecycle control over HTTP. Stream live logs and an interactive console over WebSockets. Bearer-token auth with ALL / PUBLIC permission scopes and rate limiting.

  • # Self-registering JARs add runtimes, storage backends, databases, metrics exporters, and integrations. Drop one in ./extensions and it wires itself up on load.

  • # Sync templates and configs straight from Git, and export Kubernetes manifests for ArgoCD to track. Your fleet topology lives in version control.

  • # The Tailscale extension exposes mesh IPs as template variables, so instances on different networks connect securely without manual port plumbing.

  • # Prometheus exposition endpoint out of the box, plus an InfluxDB exporter. Daily-rotated structured logs and a styled operational console.

  • # First-class plugins for Paper, Spigot, Velocity, BungeeCord and Folia. Proxies auto-register backends and route players with pluggable strategies.

templates/ 7 lines

Templates are versioned file trees per group/name. Built-in and custom %VARIABLES% are substituted when an instance deploys. Edit the values and watch the render.

templates/lobby/server.properties 
# server.properties
server-port=%SERVER_PORT%
motd=%INSTANCE_NAME% - powered by Universe
 
# start.flags
--instance-id %INSTANCE_ID%
--max-memory %MAX_MEMORY%

# variables

→
a1b2c3 · rendered DEPLOYED 
 
 
 
 
  
 
 
 
 
  cluster.txt  22 lines 
  
 

# one master exposes the api & holds state · N wrappers execute instances

 
 
 
  node-1 MASTER 
 
 api :7000 · hz :6000 
 
  
 
 
  node-1 wrapper 
 
 
a1b2c3
 
 lobby  ONLINE  
 
:25565
 
 
  node-2 wrapper 
 
 
d4e5f6
 
 survival  ONLINE  
 
:25566
 
 
  node-3 wrapper 
 
 
g7h8i9
 
 build  STARTING  
 
:25567
 
 
 
 
  
 
 
 
 
  preview/  10 lines 
  
    
 
 
 
 universe@na-game-1 ›    instance list  
    564574  game-server-na    ONLINE   :25100  docker  
    27c625  game-lobby-na     ONLINE   :25000  docker  
    2bb48e  proxy-na          ONLINE   :40188  docker  
 universe@na-game-1 ›    cluster status  
    universe-cluster · members: 1 · master: na-game-1  
 universe@na-game-1 ›    instance execute 27c625 'say Universe online'  
  ✓   dispatched → 27c625  
  
 
    
 
 
 
 
  editions.toml  30 lines 
  
 
 
  
[open-source]
 free · self-host · apache-2.0 
 
 
[open-source]
 
 orchestrator  =  "full: master, wrappers, clustering" 
 node_caps  =  false 
 self_host  =  true 
 runtimes  =  "screen, tmux, docker, kubernetes" 
 api  =  "REST + WebSocket, console, templates" 
 extensions  =  "community ecosystem" 
 
 
 
  
[licensed]
 hardened · sla · from LunarLabs 
 
 
[licensed]
 
 includes  =  "everything in open-source" 
 entitlements  =  "key-gated + licensed extensions" 
 release_channel  =  "hardened" 
 sla  =  true 
 deployment_help  =  "hands-on, from LunarLabs" 
 
 
 
 
 
 # feature comparison 
 
 
  
 capability open-source licensed 
   
 master / wrapper clustering  ✓  ✓  
 template-based deployment  ✓  ✓  
 built-in runtimes (screen, tmux)  ✓  ✓  
 docker & kubernetes runtimes  ✓  ✓  
 REST + WebSocket API  ✓  ✓  
 official extensions (s3, metrics, dbs)  ✓  ✓  
 minecraft plugins (paper, velocity)  ✓  ✓  
 self-host, unlimited nodes  ✓  ✓  
 community support  ✓  priority  
 web management panel  self-host  hosted + sso  
 license-key entitlements  -  ✓  
 hardened release channel & slas  -  ✓  
 onboarding & deployment support  -  ✓  
  
 
 
  
 
 
 
 
get started
 

one command. spin up the whole cluster.

 

One line installs Docker, writes a compose.yml, and
			starts the cluster. Prefer standalone? The JAR runs on its own, it just wants more flags.

 
 
 ~/universe  
 
 
 ❯ curl -fsSL https://get.lunarlabs.dev/universe | sh 
 
# installs docker · writes compose.yml · brings the cluster up
 
 
 
  ❯ browse features
 view the source