Get started with Universe in under five minutes

Universe ships as a single fat JAR produced by the loader module. On first launch it writes a config.json with sane defaults, creates the required directories, and is ready to accept commands. This guide walks through the full path from binary to running instance, with a Docker Compose alternative for container-based setups.

Prerequisites:

JDK 25 or higher (required to run the JAR)
Gradle 9.5 or higher (required only if building from source)

Standalone JAR
Docker Compose

Get the JAR

Option A — download a release:Grab the latest universe-loader-*.jar from the GitHub releases page.Option B — build from source:Clone the repository and run the Gradle build. Artifacts are copied to .built/ on success.

git clone https://github.com/ohemilyy/universe.git
cd universe
./gradlew build

The fat JAR will be at .built/universe-loader-0.0.1.jar.

Run for the first time

Launch the JAR. If no config.json is found, Universe writes one with defaults and exits — or continues running as a master node.

java -jar universe-loader-0.0.1.jar

The following files and directories are created on first run:

Path	Purpose
`./config.json`	Node identity and cluster settings
`./configuration/`	Instance configuration files (`.json`)
`./templates/`	Template storage (`<group>/<name>/`)
`./running/`	Active instance working directories
`./extensions/`	Extension JARs and their configs

Configure config.json

Open ./config.json and set your node’s identity, cluster name, and role. The full set of fields with their defaults:

config.json

{
  "address": "127.0.0.1",
  "port": 6000,
  "apiPort": 7000,
  "nodeId": "node-1",
  "clusterName": "universe-cluster",
  "isMasterNode": true,
  "masterAddress": "127.0.0.1",
  "masterPort": 6000,
  "masterApiPort": 7000
}

Field	Description
`address`	This node’s bind address for Hazelcast
`port`	Hazelcast cluster port
`apiPort`	Ktor REST API port (Master only)
`nodeId`	Unique identifier for this node
`clusterName`	Hazelcast cluster name — must match across all nodes
`isMasterNode`	`true` to start the Ktor API and act as cluster coordinator
`masterAddress`	Hazelcast address of the Master (used by Wrapper nodes)
`masterPort`	Hazelcast port of the Master
`masterApiPort`	REST API port of the Master

On a single-machine setup, the defaults work without any changes. For a multi-node cluster, set a unique nodeId on each node and point masterAddress / masterPort to the Master.

Restart the JAR after editing config.json.

Add an instance configuration

Instance configurations live in ./configuration/. Create ./configuration/default.json:

configuration/default.json

{
  "name": "default",
  "runtime": "screen",
  "command": "java -jar server.jar",
  "static": false,
  "instanceGroups": [],
  "nodes": ["node-1"],
  "hostAddress": "127.0.0.1",
  "availablePorts": { "min": 25565, "max": 25570 },
  "minimumServiceCount": 1,
  "environmentVariables": {},
  "templateInstallationConfig": {
    "allOf": [{ "name": "base", "group": "server", "storage": "local", "priority": 0 }],
    "allInGroups": [],
    "oneOf": [],
    "oneInGroups": [],
    "onTemplatePasteOverridePresentFiles": false
  },
  "fileModifications": ["server.properties"],
  "properties": {}
}

Key fields to adjust for your application:

Field	Description
`runtime`	Runtime to use: `screen`, `tmux`, `process`, or a custom extension runtime
`command`	Shell command to start the instance process
`nodes`	List of `nodeId` values that can host this instance type
`availablePorts`	Port range Universe scans when allocating a port for the instance
`templateInstallationConfig.allOf`	Templates that are always applied, in priority order
`fileModifications`	Files scanned for variable replacement (`%PORT%`, `%INSTANCE_ID%`, etc.)

Reload configurations without restarting:

config reload

Create your first instance

With the node running and default.json in place, create an instance from the console or the REST API.Console:

instance create default

REST API:

curl -X POST http://localhost:7000/api/instances \
  -H "Content-Type: application/json" \
  -d '{"configurationName": "default"}'

Verify it started:

instance list

Or via REST:

curl http://localhost:7000/api/instances

Docker Compose is the fastest way to run a Master and one or more Wrapper nodes without managing JVM installation.

Create docker-compose.yml

docker-compose.yml

services:
  universe-master:
    image: git.lunarlabs.dev/scala/universe:latest
    container_name: universe-master
    stdin_open: true
    tty: true
    ports:
      - "7000:7000"   # REST API
      - "6000:6000"   # Hazelcast
    volumes:
      - ./data:/data

  universe-wrapper:
    image: git.lunarlabs.dev/scala/universe:latest
    depends_on:
      - universe-master
    volumes:
      - ./wrapper-data:/data

Configure the Wrapper node

The Wrapper needs its own config.json pointing to the Master. Create ./wrapper-data/config.json:

wrapper-data/config.json

{
  "isMasterNode": false,
  "masterAddress": "universe-master",
  "masterPort": 6000,
  "masterApiPort": 7000
}

masterAddress uses the Docker Compose service name. Use the Master’s IP address instead if nodes run outside Compose.

Start the cluster

docker compose up -d

Interact with the running cluster

Option 1 — attach to the console:

docker attach universe-master

Then type commands directly:

cluster status
instance list
instance create default

Detach with Ctrl+P then Ctrl+Q (do not use Ctrl+C — that stops the container).Option 2 — REST API (recommended for scripting):

# List all instances
curl http://localhost:7000/api/instances

# Create an instance
curl -X POST http://localhost:7000/api/instances \
  -H "Content-Type: application/json" \
  -d '{"configurationName": "default"}'

# Execute any console command via REST
curl -X POST http://localhost:7000/api/commands/execute \
  -H "Content-Type: application/json" \
  -d '{"command": "cluster status"}'

Next steps

Architecture

Understand how the Master, Wrappers, Hazelcast task dispatch, and the extension system fit together.

Instance configuration

Full reference for every field in configuration/<name>.json.

Templates

Learn how templates are structured, resolved, and how variable replacement works.

Extensions

Add Docker runtime support, S3 template storage, or build a custom extension.

Get Started

Configuration

Operations

Extensions

Get started with Universe in under five minutes

Next steps

Architecture

Instance configuration

Templates

Extensions

Build docs developers (and LLMs) love

Get Started

Configuration

Operations

Extensions

Documentation Index

​Next steps

Architecture

Instance configuration

Templates

Extensions

Build docs developers (and LLMs) love

Next steps