Cluster nodes

Cluster nodes is the control surface for trusted internal nodes in a multi-node Callaba deployment. Teams use it when one engine should act as the primary control point, when a child node should join the fleet, or when a node should be disabled cleanly without guessing what still depends on it.

This module is about safe topology management in production. It helps operators decide which nodes should participate, how they should trust each other, and how to attach or detach a node without turning the cluster relationship into tribal knowledge.

The most important production rule is simple: these nodes are internal infrastructure. The dashboard itself warns against using public IP addresses here, because the goal is a stable internal node mesh, not an exposed internet-facing control path.

Examples by preset

The useful presets here follow real fleet roles: a primary control node, a connected slave node that uses a child-node token, and a test node for validation or rehearsal before a broader rollout.

{
  "name": "Primary cluster node",
  "host": "10.20.0.10",
  "node_type": "CLUSTER_NODES_TYPE_MASTER",
  "active": true
}
{
  "name": "Istanbul slave node",
  "host": "10.20.0.25",
  "node_type": "CLUSTER_NODES_TYPE_SLAVE",
  "api_token": "<child_node_jwt_token>",
  "active": true
}

Workflow examples

Bring a child node into the trusted internal fleet

Use the create flow for a slave node when another machine should participate as part of the same operational system rather than as an unrelated standalone instance.

Detach a node before maintenance or network changes

Use detachNode, stop, or remove when a node must be taken out of service cleanly before maintenance, relocation, or topology changes.

Keep test capacity separate from production control nodes

Use a dedicated test-node role when a team needs safe validation capacity without blurring the line between production ownership and experimentation.

Create cluster node
Collapse
POST
/api/clusterNodes/create

Use this method to register a new internal node in the cluster. In production, the create call matters when the fleet is expanding, when a child node should become part of the trusted topology, or when a clean test node should be prepared ahead of a rollout.

For slave nodes, the child-node API token is part of that trust handshake. The dashboard also warns the operator not to use a public IP here because this relationship is intended for internal infrastructure.

Primary control node

Use this when one internal node should act as the main coordination point for the cluster and the rest of the fleet should align around it.

Primary control node
curl --request POST \
  --url http://localhost/api/clusterNodes/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Primary cluster node",
  "host": "10.20.0.10",
  "node_type": "CLUSTER_NODES_TYPE_MASTER",
  "active": true
}'
Connected slave node

Use this when a child node should join the trusted internal fleet and needs the child-node API token so attachment can succeed cleanly.

Connected slave node
curl --request POST \
  --url http://localhost/api/clusterNodes/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Istanbul slave node",
  "host": "10.20.0.25",
  "node_type": "CLUSTER_NODES_TYPE_SLAVE",
  "api_token": "<child_node_jwt_token>",
  "active": true
}'
Test or validation node

Use this when a node should be provisioned for validation, rehearsal, or isolated checks before it becomes part of a production path.

Test or validation node
curl --request POST \
  --url http://localhost/api/clusterNodes/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Test validation node",
  "host": "10.20.0.40",
  "node_type": "CLUSTER_NODES_TYPE_TEST",
  "active": false
}'
Request body parameters
Identity
name
string

Dashboard label: Node name.

Human-readable internal node name.

node_type
string

Dashboard label: Type.

Real product values are CLUSTER_NODES_TYPE_MASTER, CLUSTER_NODES_TYPE_SLAVE, and CLUSTER_NODES_TYPE_TEST.

Connectivity
host
string

Dashboard label: Host.

Internal node address. The dashboard warns operators not to use a public IP here.

Trust
api_token
string

Dashboard label: API token.

Child-node JWT token used for slave-node attachment flows. It is only relevant when the node type is CLUSTER_NODES_TYPE_SLAVE.

Runtime
active
boolean

Dashboard label: Enabled.

Controls whether the node should be active right after provisioning.

Create cluster node
curl --request POST \
  --url http://localhost/api/clusterNodes/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Istanbul slave node",
  "host": "10.20.0.25",
  "node_type": "CLUSTER_NODES_TYPE_SLAVE",
  "api_token": "<child_node_jwt_token>",
  "active": true
}'
Response
success
boolean

The create call confirms acceptance with a success-shaped response.

Response: Create cluster node
JSON
{
  "success": true
}
Get cluster nodes count
Expand
POST
/api/clusterNodes/getCount

Use this method when the UI or an operator needs a quick count of registered cluster nodes without loading the full list.

Request body parameters
This method has no parameters
Get cluster nodes count
curl --request POST \
  --url http://localhost/api/clusterNodes/getCount \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
Response
count
integer

Total number of registered cluster nodes currently visible to the authenticated user.

Response: Get cluster nodes count
JSON
{
  "count": 2
}
Get all cluster nodes
Expand
POST
/api/clusterNodes/getAll

Use this method to list the current cluster topology that the instance knows about. It is the fastest way to confirm which nodes are registered, which role each node has, and whether the fleet view still matches the intended production layout.

Request body parameters
limit
integer

Optional page size for the node list.

