Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ohemilyy/universe/llms.txt

Use this file to discover all available pages before exploring further.

The config.json file is the primary configuration file for every Universe node. It lives in the working directory from which you launch the JAR (typically ./config.json) and controls the node’s identity, its role in the cluster, how it connects to the master, and the resource limits it enforces when allocating instances. Universe reads this file once on startup; changes require a restart to take effect.
If config.json does not exist when Universe starts, it is created automatically with default values. Review the generated file before deploying to a production cluster — the defaults assume a single-node master setup on 127.0.0.1.

​
Field reference

​
address
string
default:"127.0.0.1"
The IP address this node binds to for Hazelcast cluster communication. Other cluster members must be able to reach this address. Set this to the node’s LAN or public IP when running across multiple machines.
​
port
number
default:"6000"
The TCP port Hazelcast listens on for inter-node cluster traffic. Must be reachable from all other nodes in the cluster.
​
apiPort
number
default:"7000"
The port the Ktor REST API server listens on. Only the master node starts the REST API; this field is still read on wrapper nodes so they can advertise it to clients.
​
nodeId
string
default:"node-1"
A unique identifier for this node within the cluster. Used in instance routing (nodes field in instance configs), log output, and cluster status commands. Must be unique across all nodes in the cluster.
​
clusterName
string
default:"universe-cluster"
The Hazelcast cluster group name. All nodes that should form a single cluster must share the same clusterName. Nodes with different cluster names will not discover each other even on the same network.
​
isMasterNode
boolean
default:"true"
Determines the role this node plays in the cluster. When true, the node starts the Ktor REST API and acts as the cluster coordinator. When false, the node operates as a wrapper — it joins the cluster via Hazelcast and executes instance tasks dispatched by the master.
​
masterAddress
string
default:"127.0.0.1"
The IP address or hostname of the master node. Wrapper nodes use this to connect to the master’s Hazelcast cluster. On the master node itself, set this to the master’s own address so instance configs can reference it for variable replacement (e.g., %MASTER_ADDRESS%).
​
masterPort
number
default:"6000"
The Hazelcast port of the master node. Wrapper nodes connect here to join the cluster.
​
masterApiPort
number
default:"7000"
The REST API port of the master node. Used in template variable replacement as %MASTER_API_PORT% so instances can locate the master API at runtime.
​
debug
boolean
default:"false"
Enables verbose debug logging. Useful when troubleshooting template installation, port allocation, or cluster connectivity. Not recommended in production due to log volume.
​
maxRamMB
number
default:"4096"
The maximum RAM in megabytes this node is permitted to allocate across all running instances. Universe checks available capacity before accepting a new instance deployment. The sum of ramMB values for all running instances on this node will not exceed this limit.
​
maxCpu
number
default:"400"
The maximum CPU units this node is permitted to allocate. Each CPU unit represents 1% of a single core (so 100 = 1 core, 400 = 4 cores). Universe checks this limit before scheduling a new instance on the node.

​
Example

The complete config.json from the README:
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
}

​
Master vs. wrapper configuration

The master node starts the REST API, maintains cluster state, and can also run instances locally. Set isMasterNode to true and point masterAddress to its own address.
config.json (master)
{
  "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": 8192,
  "maxCpu": 800
}
Setting isMasterNode: true on more than one node in a cluster is not supported. Only one node should act as master. If multiple nodes are misconfigured as masters, each will start its own REST API and the cluster will not share state correctly — instances started on one “master” will be invisible to the other.

Build docs developers (and LLMs) love

Get started for freeTalk to us