Entity: Hermes Agent (AI Agent Service)

This page is the repository hub for the Hermes Agent Proxmox LXC deployment.

Overview

Hermes Agent is deployed as a “cattle” container (CT 105) on Proxmox, with a “pet” container (CT 999, protection=1) that owns a persistent 10G LVM-thin volume (local-lvm:vm-999-disk-1). The volume is attached/detached via API on stop/start cycles. Data survives destroy/recreate of CT 105 because ownership is tied to CT 999. This Pet vs Cattle pattern is the only way to achieve PVC-like persistence on LVM-thin with API token access on Proxmox 9.1.

The deployment follows the same enterprise lifecycle pattern as the Hetzner Vault runtime (Terraform + Ansible + timed orchestrator), living under ephemeral-castle/hermes/.

Repository Structure

ephemeral-castle/hermes/
├── create.sh              # 8-phase orchestrator (Pet Ensure → Terraform → Attach → Ansible) with structured logging
├── destroy.sh             # Stop → API detach volume → Terraform destroy (volume preserved on CT 999)
├── cycle.sh               # Full destroy/create cycle with timed phases
├── HANDOFF.md             # Project state and handoff documentation
├── configs/
│   └── runtime.env        # CT 105 ID, IP, hostname, resources, template
├── terraform/
│   ├── main.tf            # CT 105 resource (NO mount_point — volume managed via API)
│   ├── variables.tf       # CT parameters
│   └── outputs.tf         # Ansible inventory + runtime env generation
├── terraform-pet/         # Independent state for CT 999 (pet)
│   └── main.tf            # CT 999 with protection=1, owns the 10G persistent volume
├── ansible/
│   ├── ansible.cfg        # SSH keepalive (30s interval)
│   ├── roles/
│   │   ├── baseline/      # System packages, hermes user, SSH keys
│   │   ├── agent/         # Hermes install (skipped if already present on persistent volume)
│   │   ├── configure/     # Config.yaml, SOUL.md, .env, service enable
│   │   └── verify/        # Port check, process check
│   └── hermes-*.yml       # 4 playbooks (baseline, agent, configure, verify)
└── logs/                   # Timestamped create/destroy logs

Quick Facts

Canonical Starting Pages for Agents

Deployment & Lifecycle

• LXC Deployment Architecture — Pet vs Cattle pattern, design decisions, storage architecture, API calls

Research Assets (in AGENTS.ctx/crisp-build/assets/)

• research-hermes-persistence-prompt.md — Initial research prompt
• research-hermes-enterprise.md — Enterprise approaches (API, ZFS, Terraform)
• research-hermes-lvm-persistence-deep.md — Deep dive on LVM-thin ownership
• Persistenza Dati LXC su Proxmox.md — Research result 1: API syntax, ZFS comparison
• Persistenza Volumi LVM-thin Proxmox.md — Research result 2: LVM ownership, Terraform lifecycle
• Proxmox LXC Volume Persistenza API.md — Research result 3: Final analysis with Pet vs Cattle solution

Relationships

• Infrastructure layer: ephemeral-castle — Hermes lives inside this repository
• GitOps cluster: tazlab-k8s — Hermes talks to the cluster via opencode-go
• Pet container: CT 999 — owns the persistent volume, managed via separate terraform-pet/ state

See Also

• Wiki Index