skip
integer

Optional offset for paginated listing.

sort
object

Optional sort descriptor. The dashboard store uses { created: 1 } by default.

Get all cluster nodes
curl --request POST \
  --url http://localhost/api/clusterNodes/getAll \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "sort": {
    "created": 1
  },
  "limit": 20,
  "skip": 0
}'
Response
array of cluster node objects
array

The backend returns the known cluster nodes as a bare array of node objects.

Response: Get all cluster nodes
JSON
[
  {
    "_id": "681300000000000000000001",
    "id": "681300000000000000000001",
    "name": "Istanbul slave node",
    "host": "10.20.0.25",
    "node_type": "CLUSTER_NODES_TYPE_SLAVE",
    "active": true,
    "created": "2026-03-24T19:00:00.000Z",
    "modified": "2026-03-24T19:00:00.000Z",
    "success": true
  }
]
Get cluster node by id
Expand
POST
/api/clusterNodes/getById

Use this method when one node needs to be inspected or edited in full, especially before attachment, detachment, or a role change.

Request body parameters
id
string

Identifier of the node you want to inspect.

Get cluster node by id
curl --request POST \
  --url http://localhost/api/clusterNodes/getById \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "681300000000000000000001"
}'
Response
cluster node object
object

The backend returns the stored node fields for the requested id.

Response: Get cluster node by id
JSON
{
  "_id": "681300000000000000000001",
  "id": "681300000000000000000001",
  "name": "Istanbul slave node",
  "host": "10.20.0.25",
  "node_type": "CLUSTER_NODES_TYPE_SLAVE",
  "active": true,
  "created": "2026-03-24T19:00:00.000Z",
  "modified": "2026-03-24T19:00:00.000Z",
  "success": true
}
Update cluster node
Expand
POST
/api/clusterNodes/update

Use this method when a node host, role, token, or activation state must be corrected without recreating the node from scratch.

Request body parameters
id
string

Identifier of the cluster node being updated.

node payload fields
mixed

The update contract mirrors create and reuses the same host, type, token, and activation fields.

Update cluster node
curl --request POST \
  --url http://localhost/api/clusterNodes/update \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "681300000000000000000001",
  "name": "Istanbul slave node updated",
  "host": "10.20.0.26",
  "node_type": "CLUSTER_NODES_TYPE_SLAVE",
  "api_token": "<child_node_jwt_token>",
  "active": true
}'
Response
success
boolean

The backend confirms that the node update was accepted.

Response: Update cluster node
JSON
{
  "success": true
}
Start cluster node
Expand
POST
/api/clusterNodes/start

Use this method when a registered node should return to active service after maintenance, validation, or a planned pause.

Request body parameters
id
string

Identifier of the node to activate.

Start cluster node
curl --request POST \
  --url http://localhost/api/clusterNodes/start \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "681300000000000000000001"
}'
Response
success
boolean

The backend confirms that the node was enabled successfully.

Response: Start cluster node
JSON
{
  "success": true
}
Stop cluster node
Expand
POST
/api/clusterNodes/stop

Use this method when a node should remain registered but should no longer participate in the active cluster until the team is ready to bring it back.

Request body parameters
id
string

Identifier of the node to disable.

Stop cluster node
curl --request POST \
  --url http://localhost/api/clusterNodes/stop \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "681300000000000000000001"
}'
Response
success
boolean

The backend confirms that the node was disabled successfully.

Response: Stop cluster node
JSON
{
  "success": true
}
Attach cluster node
Expand
POST
/api/clusterNodes/attachNode

Use this method when a registered node should be attached into the active cluster relationship and treated as part of the current trusted topology.

Request body parameters
id
string

Identifier of the node that should be attached into the active cluster relationship.

Attach cluster node
curl --request POST \
  --url http://localhost/api/clusterNodes/attachNode \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "681300000000000000000001"
}'
Response
success
boolean

The backend confirms that the node attachment step completed successfully.

Response: Attach cluster node
JSON
{
  "success": true
}
Detach cluster node
Expand
POST
/api/clusterNodes/detachNode

Use this method when a node should stay registered for reference but must be detached from the active cluster relationship before maintenance, testing, or removal.

Request body parameters
id
string

Identifier of the node that should be detached from the active cluster relationship.

Detach cluster node
curl --request POST \
  --url http://localhost/api/clusterNodes/detachNode \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "681300000000000000000001"
}'
Response
success
boolean

The backend confirms that the node detachment step completed successfully.

Response: Detach cluster node
JSON
{
  "success": true
}
Remove cluster node
Expand
DELETE
/api/clusterNodes/remove

Use this method when a node relationship should be removed entirely from the cluster inventory rather than merely paused.

Query parameters
id
string

Identifier of the node to remove.

Remove cluster node
curl --request DELETE \
  --url http://localhost/api/clusterNodes/remove \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "681300000000000000000001"
}'
Response
success
boolean

The backend confirms that the node was removed successfully.

Response: Remove cluster node
JSON
{
  "success": true
}
Back toPortsNext toAdditional utilities