Node Configuration Reference for Universe

Every Universe node reads ./config.json on startup to determine its identity in the cluster, which address and port to bind Hazelcast on, where the Master lives, and how many resources it may allocate to instances. The same JAR acts as either a Master or a Wrapper depending on the isMasterNode flag; all other fields follow from that role.

If config.json does not exist when you first launch the JAR, Universe creates it automatically alongside the other required directories. Edit the generated file and restart to apply your values.

First-Run Directory Structure

On first launch Universe initialises the following layout next to the JAR:

./
├── config.json          ← node identity & cluster settings
├── database.json        ← database backend settings
├── configuration/       ← instance configuration files (.json)
├── templates/           ← template storage (<group>/<name>/)
├── running/             ← active instance working directories
└── extensions/          ← extension JARs and their configs

Full Configuration Example

{
  "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,
  "debug": false,
  "maxRamMB": 8192,
  "maxCpu": 400,
  "updateSources": [],
  "nodeSpecificVariables": {
    "region": "us-east-1"
  },
  "bindAddress": "127.0.0.1",
  "publicAddress": "127.0.0.1"
}

Field Reference

Field	Type	Default	Description
`address`	string	`"127.0.0.1"`	The IP address this node advertises to the cluster. Used as the default for `bindAddress` and `publicAddress`.
`port`	integer	`6000`	Hazelcast member port.
`apiPort`	integer	`7000`	Ktor REST API port (Master only; Wrappers do not expose an API).
`nodeId`	string	`"node-1"`	Unique identifier for this node within the cluster. Appears in instance metadata and console output.
`clusterName`	string	`"universe-cluster"`	Hazelcast cluster group name. All members in the same cluster must share this value.
`isMasterNode`	boolean	`true`	When `true` this node acts as the Master: it hosts the REST API and dispatches tasks. When `false` it is a Wrapper.
`masterAddress`	string	`"127.0.0.1"`	Hostname or IP of the Master node’s Hazelcast interface. Wrappers use this to join the cluster.
`masterPort`	integer	`6000`	Hazelcast port of the Master node.
`masterApiPort`	integer	`7000`	REST API port of the Master node (used by plugins and clients to reach the API).
`debug`	boolean	`false`	Enables verbose `DEBUG` logging in the console and raises Logback to `INFO` for framework loggers.
`maxRamMB`	integer	`8192`	Maximum RAM in megabytes this node is allowed to allocate across all running instances.
`maxCpu`	integer	`400`	Maximum CPU units this node may allocate. 100 units equals one physical core.
`updateSources`	array	`[]`	List of auto-update source definitions. Each entry polls a remote URL on a schedule and writes the result to a local path. See the sub-fields table below.
`nodeSpecificVariables`	object	`{"region":"us-east-1"}`	Arbitrary key/value pairs exposed as template variables on this node only. Each key `k` becomes `%k%` in template variable replacement.
`bindAddress`	string	`address`	Address Hazelcast binds its server socket to. Set to `"0.0.0.0"` inside Docker to accept connections on all interfaces.
`publicAddress`	string	`address`	Address advertised to other Hazelcast members. Use your Tailscale IP when running behind Docker NAT.

`updateSources` Entry Fields

Each object in the updateSources array controls one auto-update source:

Sub-field	Type	Default	Description
`url`	string	—	Remote file URL to download.
`targetPath`	string	—	Local path to write the file (e.g. `"./configuration/lobby.json"`). Use a trailing slash for template directories (e.g. `"./templates/global/server/"`).
`hashUrl`	string \| null	`null`	Optional URL of a hash file (`.sha256`, `.sha1`, or `.md5`). If omitted, Universe tries common suffixes automatically.
`intervalMs`	integer	`60000`	Polling interval in milliseconds. Default is 60 seconds.
`enabled`	boolean	`true`	Whether this source is active. Set to `false` to pause polling without removing the entry.
`syncToStorage`	string \| null	`null`	Optional storage provider key (e.g. `"s3"`) to sync to after a successful download. When set and `targetPath` is under `./templates/`, the file is also uploaded to that storage provider.

Master vs Wrapper Configuration

Master Node
Wrapper Node
Docker Compose

The Master exposes the REST API, hosts the Hazelcast cluster, and routes deploy/stop tasks to Wrappers. Its isMasterNode must be true and masterAddress/masterPort should point back to itself.

{
  "address": "10.0.0.1",
  "port": 6000,
  "apiPort": 7000,
  "nodeId": "master-1",
  "clusterName": "universe-cluster",
  "isMasterNode": true,
  "masterAddress": "10.0.0.1",
  "masterPort": 6000,
  "masterApiPort": 7000,
  "debug": false,
  "maxRamMB": 16384,
  "maxCpu": 800
}

When running in Docker, set bindAddress to "0.0.0.0" so Hazelcast accepts inbound connections from Wrapper containers, and set publicAddress to the container’s reachable IP or Tailscale address.

Wrappers receive tasks from the Master via Hazelcast and execute them locally. Set isMasterNode to false and point masterAddress/masterPort at the Master. The apiPort field is ignored on a Wrapper.

{
  "address": "10.0.0.2",
  "port": 6001,
  "apiPort": 7001,
  "nodeId": "wrapper-1",
  "clusterName": "universe-cluster",
  "isMasterNode": false,
  "masterAddress": "10.0.0.1",
  "masterPort": 6000,
  "masterApiPort": 7000,
  "debug": false,
  "maxRamMB": 8192,
  "maxCpu": 400
}

Every Wrapper must use the same clusterName as the Master or Hazelcast will refuse to admit it to the cluster.

When the Wrapper runs in the same Docker Compose project as the Master, use the Compose service name as masterAddress:

{
  "isMasterNode": false,
  "masterAddress": "universe-master",
  "masterPort": 6000,
  "masterApiPort": 7000,
  "bindAddress": "0.0.0.0",
  "publicAddress": "10.0.0.2"
}

Replace publicAddress with the Docker bridge IP or Tailscale IP so that Hazelcast members on different networks can route back to the Wrapper.

Debug Logging

The debug field controls the verbosity of both the user-facing console and the SLF4J/Logback file logger:

`debug` value	Console output	Logback console	Log file
`false`	`INFO`+ operational messages	`WARN`+ only	Full detail
`true`	`INFO`+ and `DEBUG` messages	`INFO`+ for all loggers including Hazelcast, Netty	Full detail

Log files are written to ./logs/universe.log, rotated daily, and retained for 30 days.

Getting Started

Configuration

Runtimes

Extensions

Minecraft Integration

Operations

Node Configuration Reference for Universe

First-Run Directory Structure

Full Configuration Example

Field Reference

`updateSources` Entry Fields

Master vs Wrapper Configuration

Debug Logging

Build docs developers (and LLMs) love

Getting Started

Configuration

Runtimes

Extensions

Minecraft Integration

Operations

Documentation Index

​First-Run Directory Structure

​Full Configuration Example

​Field Reference

​updateSources Entry Fields

​Master vs Wrapper Configuration

​Debug Logging

Build docs developers (and LLMs) love

First-Run Directory Structure

Full Configuration Example

Field Reference

`updateSources` Entry Fields

Master vs Wrapper Configuration

Debug Logging