Orchestration

Run a fleet of MiroxOS edge nodes as a single, self-healing cluster at your plant, with every node moving through a guarded state machine so a device can never end up in an invalid or half-configured state.

Overview

Standing up an edge cluster is a coordinated handshake between actions you run on the device and actions Mirox staff perform in the cloud. Each node advances through a strict state machine, and every transition checks its prerequisites first — so you cannot, for example, tear a node out of a park while it is still serving a live cluster. When a device falls behind the cloud (for instance after a forced cleanup while it was offline), a single sync command reconciles it.

State Machine

Device State Diagram

Legend:

Solid arrows: Normal transitions (run on the device or by an organization administrator)
Dashed arrows: Forced transitions performed by Mirox staff, with automatic cleanup
Locked to park Edge cluster running Sync point

Forced Transition Behavior

When Mirox staff use the force option, all intermediate cleanups run automatically:

Forced Action	Auto-executes
Delete device (from CLUSTER_ACTIVE)	leave cluster → node deinit → unassign park → unassign org → unregister
Delete device (from NODE_INITIALIZED)	node deinit → unassign park → unassign org → unregister
Unassign from org (from NODE_INITIALIZED)	node deinit → unassign park → unassign org
Unassign from park (from NODE_INITIALIZED)	node deinit → unassign park

Device Sync

The device can run mrxcloud sync to fetch the current cloud state and reconcile its local configuration:

If the device was forcefully unassigned from the park → local node config is cleared
If the device was forcefully unassigned from the organization → local org config is cleared
If the device was forcefully deleted → the device must re-register

Cluster State Diagram

Legend:

Solid arrows: Normal transitions
Dashed arrows: Forced transitions performed by Mirox staff
Waiting for nodes Cluster operational

Device States

State	Description	Next Allowed States
`UNREGISTERED`	Device is not registered with any cloud	`REGISTERED`
`REGISTERED`	Device is registered with cloud	`ASSIGNED_ORG`, `UNREGISTERED`
`ASSIGNED_ORG`	Device is assigned to an organization	`ASSIGNED_PARK`, `REGISTERED`
`ASSIGNED_PARK`	Device is assigned to a park	`NODE_INITIALIZED`, `ASSIGNED_ORG`
`NODE_INITIALIZED`	Device is initialized as edge node	`CLUSTER_ACTIVE`, `ASSIGNED_PARK`
`CLUSTER_ACTIVE`	Edge cluster is running on device	`NODE_INITIALIZED`

Cluster States

State	Description
`NOT_CREATED`	No edge cluster exists for park
`CREATED`	Edge cluster created, waiting for nodes
`ACTIVE`	At least one node has joined

Workflow Steps

Forward Flow (Setup)

Step	Action	Actor	Tool	Prerequisite
1	Register device	Device	`mrxcloud register`	-
2	Assign to organization	Mirox staff	Cloud	Step 1
3	Assign to park	Organization administrator	Cloud	Step 2
4	Create edge cluster	Mirox staff	Cloud	Step 3 (park exists)
5	Initialize node	Device	`mrxcloud node init`	Steps 3 + 4
6	Initialize cluster	Device	`mrxnode init`	Step 5
7	Deploy workloads	Device	`mrxnode bootstrap`	Step 6

Backward Flow (Teardown)

Step	Action	Actor	Tool	Prerequisite
7	Stop workloads	Device	`mrxnode teardown`	-
6	Leave cluster	Device	`mrxnode leave`	Step 7
5	De-initialize node	Device	`mrxcloud node deinit`	Step 6
4	Delete edge cluster	Mirox staff	Cloud	No active nodes
3	Unassign from park	Organization administrator	Cloud	Step 5 (node de-initialized)
2	Unassign from org	Mirox staff	Cloud	Step 3
1	Unregister device	Device	`mrxcloud unregister`	Step 2

Locking Constraints

Park Assignment Lock

