---
module: technical.agent
title: HiveOps Agent — on-ATM Java monitoring agent
tab: Overview
order: 10
audience: dev
---

> **DRAFT · internal.** Written 2026-07-01 from hiveops-agent source. Verify against code before relying on specifics.

## Responsibility

The HiveOps Agent is a **Java client that runs on ATMs / servers**, not a Spring microservice. It parses journal files locally, uploads journal data + transaction images, reports structured events, and executes remote fleet-management commands (reboot, patch, file-collect, agent/module self-update). It is a multi-module Maven build (fat JAR via `maven-shade-plugin`) with **no REST controllers, no database, and no Kafka** — all integration is outbound HTTP to the `agent-proxy` / `incident` / `journal` services. See [platform.service-ownership].

Entry point: `com.hiveops.AgentApplication`. Module discovery is `ServiceLoader`-based (`com.hiveops.core.module.AgentModule` SPI) with lifecycle `initialize() → isEnabled() → start() → stop()`, topologically ordered by declared dependencies (`ModuleLoader` / `ModuleRegistry`).

## Data

**None.** The agent has no database and no ORM entities. State it needs to survive restarts is persisted locally to disk (e.g. `PersistantStateAndLog` for task state, per-file byte offsets for journal/applog readers). Fleet/journal/incident data lives in the backend services' own stores — see [platform.data-stores]. (Backend `hiveops-journal` reads env var `DB_URL`; the agent never touches it.)

## Kafka

**No Kafka.** The agent communicates only over HTTP(S). See [platform.kafka].

## API surface

The agent is an **HTTP client**, so this section lists the outbound endpoints it *calls* (base URLs from `agent.endpoint` / `journal.endpoint` / `incident.endpoint` in `hiveops.properties`). Paths are drawn from the HTTP client classes (`FileUploadClient`, `TransactionImageHttpClient`, `IncidentEventClient`, config/hardware sync + aria clients). Not exhaustive.

| Method | Path (relative to service base) | Purpose | Module / client |
|--------|--------------------------------|---------|-----------------|
| POST | `/api/journal-events` | Report parsed journal / app-log events | `journal-events` (`IncidentEventClient`) |
| POST | `/api/v1/agents/register` | Auto-register ATM on first contact | agent lifecycle |
| POST | `/api/v1/agents/heartbeat` | Periodic health / connection status | heartbeat |
| GET | `/api/v1/agents/poll` | Poll for pending fleet tasks | `command-processor` |
| GET/POST | `/api/v1/agents/commands/{...}` | Fetch / ack remote commands | `command-processor` |
| GET/POST | `/api/agent/tasks/{...}` | Fleet task detail / status update | `command-processor` |
| POST | `/api/agent/image/upload?atmName=&atmCountry=&datetime=&filename=&category=&orientation=` | Transaction image upload | `image-upload` |
| POST | `/api/agent/image/cheque/metadata?...` | Cheque image metadata | image (Gaia) |
| PUT/POST | `/api/agent/{country}/{atm}/transit?groupId=` | Report ATM transit | config-sync |
| POST | `/api/atms/config/sync` | Push ATM configuration | `atm-config-sync` |
| POST | `/api/atms/hardware/sync` | Push hardware inventory | `hw-inventory` |
| GET | `/api/atms/search?query=` | Resolve ATM id | `AtmIdResolver` |
| POST | `/api/aria/ingest/events`, `/api/aria/posture/report` | ARIA threat signals / posture | `aria-signals` |
| GET | `https://cdn.bcos.cloud/downloads/agent/latest.json` | Auto-update manifest poll | `auto-update` |

Legacy `/atm/image/*/v1` endpoints (`FileUploadClient`, `TransactionImageHttpClient`) remain for backward compatibility.

## Modules

Registered via `META-INF/services/com.hiveops.core.module.AgentModule`; disable through `modules.disabled` (comma-separated).

