replica-omnisciente/experiments/hermes-launch/AGENTS.md

Agent Runbook — Hermes Launch Workspace

Agent-specific notes for working in /home/fcunha/portugalfuturista/replica/experiments/hermes-launch/.

What this workspace is

Hackathon submission for Portugal Futurista Aurelio × Hermes (Nous Research / NVIDIA / Stripe). It wires a single Hermes agent to the Olhos-de-Orpheu MCP gateway, which in turn routes physical-device calls to a mesh of Hardware Lab Nodes.

Directory layout

.
├── README.md                          # Human-facing overview and quick start
├── AGENTS.md                          # This file
├── .env.example                       # Template for API keys and endpoints
├── pyproject.toml                     # Python package metadata
├── server.py                          # Local MCP aggregator (fallback/proxy)
├── demo.py                            # Alentejo cooperative demo
├── hardware_lab_node/                 # FastMCP SSE server for bench hardware
│   ├── server.py                      # Entry point
│   ├── discovery.py                   # USB/udev device discovery
│   ├── adapters/                      # ESP32, PPK2, generic serial, Xgecu
│   ├── launcher.sh                    # ASUS/Proxmox node launcher
│   └── aurelio-lab-node-asus.service  # systemd unit for asus-server
├── skills/                            # Python skills called by tools
├── scripts/
│   ├── setup_hermes.py                # Writes ~/.hermes/config.yaml
│   ├── olhos_de_orpheu_mcp.py         # stdio fallback wrapper
│   ├── run_bench_lab_node.sh          # Start bench-lab node
│   └── test_lab_node_client.py        # SSE node smoke client
├── tests/test_smoke.py                # pytest smoke tests
└── orchestrator/                      # Parallel Kimi sub-agent queue
    ├── orchestrator.py
    ├── tasks.json
    └── state.json

Core endpoints

Service	URL / location
Olhos-de-Orpheu gateway	http://192.168.0.16:8001/sse (Proxmox CT 206)
bench-lab node	http://192.168.0.88:8002/sse (local laptop, ESP32-S3 on /dev/ttyACM1)
asus-server node	http://192.168.0.38:8002/sse (Proxmox host, PPK2 / logic analyzer / printers)

How to start lab nodes

bench-lab (local laptop)

cd /home/fcunha/portugalfuturista/replica/experiments/hermes-launch
source .venv/bin/activate
scripts/run_bench_lab_node.sh

asus-server (Proxmox host)

The node is deployed under /opt/aurelio-lab-node-asus/ on 192.168.0.38:

ssh root@192.168.0.38
sudo systemctl enable --now aurelio-lab-node-asus

To update remote source from this workspace, copy hardware_lab_node/ to /opt/aurelio-lab-node-asus/ and restart the service.

Quick node health check

source .venv/bin/activate
python scripts/test_lab_node_client.py http://192.168.0.88:8002/sse
python scripts/test_lab_node_client.py http://192.168.0.38:8002/sse

How to configure Hermes

export NVIDIA_NIM_API_KEY="nvapi-..."   # optional; falls back to Ollama
export STRIPE_SECRET_KEY="sk_test_..."  # optional; needed for payment tools
python scripts/setup_hermes.py
hermes doctor
hermes mcp list

How to run tests

source .venv/bin/activate
PYTHONPATH=/home/fcunha/portugalfuturista/replica/experiments/hermes-launch pytest tests/
python -m py_compile server.py demo.py hardware_lab_node/server.py orchestrator/orchestrator.py scripts/setup_hermes.py

Note: pytest alone fails with ModuleNotFoundError: No module named 'skills' because the repo is not installed as an editable package. Always set PYTHONPATH to the workspace root.

How to run the sub-agent orchestrator

# Run the queued tasks (default max 4 concurrent Kimi CLI processes)
python orchestrator/orchestrator.py --tasks orchestrator/tasks.json [--max-concurrent 4]

# Check status without starting anything
python orchestrator/orchestrator.py --status

Each task spawns kimi --print --yolo --afk -w <work_dir> --prompt <prompt>. Logs are written to orchestrator/logs/<task_id>.log and state is persisted in orchestrator/state.json.

Important constraints

• 4-agent concurrency limit. The orchestrator defaults to MAX_CONCURRENT=4. Do not raise it unless you are sure the machine and API rate limits can handle it.
• Single MCP gateway. Hermes must talk only to Olhos-de-Orpheu. Do not add extra mcp_servers entries in ~/.hermes/config.yaml unless the gateway itself is being redesigned.
• Hardware side effects. aurelio_flash_firmware, aurelio_erase_flash, ppk2_start_profiling, and xgecu_program_device touch real devices. Always verify the target node_id and /dev/tty* port before running them.
• Stripe test mode. Budget/payment tools create real PaymentIntents against the configured Stripe account. Use test keys unless you intend to charge a real card.

Known blockers / gotchas

1. Public URL 404. https://olhos-de-orpheu.portugalfuturista.org/sse currently returns 404. Use the direct CT IP http://192.168.0.16:8001/sse for the hackathon demo.
2. NVIDIA model availability. nvidia/nemotron-3-ultra-550b-a55b is the configured model; if NVIDIA returns 404, scripts/setup_hermes.py will fall back to local Ollama (llama3.2 at 192.168.0.104:11434).
3. PPK2 service path. Earlier ASUS node deployments expected /home/fcunha/savearth/aws-iot-core-poc/tools/scripts/ppk2_service.py, which does not exist on that host. The adapter should be self-contained (pyserial-based) and mirrored locally in hardware_lab_node/adapters/ppk2.py.
4. LattePanda on bench-lab. /dev/ttyACM0 is the LattePanda Leonardo; the ESP32-S3 is on /dev/ttyACM1. Default tool arguments already point to /dev/ttyACM1.
5. Hermes integration test reliability. tests/test_smoke.py initializes server.py and scripts/sci_bot_mcp.py over stdio; these tests may return exit code -15 (SIGTERM) on timeout and should still pass.

When to edit what

• Gateway routing / tool surface → olhos-de-orpheu repository (src/olhos_de_orpheu/tools/).
• Lab node hardware adapter → hardware_lab_node/adapters/<device>.py (mirror fix to /opt/aurelio-lab-node-asus/ on the remote node).
• Stripe / spend logic → skills/aurelio_stripe.py (Olhos uses its own copy; keep them consistent).
• Hermes config generation → scripts/setup_hermes.py.
• Demo scenario → demo.py and demo/scenario.md.
• Docs → README.md and this file.