universe docs source
README.md 34 lines

orchestrator control plane

drive the whole cluster over HTTP.

Every console action is an endpoint. Deploy instances, stream live logs, edit templates and dispatch commands across nodes, authenticated with a single bearer token, served by the master on :7000.

openapi 3.0.3 bearer auth :7000 v1.0.0
base url
http://localhost:7000/api
download openapi.json · 3.0.3
authentication
# send your key on every request
Authorization: Bearer $KEY
# mint one from the master console
› key create --scope ALL
WebSocket handshakes carry the same bearer header.
permissions & limits
ALL · full access · bypasses rate limits
PUBLIC · public reads only · no instance ops
Public keys are capped at 100 calls / 60s; admin keys are unmetered.
node.http 5 lines

  • Returns basic status information about the Universe node.

    # responses

    200 Universe is running object

    # example

    curl :7000/api/ping

  • Returns system statistics and uptime for the current node.

    # responses

    200 Node details object
    401 Missing or invalid Authorization header

    # example

    curl :7000/api/node \
  -H "Authorization: Bearer $KEY"

  • Returns the current node's main configuration ( UniverseMainConfiguration).

    # responses

    200 Node configuration UniverseMainConfiguration
    401 Missing or invalid Authorization header

    # example

    curl :7000/api/node/config \
  -H "Authorization: Bearer $KEY"

  • Reloads the node configuration from disk. (Not fully implemented.)

    # responses

    401 Missing or invalid Authorization header
    501 Not Implemented object

    # example

    curl -X POST :7000/api/node/reload \
  -H "Authorization: Bearer $KEY"

  • Returns metrics in Prometheus exposition format. Used by Prometheus or other monitoring systems.

    # responses

    200 Prometheus metrics string

    # example

    curl :7000/api/metrics
cluster.http 3 lines

  • Returns a list of all nodes in the Hazelcast cluster.

    # responses

    200 List of nodes object[]
    401 Missing or invalid Authorization header

    # example

    curl :7000/api/cluster/nodes \
  -H "Authorization: Bearer $KEY"

  • Returns detailed information about a cluster node, including its instances.

    # parameters

    name in type req description
    id path string ✓

    # responses

    200 Node details object
    401 Missing or invalid Authorization header

    # example

    curl :7000/api/cluster/nodes/{id} \
  -H "Authorization: Bearer $KEY"

  • Executes a console command on the specified node. - If id is the current node: runs locally (not yet implemented) - If id is a remote node: dispatches via Hazelcast (not yet implemented)

    # parameters

    name in type req description
    id path string ✓

    # request body

    application/json → ClusterCommandRequest required

    # responses

    400 Cannot execute command on local node via API object
    401 Missing or invalid Authorization header
    501 Remote node command execution not yet implemented

    # example

    curl -X POST :7000/api/cluster/nodes/{id} \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