| Module (class) | Purpose |
|----------------|---------|
| `CommandProcessorModule` / `CommandCenterModule` | Poll + dispatch fleet tasks (`REBOOT`, `UPDATE`, `WINPATCH`, `FILECOLLECT`, `CCSUPPORT`, `RESTART_AGENT`, `UPDATE_AGENT`) |
| `AutoUpdateModule` / `ModuleAutoUpdateModule` | Self-update agent JAR / drop-in modules from CDN |
| `JournalUploadModule` | Chunked journal file upload |
| `JournalEventModule` | Parse journals → structured events → incident |
| `AppLogEventModule` | Monitor app logs for ERROR entries |
| `GenericImageUploadModule` / `GaiaImageUploadModule` | Transaction / cheque image upload |
| `LogUploadModule` / `LogMonitorModule` / `LogCollectPathModule` | Agent log upload + collection |
| `AtmConfigSyncModule` / `HardwareInventoryModule` | Config + hardware inventory sync |
| `EJournalDbMonitorModule` | Warn on Hyosung EJournal `.mdb` nearing 2 GB limit |
| `WinAppEventModule` | Windows application event monitoring |
| `NhTcrJournalModule` / `NhTcrEventsModule` / `TcrEventsModule` | TCR (teller cash recycler) journal + events |
| `ServerMonitorModule` | SRV installs: CPU/mem/disk/service monitoring |
| `AriaSignalModule` | ARIA threat-intelligence signals |
| `PacketCaptureModule` / `RemoteModule` | Packet capture / remote command execution |

## Platform abstraction

`com.hiveops.platform` — `PlatformServiceFactory` detects OS at runtime and returns Windows or Linux implementations of `ConfigurationReader`, `SystemCommands`, `PathResolver`, `SystemInfoProvider`. Windows reads config from the registry and runs `.cmd` scripts; Linux reads `/etc/hiveops/atm-config.properties` + `HIVEOPS_*` env vars and runs `.sh` scripts.

## Key config keys

From `hiveops-app/src/main/resources/hiveops.properties`:

| Key | Meaning |
|-----|---------|
| `agent.endpoint` | Base URL for fleet mgmt + heartbeat (default `https://api.bcos.cloud/incident`; replaces deprecated `server.endpoint`) |
| `journal.endpoint` | Journal upload/query base URL (separate service) |
| `incident.endpoint` | Deprecated fallback for events (older builds) |
| `agent.auth.token` | Bearer token (Incident → Settings → Agent Properties → Tokens); preferred auth |
| `agent.institution.key` | Legacy institution auth, used only if `agent.auth.token` unset |
| `agent.cdn.token` | Shared `X-CDN-Token` for `/downloads/agent/` + `/downloads/hotfix/` |
| `atm.id` / `country` / `atm.transit` | ATM identity (id resolution: property → `HIVEOPS_ATM_ID` → registry → hostname) |
| `heartbeat.interval` / `heartbeat.restart.threshold` | Heartbeat cadence; self-restart after N consecutive failures |
| `agent.update.enabled` / `agent.update.check.url` / `agent.update.window.start`/`end`/`timezone` | Auto-update toggle, manifest URL, after-hours window |
| `incident.events.enabled` / `.batch.size` / `.recheck.delay.msec` | Event reporting behavior |
| `applog.events.*` | App-log ERROR monitoring (dir, filename format, correlation) |
| `ejournal.db.monitor.*` | EJournal DB size warn/critical thresholds |
| `srv.monitor.*` | SRV-install CPU/mem/disk/service monitoring (ATMs leave `enabled=false`) |
| `modules.disabled` | Comma-separated modules to skip |

## Gotchas

- **Auth headers:** the agent sends `Authorization: Bearer <agent.auth.token>` when set, else legacy `X-Institution-Key`. Update downloads carry `X-CDN-Token`; there is also `X-ATM-Profile` and (internal) `X-Service-Secret`. Institution is auto-derived server-side from the token/key.
- **`agent.endpoint` vs `incident.endpoint`:** `agent.endpoint` is the current key; `incident.endpoint` and `server.endpoint` are deprecated fallbacks kept for older builds — don't rely on them for new work.
- **Token revocation kills module threads:** revoking `agent.auth.token` while ATMs still hold it kills their module threads and requires a manual JVM restart per machine. Push a fleet-wide `CONFIG_UPDATE` to clear the token and wait for tasks to drain *before* revoking.
- **ATM id resolution order matters:** property → `HIVEOPS_ATM_ID` env → Windows registry → hostname fallback; a mis-imaged box can silently take the wrong identity/institution.
- **`agent.update.enabled=false` customers** (e.g. ATEC Java 8 branch) get patches by hand via share.bcos.cloud, not CDN auto-update.
- **`hiveops-module-tcr-events` directory exists but is not a listed `<module>`** in the root `pom.xml` (the built TCR modules are `atec-tcr-events` / `nh-tcr-events`); treat the bare `tcr-events` dir as legacy. (unverified intent)
