> 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/guides/controller/embedding-the-controller.md).

# Embedding the Controller

This guide covers using the Rumi Controller programmatically within custom management applications.

## Overview

The Controller can be embedded into Java applications for programmatic deployment and lifecycle management. This is how the Rumi Agent uses the Controller internally — it instantiates a Controller instance and invokes operations through its Java API rather than through scripts.

## Use Cases

Embedding the Controller is useful when:

* Building custom management tooling with application-specific workflows.
* Integrating Rumi deployment into CI/CD pipelines programmatically.
* Creating automated test harnesses that deploy and manage systems.
* Implementing custom orchestration logic that goes beyond what deployment scripts offer.

## Integration Pattern

The Controller is integrated through the `RumiControllerFactory` pattern:

1. **Instantiate** a Controller via the factory.
2. **Discover** available systems and their scripts.
3. **Execute** commands against systems (script invocations, ad-hoc commands).
4. **Query** system state and container status.

The Agent uses this pattern through the `ControllerProvider` dependency injection interface, which allows the Controller implementation to be swapped (configured via `nv.agent.controller.factory`).

## Configuration

When embedding the Controller, configure it via the standard `controller.conf` properties or programmatically:

| Property                    | Description               |
| --------------------------- | ------------------------- |
| `RUMI_CONTROLLER_HOME`      | Controller home directory |
| `RUMI_CONTROLLER_CONF`      | Path to `controller.conf` |
| `nv.controller.systemsroot` | Systems directory         |

## System and Script Discovery

The embedded Controller provides methods to:

* List available systems.
* List scripts within a system, including their metadata (parameters, descriptions).
* Query container state within a system.

Script metadata includes parameter definitions (`ScriptParamMetadata`) with types (`ScriptArgumentType`), enabling dynamic UI generation or validation in custom tooling.

## Example: Agent Integration

The Rumi Agent demonstrates the canonical embedding pattern:

1. The Agent's Guice module binds a `ControllerProvider`.
2. The `RumiControllerFactory` creates and configures the Controller instance.
3. The `ExecutionManager` wraps Controller invocations with serialization and audit tracking.
4. REST endpoints delegate to the Controller through the execution manager.

This pattern ensures that programmatic invocations have the same execution semantics (one-at-a-time, audited, cancellable) as script-based invocations.