instances.http 9 lines

  • Returns all instances across the cluster (active and stopped).

    # responses

    200 List of instances InstanceInfo[]
    401 Missing or invalid Authorization header

    # example

    curl :7000/api/instances \
  -H "Authorization: Bearer $KEY"

  • Deploys a new instance using the specified configuration.

    # request body

    application/json → CreateInstanceRequest required

    # responses

    201 Instance created InstanceInfo
    400 Invalid configuration name
    401 Missing or invalid Authorization header

    # example

    curl -X POST :7000/api/instances \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

  • Returns detailed information about an instance. Requires ALL permission: This endpoint requires an API key with ALL permission.

    # parameters

    name in type req description
    id path string ✓

    # responses

    200 Instance details InstanceInfo
    401 Missing or invalid Authorization header

    # example

    curl :7000/api/instances/{id} \
  -H "Authorization: Bearer $KEY"

  • Stops the instance and removes it from the cluster.

    # parameters

    name in type req description
    id path string ✓

    # responses

    200 Instance stopped object
    401 Missing or invalid Authorization header

    # example

    curl -X DELETE :7000/api/instances/{id} \
  -H "Authorization: Bearer $KEY"

  • Returns the most recent log lines for an instance. Works with all runtimes (Docker, K8s, screen, tmux, process). Requires ALL permission: This endpoint requires an API key with ALL permission.

    # parameters

    name in type req description
    id path string ✓
    lines query integer - Number of log lines to return

    # responses

    200 Log lines object
    401 Missing or invalid Authorization header

    # example

    curl :7000/api/instances/{id}/logs \
  -H "Authorization: Bearer $KEY"

  • Opens a WebSocket connection that streams live log output from the instance. Requires ALL permission: This endpoint requires an API key with ALL permission. Connect with: `` ws://host/api/instances/{id}/live-log Authorization: Bearer YOUR_TOKEN `` Messages are sent as text frames.

    # parameters

    name in type req description
    id path string ✓

    # responses

    101 WebSocket connection established
    401 Missing or invalid Authorization header

    # example

    curl :7000/api/instances/{id}/live-log \
  -H "Authorization: Bearer $KEY"

  • Updates the state and/or heartbeat timestamp of an instance.

    # parameters

    name in type req description
    id path string ✓

    # request body

    application/json → UpdateStateRequest required

    # responses

    200 State updated InstanceInfo
    401 Missing or invalid Authorization header

    # example

    curl -X PUT :7000/api/instances/{id}/state \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

  • Controls the lifecycle of an instance: - start: Start a stopped instance - stop: Stop a running instance - restart: Restart the instance

    # parameters

    name in type req description
    id path string ✓
    target query "start" | "stop" | "restart" ✓ Target lifecycle state

    # responses

    200 Lifecycle changed object
    400 Invalid target state or instance not found
    401 Missing or invalid Authorization header

    # example

    curl -X PATCH :7000/api/instances/{id}/lifecycle \
  -H "Authorization: Bearer $KEY"

  • Sends a command to the instance's stdin. The command is piped directly to the running process (e.g., Minecraft console).

    # parameters

    name in type req description
    id path string ✓

    # request body

    application/json → ExecuteOnInstanceRequest required

    # responses

    200 Command dispatched object
    401 Missing or invalid Authorization header

    # example

    curl -X POST :7000/api/instances/{id}/execute \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
configurations.http 4 lines

  • Returns all instance configurations.

    # responses

    200 List of configurations Configuration[]
    401 Missing or invalid Authorization header

    # example

    curl :7000/api/configurations \
  -H "Authorization: Bearer $KEY"

  • Returns a specific configuration by name.

    # parameters

    name in type req description
    name path string ✓

    # responses

    200 Configuration details Configuration
    401 Missing or invalid Authorization header
    404 Configuration not found

    # example

    curl :7000/api/configurations/{name} \
  -H "Authorization: Bearer $KEY"

  • Creates or updates an instance configuration.

    # parameters

    name in type req description
    name path string ✓

    # request body

    application/json → Configuration required

    # responses

    204 Configuration saved
    401 Missing or invalid Authorization header

    # example

    curl -X PUT :7000/api/configurations/{name} \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

  • Deletes an instance configuration.

    # parameters

    name in type req description
    name path string ✓

    # responses

    204 Configuration deleted
    401 Missing or invalid Authorization header

    # example

    curl -X DELETE :7000/api/configurations/{name} \
  -H "Authorization: Bearer $KEY"
