---
okf: "0.1"
type: subsystem
visibility: private
status: active
updated: 2026-05-17
links: []
---

### Agent System
Central runtime materializer and Operator Control Plane UI.

#### Components
- **Redis**: Central state store (on PIHA).
- **Runtime Materializer**: Converts Redis state to JSON files in `/opt/homelab/world`.
- **Web UI**: Exposes API endpoints and serving the Operator UI.
- **Telegram Bot**: Provides operator commands and action approvals via Telegram.

#### Configuration
Environment variables should be set in `.env` (see `env.example`).
Key variables for the Telegram Bot:
- `TELEGRAM_BOT_TOKEN`: Your bot token from @BotFather.
- `TELEGRAM_ALLOWED_USER_IDS`: Comma-separated list of authorized Telegram User IDs.
- `CONTROL_PLANE_URL`: URL to the `agent-system-webui` (default: `http://webui:8080`).

#### Telegram Commands
- `/status`: Check bot and API connectivity.
- `/summary`: System health overview.
- `/nodes`: List homelab nodes and their status.
- `/services`: Summary of services across nodes.
- `/unhealthy`: List all unhealthy components.
- `/incidents`: View active incidents.
- `/actions`: Summary of operator actions.
- `/help`: List all commands.

#### Deployment (on PIHA)
```bash
cd services/agent-system
./deploy.sh
```

#### Deployment (on CHELSTY)
```bash
cd services/stability-agent
docker compose up -d --build
```

#### Verification
The `deploy.sh` script automatically verifies the local endpoints.
You can also manually check:
```bash
# Check runtime summary
curl http://localhost:18180/summary

# Check discovered nodes
curl http://localhost:18180/nodes

# Check discovered services
curl http://localhost:18180/services
```

#### Directory Structure
- `/opt/homelab/world`: Contains materialized JSON state.
- `/opt/homelab/state`: Contains operator configuration and local heartbeats.