When a device is initialized as an edge node (Step 5), the device becomes locked to the park:

Action	Allowed When	Blocked When
Unassign device from park	Node NOT initialized	Node initialized
Unassign device from org	Device NOT assigned to park	Device assigned to park
Delete edge cluster	No nodes initialized	Any node initialized

Enforcement Matrix

Each action is refused while a lock is active, unless it is run with the force flag — in which case the platform performs every intermediate cleanup for you:

Action	Without Force	With Force
Unassign device from park	Refused while the device is an initialized node	Auto node deinit, then unassign
Unassign device from organization	Refused while the device is assigned to a park	Auto unassign park (and node deinit if needed)
Delete device	Refused while the device has any assignments	Auto full cleanup chain
Delete edge cluster	Refused while any nodes are initialized	Auto deinit all nodes, then delete
Initialize node (`mrxcloud node init`)	Requires the device be assigned to a park with an edge cluster	-
Leave cluster (`mrxcloud node deinit`)	Requires the device to currently hold a node number	-

Command Reference

Device-Side Commands (mrxcloud)

Command	Description
`mrxcloud register <domain>`	Register the device with the cloud
`mrxcloud unregister`	Unregister the device
`mrxcloud sync`	Fetch and reconcile the current cloud state
`mrxcloud node init`	Initialize the device as an edge node
`mrxcloud node deinit`	De-initialize the node from the cluster
`mrxcloud node info`	Show the device's node configuration

Device-Side Commands (mrxnode)

Command	Description
`mrxnode init`	Start the edge cluster (first node) or join an existing one
`mrxnode leave`	Leave the edge cluster
`mrxnode bootstrap`	Deploy the plant's workloads onto the cluster
`mrxnode teardown`	Stop and remove the deployed workloads
`mrxnode check`	Check the cluster status

Cloud-Side Actions

These steps are performed in the cloud rather than on the device. Assigning a device to a park and managing it within the park is available to your organization administrators; registering or assigning a device to an organization, and creating or deleting the edge cluster itself, are performed by Mirox staff.

Action	Performed By	With Force
Assign device to organization	Mirox staff	-
Unassign device from organization	Mirox staff	Auto unassign park + node deinit
Delete device	Mirox staff	Auto full cleanup chain
Assign / unassign device to a park	Organization administrator	Auto node deinit on unassign
Create edge cluster for a park	Mirox staff	-
Delete edge cluster	Mirox staff	Auto deinit all nodes

State Verification

Check Current State

# On device: check registration and node status
mrxcloud status
mrxcloud node info

# Check the edge cluster status
mrxnode check

State Indicators

mrxcloud node info reports the device's current node configuration:

Indicator	Meaning
`edge_location`	Park UID this device serves as a node
`edge_node_number`	Assigned node number (1, 2, 3...)
`private_ip`	Node's private network IP within the cluster
`token_to_join`	Cluster join token used by additional nodes

Error Handling

Common Errors

Error	Cause	Resolution
"Device is not assigned to a park"	Step 3 not completed	Assign the device to a park in the cloud
"No edge cluster exists for park"	Step 4 not completed	Have the edge cluster created in the cloud
"Cannot unassign: device is initialized as edge node"	Step 5 completed, lock active	Run `mrxcloud node deinit`, or use the force option
"Cannot delete cluster: active nodes exist"	Nodes still initialized	De-initialize all nodes, or use the force option
"Cannot unassign from org: device assigned to park"	Device still in park	Unassign from the park first, or use the force option
"State mismatch: device was forcefully modified"	Cloud state changed while the device was offline	Run `mrxcloud sync` to reconcile

mrxnode — the edge hardware node that runs as part of the cluster
mrxnode Overview — device setup, registration, and CLI walkthrough
mrxnode Cheatsheet — quick reference for the mrxcloud and mrxnode commands
Troubleshooting — recovery patterns when a node misbehaves
Agent Deployment Options — on-site edge clusters versus cloud-hosted agents