templates.http 11 lines

  • Returns all available templates organized by group.

    # responses

    200 List of templates object[]
    401 Missing or invalid Authorization header

    # example

    curl :7000/api/templates \
  -H "Authorization: Bearer $KEY"

  • Returns details about a specific template.

    # parameters

    name in type req description
    group path string ✓
    name path string ✓

    # responses

    200 Template details object
    401 Missing or invalid Authorization header

    # example

    curl :7000/api/templates/{group}/{name} \
  -H "Authorization: Bearer $KEY"

  • Returns all files within a local template directory.

    # parameters

    name in type req description
    group path string ✓
    name path string ✓

    # responses

    200 List of files object
    401 Missing or invalid Authorization header

    # example

    curl :7000/api/templates/{group}/{name}/files \
  -H "Authorization: Bearer $KEY"

  • Returns the contents of a specific file within a template.

    # parameters

    name in type req description
    group path string ✓
    name path string ✓
    path path string ✓ Relative file path (e.g. server.properties)

    # responses

    200 File contents string
    401 Missing or invalid Authorization header
    404 File not found

    # example

    curl :7000/api/templates/{group}/{name}/files/{path} \
  -H "Authorization: Bearer $KEY"

  • Creates a new file within a local template. Fails if the file already exists. Accepts any content type (text, binary, images, jars, etc.).

    # parameters

    name in type req description
    group path string ✓
    name path string ✓
    path path string ✓ Relative file path

    # request body

    application/octet-stream → binary required

    # responses

    201 File created object
    401 Missing or invalid Authorization header
    409 File already exists

    # example

    curl -X POST :7000/api/templates/{group}/{name}/files/{path} \
  -H "Authorization: Bearer $KEY" \
  --data-binary @archive.zip

  • Updates the contents of a file within a local template.

    # parameters

    name in type req description
    group path string ✓
    name path string ✓
    path path string ✓ Relative file path

    # request body

    text/plain → string required

    # responses

    200 File updated object
    401 Missing or invalid Authorization header

    # example

    curl -X PATCH :7000/api/templates/{group}/{name}/files/{path} \
  -H "Authorization: Bearer $KEY" \
  --data-binary @file.txt

  • Deletes a file within a local template.

    # parameters

    name in type req description
    group path string ✓
    name path string ✓
    path path string ✓ Relative file path

    # responses

    200 File deleted object
    401 Missing or invalid Authorization header

    # example

    curl -X DELETE :7000/api/templates/{group}/{name}/files/{path} \
  -H "Authorization: Bearer $KEY"

  • Exports a local template as a zip file.

    # parameters

    name in type req description
    group path string ✓
    name path string ✓

    # responses

    200 Zip file binary
    401 Missing or invalid Authorization header
    404 Template not found

    # example

    curl -X POST :7000/api/templates/{group}/{name}/export \
  -H "Authorization: Bearer $KEY"

  • Imports a template from a zip file, overwriting existing files.

    # parameters

    name in type req description
    group path string ✓
    name path string ✓

    # request body

    application/zip → binary required

    # responses

    200 Import successful object
    401 Missing or invalid Authorization header

    # example

    curl -X POST :7000/api/templates/{group}/{name}/import \
  -H "Authorization: Bearer $KEY" \
  --data-binary @archive.zip

  • Downloads the latest version of a template from a remote storage provider.

    # parameters

    name in type req description
    group path string ✓
    name path string ✓

    # request body

    application/json → StorageSyncRequest required

    # responses

    200 Sync successful object
    400 Storage provider not found
    401 Missing or invalid Authorization header

    # example

    curl -X POST :7000/api/templates/{group}/{name}/sync \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

  • Dispatches a template sync task to the cluster via Hazelcast.

    # request body

    application/json → TemplateSyncRequest required

    # responses

    200 Sync initiated object
    401 Missing or invalid Authorization header

    # example

    curl -X POST :7000/api/templates/sync \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
console.http 2 lines

  • Executes a command on the Universe master node's console. The command output is captured and returned in the response.

    # request body

    application/json → ExecuteCommandRequest required

    # responses

    200 Command output object
    401 Missing or invalid Authorization header

    # example

    curl -X POST :7000/api/commands/execute \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

  • Opens an interactive WebSocket console to the Universe master node. Connect with: `` ws://host/api/console Authorization: Bearer YOUR_TOKEN `` Send commands as text frames. Responses are streamed back as text frames.

    # responses

    101 WebSocket connection established
    401 Missing or invalid Authorization header

    # example

    curl :7000/api/console \
  -H "Authorization: Bearer $KEY"
schemas.ts 15 lines

The shapes referenced by every endpoint. Aqua types are links. Click to jump to their definition.

InstanceInfo interface
interface InstanceInfo {
id?: string // Unique 6-character instance ID · e.g. "a1b2c3"
configurationName?: string // Name of the configuration this instance uses · e.g. "lobby"
wrapperNodeId?: string // ID of the node hosting this instance · e.g. "node-1"
hostAddress?: string // Host address clients should connect to · e.g. "127.0.0.1"
allocatedPort?: integer // Port allocated for this instance · e.g. 25565
state?: InstanceState
lastHeartbeat?: int<int64> // Unix timestamp of last heartbeat
processPid?: int<int64> | null // Process ID (null for container runtimes)
allocatedRamMB?: integer // Allocated RAM in MB · e.g. 2048
allocatedCpu?: integer // Allocated CPU units (100 = 1 core) · e.g. 100
runtime?: string // Runtime provider used (screen, docker, k8s, etc.) · e.g. "docker"
}
InstanceState enum

