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


---

# 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:

```
GET https://docs.rumi.systems/rumi-management/overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.