Universe is a general-purpose instance orchestrator that ships as a single fat JAR. You configure whether a node acts as a Master or a Wrapper, launch the same binary on each machine, and Universe handles the rest — dispatching deploy tasks over Hazelcast, copying templates into place, replacing dynamic variables, and starting processes through pluggable runtime providers. This documentation walks you through running your first node, understanding the cluster model, and extending Universe with custom runtimes or template storage backends.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.
What Universe does
Universe sits between the operator (you, or an upstream service) and the running application processes. The Master node exposes a Ktor REST API and a console command system; it stores cluster state in Hazelcast distributed maps and dispatches lifecycle tasks to Wrapper nodes. Wrapper nodes receive those tasks, resolve templates from the local filesystem, apply variable substitution, allocate a port, and start the instance with the configured runtime. Because Master and Wrapper run from the same JAR, the Master also acts as a Wrapper — it can host instances locally while simultaneously coordinating the rest of the cluster.Key concepts
Before diving deeper, it helps to have these terms defined:| Term | Definition |
|---|---|
| Instance | A running application process managed by Universe. Represented by InstanceInfo with a 6-character alphanumeric ID, allocated port, state, and heartbeat timestamp. |
| Template | A directory tree under ./templates/<group>/<name>/ that is copied to ./running/<instance-id>/ when an instance is created. |
| Configuration | A JSON file in ./configuration/ (e.g., default.json) that declares the runtime, command, port range, template selection, and variable-replacement targets for a class of instance. |
| InstanceGroup | A logical grouping label applied to instances via Configuration.instanceGroups. Allows templates and sync operations to target multiple instances by group name. |
| Extension | A self-registering JAR placed in ./extensions/. Extensions implement the Extension interface and register custom runtimes, template storage backends, or variable providers in onLoad(). |
Feature overview
Master/Wrapper cluster
One Master exposes the REST API and holds cluster state. Any number of Wrapper nodes execute instances. All run from the same JAR — role is set by
isMasterNode in config.json.Template-based deployment
Instances are created from file-tree templates.
TemplateManager resolves, copies, and applies dynamic variable replacement (%PORT%, %INSTANCE_ID%, %MASTER_IP%, and more).Pluggable runtimes
Built-in
screen, tmux, and raw process runtimes are registered at startup. Docker support is available via the runtime-docker extension. Add your own by implementing RuntimeProvider.Console & REST commands
Every command (
instance create, template sync, cluster status, and more) works identically from the interactive console and via POST /api/commands/execute.Remote template storage
The
storage-s3 extension stores and retrieves template archives from AWS S3, enabling centralized template management across cluster nodes.Extension system
Extensions are isolated JARs that depend only on
:api and :extensions:extension-api. They register via injected Guice-managed registries — never by modifying core code.Architecture summary
Universe uses a two-tier cluster: a single Master coordinates state and dispatch; one or more Wrappers execute instances. All inter-node communication flows through Hazelcast — the Master submitsCallable tasks to the IExecutorService, and Wrappers receive and route them to the appropriate handler.
The Master is also a Wrapper. When
isMasterNode is true, the node starts the Ktor REST API and consumes IExecutorService tasks, hosting instances locally like any other Wrapper.