Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/universeclouddev/Universe/llms.txt

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

A Configuration is the blueprint Universe uses to create instances. It defines everything from which runtime to use and how much RAM to allocate, to which templates to install, which ports to expose, and what environment variables to inject. Configurations are stored in the cluster’s shared Hazelcast state and on disk under ./configuration/. All endpoints in this group require a Bearer token with ALL permission.
The name in the URL path always takes precedence over any name field in the request body — the server calls .copy(name = name) before saving. Always ensure the path name and intended configuration name match.

​
The Configuration Object

​
name
string
required
Unique identifier for this configuration (e.g., lobby, game-duels). Used as the key in all API paths and in CreateInstanceRequest.
​
runtime
string
Runtime provider key. Defaults to screen. Built-in options: screen, tmux. Extension-provided: docker, k8s.
​
command
string
Shell command to execute when starting the instance (e.g., java -Xmx2048M -jar server.jar).
​
static
boolean
Whether this is a static (persistent) instance whose working directory survives restarts. Defaults to false.
​
ramMB
integer
RAM in megabytes to allocate per instance. Defaults to 2048. Used for node resource scheduling.
​
cpu
integer
CPU units per instance. 100 = 1 full core. Defaults to 100.
​
instanceGroups
string[]
Logical group tags this configuration belongs to (e.g., ["lobby", "hub"]). Used for group-based queries.
​
nodes
string[]
List of node IDs allowed to host instances of this configuration. Defaults to ["node-1"]. Instances are only scheduled onto nodes in this list.
​
hostAddress
string
Host address advertised to clients for connecting to instances. Supports template variables like %TAILSCALE_IP%. Defaults to 127.0.0.1.
​
availablePorts
PortRange object
​
minimumServiceCount
integer
Minimum number of running instances to maintain for this configuration. The master node will auto-create new instances if the count falls below this. Defaults to 1.
​
environmentVariables
object
Key-value map of environment variables injected into the instance process. The default includes {"UNIVERSE_INSTANCE_ID": "%INSTANCE_ID%"}.
​
templateInstallationConfig
TemplateInstallationConfig object
​
fileModifications
string[]
Relative paths of files to scan for variable replacement after templates are installed (e.g., ["server.properties", "plugins/Universe/config.yml"]).
​
properties
object
Custom key-value map for user-defined template variables. Each {"myKey": "myValue"} entry makes %myKey% available as a replacement token in fileModifications files.
​
additionalPorts
AdditionalPort[]
Additional ports to expose beyond the primary allocatedPort. Each entry has port (integer), protocol (default "TCP"), and name (string label) fields.

​
Endpoints

​
GET /api/configurations

Returns all instance configurations currently stored in the cluster state. Authentication: ALL permission required. 
curl http://localhost:8080/api/configurations \
  -H "Authorization: Bearer YOUR_API_KEY"
Response — 200 OK An array of Configuration objects. 
[
  {
    "name": "lobby",
    "runtime": "screen",
    "command": "java -Xmx2048M -jar server.jar",
    "static": false,
    "ramMB": 2048,
    "cpu": 100,
    "instanceGroups": ["lobby"],
    "nodes": ["node-1"],
    "hostAddress": "127.0.0.1",
    "availablePorts": { "min": 25565, "max": 25570 },
    "minimumServiceCount": 1,
    "environmentVariables": { "UNIVERSE_INSTANCE_ID": "%INSTANCE_ID%" },
    "templateInstallationConfig": {
      "allOf": [{ "name": "base", "group": "server", "storage": "local", "priority": 0 }],
      "allInGroups": [],
      "oneOf": [],
      "oneInGroups": [],
      "onTemplatePasteOverridePresentFiles": false
    },
    "fileModifications": ["server.properties"],
    "properties": {},
    "additionalPorts": []
  }
]
StatusMeaning
200Success, array returned (may be empty).
401Unauthorized.

​
GET /api/configurations/

Returns a single configuration by its unique name. Authentication: ALL permission required. Path Parameters
​
name
string
required
The configuration name (e.g., lobby).
curl http://localhost:8080/api/configurations/lobby \
  -H "Authorization: Bearer YOUR_API_KEY"
Response — 200 OK A single Configuration object.
StatusMeaning
200Configuration found and returned.
404No configuration with this name exists.
401Unauthorized.

​
PUT /api/configurations/

Creates or fully replaces a configuration. The request body must be a complete Configuration object. The name field in the body is ignored — the path parameter is always used as the authoritative name. Authentication: ALL permission required. Path Parameters
​
name
string
required
The configuration name to create or overwrite (e.g., lobby).
Request Body — Complete Configuration object.
​
name
string
Ignored; the URL path parameter is used. May be omitted.
​
runtime
string
Runtime provider key. Defaults to screen.
​
command
string
Start command for the instance process.
​
static
boolean
Whether the instance is persistent across restarts. Defaults to false.
​
ramMB
integer
RAM to allocate in megabytes. Defaults to 2048.
​
cpu
integer
CPU units to allocate (100 = 1 core). Defaults to 100.
​
instanceGroups
string[]
Group tags for this configuration.
​
nodes
string[]
Node IDs eligible to run instances of this configuration.
​
hostAddress
string
Host address for client connections.
​
availablePorts
object
Port allocation range with min and max fields.
​
minimumServiceCount
integer
Minimum live instance count to maintain.
​
environmentVariables
object
Environment variable key-value map.
​
templateInstallationConfig
object
Template installation instructions including allOf, allInGroups, oneOf, oneInGroups, and onTemplatePasteOverridePresentFiles.
​
fileModifications
string[]
List of relative file paths to scan for variable replacement.
​
properties
object
Custom template variable map (keys become %KEY% tokens).
​
additionalPorts
array
Additional ports to expose, each with port, protocol, and name.
curl -X PUT http://localhost:8080/api/configurations/lobby \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "runtime": "screen",
    "command": "java -Xmx2048M -jar server.jar",
    "static": false,
    "ramMB": 2048,
    "cpu": 100,
    "instanceGroups": ["lobby"],
    "nodes": ["node-1"],
    "hostAddress": "127.0.0.1",
    "availablePorts": { "min": 25565, "max": 25570 },
    "minimumServiceCount": 1,
    "environmentVariables": { "UNIVERSE_INSTANCE_ID": "%INSTANCE_ID%" },
    "templateInstallationConfig": {
      "allOf": [{ "name": "base", "group": "server", "storage": "local", "priority": 0 }],
      "allInGroups": [],
      "oneOf": [],
      "oneInGroups": [],
      "onTemplatePasteOverridePresentFiles": false
    },
    "fileModifications": ["server.properties"],
    "properties": {},
    "additionalPorts": []
  }'
Response — 204 No Content No body is returned on success.
StatusMeaning
204Configuration saved.
401Unauthorized.
PUT performs a full replacement. Any fields omitted from the request body will revert to their default values. Read the current configuration first if you only intend to update one field.

​
DELETE /api/configurations/

Permanently removes a configuration from the cluster state. Existing running instances that were created from this configuration are not affected — only future deployments are blocked. Authentication: ALL permission required. Path Parameters
​
name
string
required
The name of the configuration to delete (e.g., lobby).
curl -X DELETE http://localhost:8080/api/configurations/lobby \
  -H "Authorization: Bearer YOUR_API_KEY"
Response — 204 No Content No body is returned on success.
StatusMeaning
204Configuration deleted.
401Unauthorized.

Build docs developers (and LLMs) love

Get started for freeTalk to us