> 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/overview.md).

# Overview

Rumi Management is the centralized deployment, administration, command-and-control, and monitoring subsystem of the Rumi platform. It provides the tooling needed to deploy, operate, and observe Rumi applications across distributed environments.

<details>

<summary>Rumi terminology used in this section</summary>

The first three terms below are [Rumi Core](/rumi-core/core.md) concepts (defined in detail there). The last — **System** — is specific to Rumi Management.

| Term                                          | Meaning                                                                                                                                                                                                                   |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Service** (also **Engine**, **AEP Engine**) | A Rumi microservice — a lightweight, stateful, fault-tolerant, horizontally scalable message processor.                                                                                                                   |
| **Container**                                 | A Rumi runtime that hosts one or more services. Provides service lifecycle management, telemetry collection, and command-and-control.                                                                                     |
| **Application**                               | A system of cooperating Rumi services — the distributed application as a whole.                                                                                                                                           |
| **System**                                    | The unit of deployment in Rumi Management. Defined by a DDL describing containers, the services they host, and how they're wired together. See [Deployment Lifecycle](/rumi-management/concepts/deployment-lifecycle.md). |

</details>

Rumi Management comprises four components:

* **Rumi Controller** — the core engine: maintains a live deployment model, runs deployment scripts, performs command-and-control, and forwards container telemetry. Runs standalone or embedded in the Agent.
* **Rumi Agent** — wraps the embedded Controller with a REST API and a telemetry pipeline that writes to a time-series database.
* **Rumi Admin** — a web UI for visual deployment, administration, and command-and-control, driving one or more Agents over REST.
* **Rumi Monitor** — a Grafana fork bundled with Rumi dashboards for visualizing container, application, and host metrics.

Each component is independently useful — the Controller can be run standalone for scripted deployments, the Agent can be used without the Admin for REST-driven automation, and the full stack can be deployed when a visual console is needed.

## Rumi Controller

The Controller is the core engine of Rumi Management. It provides:

* **Deployment model** — an in-memory model of discovered containers, the services they host, and the state of their bus connections. Built and maintained from lifecycle events emitted by containers, and queryable by any embedder.
* **Scripted deployment** — a script DSL (with an interactive alternative for stepwise execution) for orchestrating the end-to-end deployment lifecycle of Rumi containers and the services they host.
* **Command and control** — scripted and ad-hoc command-and-control of Rumi containers and the applications they host.
* **Telemetry forwarding** — periodic container telemetry received via heartbeats and forwarded to registered listeners for metrics collection.

The Controller can be **installed and used standalone** — for running deployment scripts, executing ad-hoc command-and-control, querying the live deployment model, or tailing the telemetry stream — or **embedded programmatically** into custom management applications, as Rumi Agent itself does.

## Rumi Agent

The Agent wraps the embedded Controller and exposes its capabilities over a REST API. It adds:

* **REST API for deployment administration** comprised of script execution and ad-hoc command-and-control, along with read access to the embedded Controller's deployment model. The REST API is fully usable on its own — Rumi Admin is not required.
* **Telemetry pipeline** that funnels telemetry forwarded by the embedded Controller into a time-series database (InfluxDB) for dashboarding and alerting.
* **Pluggable collectors** for extending default telemetry with custom metrics.

In addition to the REST API, an Agent installation also exposes the embedded Controller's CLI, providing the same command-line script-execution and ad-hoc command-and-control capabilities as a standalone Controller install.

The Agent operates in one of two telemetry modes:

* **Session mode** (default) — the Agent's embedded Controller establishes a session with each discovered container. Heartbeats received over each session feed the telemetry pipeline; lifecycle events feed the deployment model.
* **Passive mode** — the Agent subscribes to a shared monitoring bus and receives heartbeats directly from the bus. The deployment model is not maintained in this mode.

## Rumi Admin

Rumi Admin is a web application that provides a visual interface for centralized deployment, administration, and command-and-control. It communicates with one or more Rumi Agents over their REST APIs to:

* Deploy and manage Rumi systems across environments.
* Execute deployment scripts and issue ad-hoc commands.
* View system status and manage container lifecycle.

## Rumi Monitor

Rumi Monitor is a Grafana fork bundled with Rumi dashboards for visually monitoring the health and performance of Rumi applications. Bundled dashboards cover:

* **Container statistics** — memory, latency, throughput, GC, and thread metrics per container.
* **Service statistics** — per-service metrics, comprising AEP engine statistics (message throughput, processing latencies, queue depths, transaction rates) and application-defined statistics (custom gauges, counters, and latency series emitted by the service through the Rumi telemetry pipeline).
* **Host statistics** — CPU, memory, and disk utilization per host.

InfluxDB-native dashboards are planned as an additional viewing option.

## Usage Modes

The components are designed to compose flexibly. Common configurations include:

| Mode                         | Components              | Use Case                                                   |
| ---------------------------- | ----------------------- | ---------------------------------------------------------- |
| **Standalone scripting**     | Controller              | Scripted deployments, CI/CD integration                    |
| **Embedded programmatic**    | Controller              | Custom management applications with programmatic control   |
| **REST-driven automation**   | Agent                   | REST-driven deployment and command-and-control, no UI      |
| **Headless with monitoring** | Agent + Monitor         | Automated deployments with telemetry and dashboards        |
| **Full stack**               | Agent + Admin + Monitor | Complete visual deployment, administration, and monitoring |