> 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/agent/setting-up-the-agent.md).

# Setting Up the Agent

This guide covers configuring and starting the Rumi Agent for first-time use.

## Configuration Overview

The Agent requires two levels of configuration:

1. **Application configuration** (`config.xml`) — Defines the Agent as a Rumi AEP application, including messaging, heartbeat, and statistics settings.
2. **Agent properties** — Configure the REST API, telemetry storage, and embedded Controller behavior.

## Application Configuration

The Agent's `config.xml` defines:

### Messaging

Configure the messaging acceptor for receiving heartbeat data from running containers:

* The `nv.agent.acceptor` property specifies the messaging acceptor descriptor.
* The Agent listens on this acceptor for heartbeat messages from deployed containers.

### Heartbeat Collection

Configure what statistics are collected from container heartbeats:

* **Memory stats** — Entity counts, pool allocation, heap/non-heap usage.
* **Latency stats** — Messaging waypoint latencies, per-transaction samples.
* **Series stats** — Latency time-series data with configurable sample size.
* **Thread stats** — Per-thread metrics.
* **Pool stats** — Memory pool utilization.
* **GC stats** — Garbage collection counts and pause times.

The heartbeat interval (default: 5 seconds) determines how frequently containers emit telemetry data.

## Agent Properties

### REST API

| Property             | Description                  | Default |
| -------------------- | ---------------------------- | ------- |
| `nv.agent.http.port` | Port for the REST API server | 7778    |

The Agent starts an embedded Jetty server on this port, exposing the REST API documented in the [REST API Reference](/rumi-management/reference/agent/rest-api.md).

### Telemetry Storage

| Property               | Description                                         |
| ---------------------- | --------------------------------------------------- |
| `nv.agent.point.store` | Storage backend: `influx`, `fake_influx`, or `none` |
| `nv.agent.influx.url`  | InfluxDB connection URL                             |

See [Configuring Telemetry Storage](/rumi-management/guides/agent/configuring-telemetry-storage.md) for detailed InfluxDB setup.

### Embedded Controller

| Property                      | Description                             |
| ----------------------------- | --------------------------------------- |
| `nv.agent.controller.factory` | Controller implementation factory class |
| `nv.agent.jvm.params`         | JVM parameters for the embedded runtime |

## Connecting Containers

For the Agent to receive heartbeats from running containers, the containers must be configured to send heartbeat data to the Agent's messaging acceptor. This is typically configured in the system's DDL model or the container's discovery configuration.

## API Documentation

The Agent auto-generates an OpenAPI/Swagger specification at build time. The API specification is available at:

```
target/classes/META-INF/openAPI/rumi-agent-api.yaml
```

This can be used with Swagger UI or other OpenAPI tools for interactive API exploration.