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.

Instance configuration files live in ./configuration/<name>.json and describe a class of instances that Universe can deploy. Each file corresponds to one named configuration — for example, ./configuration/lobby.json defines how lobby instances are started, which templates they use, and which nodes they can run on. The master node loads all .json files from this directory at startup and reloads them when you run config reload.
If the ./configuration/ directory contains no valid JSON files when Universe starts, a default lobby.json is created automatically so the node has at least one configuration to work with.

​
Example

The complete default.json from the README:
./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": {}
}

​
Field reference

​
name
string
required
The identifier for this configuration. Must match the filename without the .json extension. Used in CLI commands (instance create <name>), REST API calls, and the %CONFIGURATION_NAME% template variable.
​
runtime
string
default:"screen"
The process runtime used to start and manage instances. Built-in options are screen, tmux, and process. The docker runtime is available via the runtime-docker extension. See runtime options below.
​
command
string
default:""
The shell command executed to start each instance. Runs inside the instance’s working directory (./running/<instance-id>/). Note that template variable replacement (%PORT%, %INSTANCE_ID%, etc.) is applied to files listed in fileModifications, not to the command string itself.
​
static
boolean
default:"false"
When true, the instance’s working directory (./running/<instance-id>/) is not deleted after the instance stops. Use this for stateful instances that need to persist data between restarts. When false, the directory is cleaned up on shutdown.
​
ramMB
number
default:"512"
The amount of RAM in megabytes to reserve for each instance of this configuration. Universe checks the node’s maxRamMB capacity before deploying; if the node does not have enough headroom, the instance will not start on that node.
​
cpu
number
default:"100"
CPU units to reserve per instance. One unit represents 1% of a single core, so 100 equals one full core and 400 equals four cores. Universe checks the node’s maxCpu before deploying.
​
instanceGroups
string[]
default:"[]"
Logical group labels for instances of this configuration. Groups are used for routing and discovery by external plugins or services. An instance can belong to multiple groups.
​
nodes
string[]
default:"[\"node-1\"]"
The list of node IDs that are eligible to run instances of this configuration. When a new instance is requested, Universe picks an eligible node that has sufficient capacity. Leave empty to allow any node.
​
hostAddress
string
default:"127.0.0.1"
The address instances of this configuration advertise to connecting clients. Used in the %HOST_ADDRESS% template variable and stored in InstanceInfo. Set this to the node’s public or LAN IP when instances need to be reachable from outside the cluster.
​
availablePorts
object
The port range from which Universe allocates a port for each new instance. Universe picks the lowest available port in the range.
{ "min": 25565, "max": 25570 }
  • min — Lowest port in the range (inclusive).
  • max — Highest port in the range (inclusive).
​
minimumServiceCount
number
default:"1"
The minimum number of instances that should be running for this configuration at all times. Universe automatically starts additional instances when the running count falls below this value. Set to 0 to disable auto-spawning.
​
environmentVariables
object
default:"{}"
A key/value map of environment variables injected into the instance process at startup. Useful for passing secrets, JVM flags, or runtime settings without embedding them in the command string.
{ "JAVA_OPTS": "-Xmx1G", "DEBUG": "false" }
​
templateInstallationConfig
object
Controls which templates are installed into the instance’s working directory before startup. See template installation config below.
​
fileModifications
string[]
default:"[]"
A list of file paths (relative to the instance working directory) where template variable replacement is applied after templates are installed. Any file listed here will have placeholders like %PORT% and %INSTANCE_ID% replaced with their runtime values.
["server.properties", "config/settings.yml"]
​
properties
object
default:"{}"
An arbitrary string key/value map for custom metadata. Universe does not interpret this field internally; it is available to extensions and external plugins via the Configuration object for custom routing, labeling, or feature flags.

​
Template installation config

The templateInstallationConfig object determines which templates are copied into the instance directory before launch.
​
templateInstallationConfig.allOf
Template[]
default:"[]"
An explicit list of templates to install. Every template in this list is always installed. Each entry requires:
  • name — Template name (the subdirectory name under its group).
  • group — Template group (the top-level directory under ./templates/).
  • storage — Storage backend: "local" or a registered extension storage key (e.g., "s3").
  • priority — Integer priority controlling install order relative to other templates.
​
templateInstallationConfig.allInGroups
string[]
default:"[]"
A list of template group names. Every template found in each group directory is installed. Templates discovered via registered storage providers are also included.
​
templateInstallationConfig.oneOf
Template[]
default:"[]"
A list of templates from which exactly one is selected at random and installed. Use this when instances should receive one of several interchangeable template variants.
​
templateInstallationConfig.oneInGroups
string[]
default:"[]"
A list of group names. For each group, exactly one template from that group is selected at random and installed.
​
templateInstallationConfig.onTemplatePasteOverridePresentFiles
boolean
default:"false"
Controls how templates are applied when multiple templates write to the same path:
  • false — Higher-priority templates are pasted first and are not overwritten by lower-priority ones.
  • true — Lower-priority templates are pasted first; higher-priority templates are pasted last and overwrite existing files.

​
Runtime options

The runtime field selects how Universe starts and manages each instance process.
RuntimeDescription
screenStarts the instance inside a GNU Screen session. Supports stdin piping for in-process command execution. Requires screen on the host.
tmuxStarts the instance inside a tmux session. Equivalent capability to screen; prefer whichever multiplexer your environment has installed.
processStarts the instance as a direct child process without a terminal multiplexer. Simpler but provides no persistent session if Universe restarts.
dockerStarts the instance as a Docker container. Requires the runtime-docker extension JAR in ./extensions/.

​
Auto-spawn behavior

When minimumServiceCount is greater than 0, Universe monitors the number of running instances for this configuration and automatically starts new instances when the count drops below the minimum. This ensures a pool of instances is always available without manual intervention.
Set minimumServiceCount: 0 for configurations that should only be started on demand via the API or CLI, such as one-off job runners or debug instances.

Build docs developers (and LLMs) love

Get started for freeTalk to us