# - CREATING: Instance is being deployed - ONLINE: Instance is running and healthy - OFFLINE: Instance has missed heartbeats - STOPPED: Instance has been stopped

type InstanceState =
| "CREATING"
| "ONLINE"
| "OFFLINE"
| "STOPPED"
Configuration interface
interface Configuration {
name?: string // Unique configuration name · e.g. "lobby"
runtime?: string // Runtime provider key · e.g. "docker"
command?: string // Command to start the instance · e.g. "java -Xmx2048M -jar server.jar"
static?: boolean // Whether this is a static (persistent) instance · default false
ramMB?: integer // RAM allocated in MB · e.g. 2048
cpu?: integer // CPU units (100 = 1 core) · e.g. 100
instanceGroups?: string[] // Groups this configuration belongs to · e.g. ["lobby"]
nodes?: string[] // Nodes allowed to host this instance · e.g. ["node-1"]
hostAddress?: string // Host address for client connections · e.g. "127.0.0.1"
availablePorts?: PortRange
minimumServiceCount?: integer // Minimum number of instances to maintain · e.g. 1
environmentVariables?: Record<string, string> // Environment variables for the instance · e.g. {"UNIVERSE_INSTANCE_ID":"%INSTANCE_ID%"}
templateInstallationConfig?: TemplateInstallationConfig
fileModifications?: string[] // Files to modify after template installation · e.g. ["server.properties"]
properties?: Record<string, string> // Additional configuration properties
}
PortRange interface
interface PortRange {
min?: integer // Minimum port number · e.g. 25565
max?: integer // Maximum port number · e.g. 25570
}
TemplateInstallationConfig interface
interface TemplateInstallationConfig {
allOf?: Template[] // Templates to install (all required)
allInGroups?: string[] // Template groups to install entirely
oneOf?: Template[] // Templates to choose one from
oneInGroups?: string[] // Template groups to choose one template from
onTemplatePasteOverridePresentFiles?: boolean // Whether templates override existing files · default false
}
Template interface
interface Template {
name?: string // e.g. "server"
group?: string // e.g. "default"
storage?: string // Storage backend (local, s3) · e.g. "local"
priority?: integer // Installation priority order · e.g. 1
}
NodeResources interface
interface NodeResources {
usedRamMB?: integer // Currently used RAM in MB
usedCpu?: integer // Currently used CPU units
}
UniverseMainConfiguration interface
interface UniverseMainConfiguration {
address?: string // e.g. "127.0.0.1"
port?: integer // Hazelcast cluster port · e.g. 6000
apiPort?: integer // REST API port · e.g. 7000
nodeId?: string // e.g. "node-1"
clusterName?: string // e.g. "universe-cluster"
isMasterNode?: boolean
masterAddress?: string
masterPort?: integer
masterApiPort?: integer
debug?: boolean
maxRamMB?: integer
maxCpu?: integer
}
CreateInstanceRequest interface
interface CreateInstanceRequest {
configurationName: string // Name of the configuration to use · e.g. "lobby"
}
UpdateStateRequest interface
interface UpdateStateRequest {
state: "CREATING" | "ONLINE" | "OFFLINE" | "STOPPED" // New state value
lastHeartbeat?: int<int64> // Unix timestamp (optional, resets if not provided)
}
ExecuteOnInstanceRequest interface
interface ExecuteOnInstanceRequest {
command: string // Command to execute on the instance · e.g. "op andyreckt"
}
ClusterCommandRequest interface
interface ClusterCommandRequest {
command: string // Console command to execute · e.g. "instance list"
}
TemplateSyncRequest interface
interface TemplateSyncRequest {
pattern: string // Template pattern to sync (e.g., default/*, group/name) · e.g. "default/*"
}
StorageSyncRequest interface
interface StorageSyncRequest {
storage: string // Storage provider key (e.g. s3, ftp) · e.g. "s3"
}
ExecuteCommandRequest interface
interface ExecuteCommandRequest {
command: string // Console command to execute on the master node · e.g. "help"
}
← back to readme ❯ view the source