> 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)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.rumi.systems/rumi-management/concepts/command-and-control.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.