> For the complete documentation index, see [llms.txt](https://docs.rumi.systems/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rumi.systems/rumi-management/concepts/command-and-control.md).

# Command and Control

Rumi Management provides both scripted and ad-hoc command-and-control capabilities for deploying and operating Rumi applications.

## Script-Based Operations

The Controller implements a **script DSL** for automating deployment and lifecycle operations. Scripts are defined as part of a system's XAR and specify a sequence of commands to execute against the system's containers.

### Script Commands

Scripts are composed of commands that operate on containers within a system. The available commands include:

| Command       | Purpose                                                                    |
| ------------- | -------------------------------------------------------------------------- |
| **provision** | Prepare containers on target hosts (copy distribution, set up directories) |
| **launch**    | Start container JVM processes                                              |
| **start**     | Start microservices within containers                                      |
| **stop**      | Gracefully stop microservices                                              |
| **shutdown**  | Terminate container JVM processes                                          |
| **configure** | Apply runtime configuration changes                                        |
| **deploy**    | Install application modules into running containers                        |
| **collect**   | Gather runtime statistics from containers                                  |
| **instruct**  | Send control messages to applications                                      |
| **validate**  | Verify system state meets expected conditions                              |
| **wait**      | Pause script execution for synchronization                                 |
| **cleanup**   | Remove provisioned files from target hosts                                 |

Commands can target individual containers by name or all containers in the system.

### Script Execution

Scripts can be executed in several ways:

* **Controller standalone** — Run directly from the command line.
* **Agent REST API** — Invoke via the `POST /invoke/script` endpoint.
* **Admin UI** — Select and execute from the web dashboard.

The Agent serializes script execution — only one script or command can run at a time. Each execution is tracked with a UUID and recorded in an audit trail with status (Pending, Running, Success, or Aborted).

A running script can be cancelled via the Agent's `POST /invoke/cancel` endpoint.

### Script Parameters

Scripts support parameterization for values that vary across environments. Parameters are resolved at execution time, allowing the same script to be used across development, staging, and production environments.

## Ad-Hoc Operations

In addition to scripts, Rumi Management supports ad-hoc operations for interactive administration and troubleshooting:

### Application Commands

Application commands are operations defined by the application code itself (via Rumi Core's command-and-control annotations). They allow operators to interact with running microservices — for example, to query state, trigger actions, or change runtime behavior.

Application commands are:

* Discovered dynamically from the deployed system.
* Invoked via the Agent REST API (`POST /app/command/invoke`) or from the Admin UI.
* Executed against specific applications within specific containers.

### Administration

The Controller provides administration capabilities for managing running containers:

* Querying container state and health.
* Modifying runtime configuration.
* Sending administrative instructions to microservices.

Administration messages are delivered over Rumi messaging (SMA), providing a reliable communication path to running applications regardless of host location.

## Execution Model

The Agent's execution model enforces ordered execution to prevent conflicting operations:

1. Script and command invocations are submitted to an **ExecutionManager**.
2. The ExecutionManager uses a **one-at-a-time executor** — only one invocation runs at any moment.
3. Each invocation is assigned a UUID for tracking.
4. An **audit record** is created for each invocation, tracking its status through the lifecycle:
   * **Pending** — Queued for execution
   * **Running** — Currently executing
   * **Success** — Completed successfully
   * **Aborted** — Cancelled or failed (with error classification: aborted before execution or during execution)