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.