Instances API

An instance is a single running process managed by a Wrapper node. Its record, an InstanceInfo object, is stored in the Master’s distributed instances map and shared across the cluster. These endpoints expose that record and the control actions that mutate it.

The InstanceInfo object

Instance states

List instances

GET /api/instances

Returns every instance across the cluster, active and stopped, as a JSON array.

curl http://<master>:7000/api/instances \
  -H "Authorization: Bearer YOUR_TOKEN"

[
  {
    "id": "a1b2c3",
    "configurationName": "lobby",
    "wrapperNodeId": "node-1",
    "hostAddress": "127.0.0.1",
    "allocatedPort": 25565,
    "state": "ONLINE",
    "lastHeartbeat": 1718000000000,
    "processPid": 12345,
    "allocatedRamMB": 2048,
    "allocatedCpu": 100,
    "runtime": "screen"
  }
]

Get an instance

GET /api/instances/{id}

Returns a single InstanceInfo by ID.

curl http://<master>:7000/api/instances/a1b2c3 \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "id": "a1b2c3",
  "configurationName": "lobby",
  "wrapperNodeId": "node-1",
  "hostAddress": "127.0.0.1",
  "allocatedPort": 25565,
  "state": "ONLINE",
  "lastHeartbeat": 1718000000000,
  "processPid": 12345,
  "allocatedRamMB": 2048,
  "allocatedCpu": 100,
  "runtime": "screen"
}

Create an instance

POST /api/instances

Deploys a new instance from an existing configuration. The Master selects an eligible Wrapper, allocates a port, writes the record with state: CREATING, and dispatches the deploy task. The response returns immediately with the new record; the state advances to ONLINE once the Wrapper finishes starting the process.

curl -X POST http://<master>:7000/api/instances \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"configurationName": "lobby"}'

{
  "id": "a1b2c3",
  "configurationName": "lobby",
  "wrapperNodeId": "node-1",
  "hostAddress": "127.0.0.1",
  "allocatedPort": 25565,
  "state": "CREATING",
  "lastHeartbeat": 1718000000000,
  "processPid": null,
  "allocatedRamMB": 2048,
  "allocatedCpu": 100,
  "runtime": "screen"
}

Stop and delete an instance

DELETE /api/instances/{id}

Stops the instance and removes it from the cluster. The Master dispatches a stop task to the owning Wrapper, which terminates the process and cleans up the working directory unless the configuration is static.

curl -X DELETE http://<master>:7000/api/instances/a1b2c3 \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "message": "Instance stopped",
  "instanceId": "a1b2c3"
}

Control the lifecycle

PATCH /api/instances/{id}/lifecycle?target=<start|stop|restart>

Changes the lifecycle of an existing instance without deleting its record. Use this to stop a running instance, start a stopped one, or restart in place.

curl -X PATCH "http://<master>:7000/api/instances/a1b2c3/lifecycle?target=restart" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "message": "Lifecycle change dispatched",
  "instanceId": "a1b2c3",
  "target": "restart"
}

Update instance state

PUT /api/instances/{id}/state

Updates the state and optional lastHeartbeat of an instance record directly. This is primarily used by Wrappers and tooling to report heartbeats; most operators should prefer the lifecycle endpoint above.

curl -X PUT http://<master>:7000/api/instances/a1b2c3/state \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"state": "ONLINE", "lastHeartbeat": 1718000123456}'

Returns the updated InstanceInfo with status 200 OK.

Execute a command on an instance

POST /api/instances/{id}/execute

Sends a command to the instance’s stdin. The command is piped directly into the running process (for example a Minecraft server console), so the syntax is whatever the process expects.

curl -X POST http://<master>:7000/api/instances/a1b2c3/execute \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command": "op andyreckt"}'

{
  "message": "Command dispatched",
  "instanceId": "a1b2c3",
  "command": "op andyreckt"
}

Fetch logs

GET /api/instances/{id}/logs?lines=<1-1000>

Returns the most recent log lines for an instance. Works with every runtime, including Docker, Kubernetes, screen, tmux, and bare processes.

curl "http://<master>:7000/api/instances/a1b2c3/logs?lines=100" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "lines": [
    "[12:00:01] [Server thread/INFO]: Starting minecraft server",
    "[12:00:04] [Server thread/INFO]: Done (3.1s)! For help, type \"help\""
  ],
  "totalLines": 2,
  "instanceId": "a1b2c3"
}

Related