2026-05-16 19:36:43 +02:00
|
|
|
### 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.
|
2026-05-17 23:42:52 +02:00
|
|
|
- **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.
|
2026-05-16 19:36:43 +02:00
|
|
|
|
|
|
|
|
#### 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.
|
