personal-agent-os/memory-systems/agent-os/01_Wiki/hermes-gitea-ecosystem-manual.md

Hermes Gitea & Agent Development Ecosystem Manual

Version 1.0 | June 21, 2026

This manual documents the full Hermes AI Agent Development setup on Gitea. It covers repositories, the role-based multi-agent system, workflows, the critical verified operations protocol, and how to work within it. Maintained as part of your personal-agent-os knowledge base.

1. Introduction & Philosophy

The Hermes ecosystem uses layered repositories for clear separation of concerns:

• core-planning (Ty_Tech/core-planning): Read-only strategic planning. High-level decisions, project charters, architecture. This is the single source of truth for "what we're doing and why."
• personal-agent-os (Tony_tech/personal-agent-os): Active workspace. Knowledge base, projects, automation patterns, agent config. This is where Leonard builds.
• hermes-agent (Tony_tech/hermes-agent): Hermes installation, config, skills, plugins. Local agent infrastructure.
• thornhill-website (Tony_tech/thornhill-website): Production website for Thornhill Construction.
• veripath (Tony_tech/veripath): Legal/verification projects.

2. Multi-Agent System

Roles

• Leonard: VPS agent (primary builder). Runs on VPS, has access to personal-agent-os, VPS tools, and SSH tunnels.
• Jimmy: Local agent (primary executor). Runs on laptop, handles local tasks, coordinates with Leonard.
• Charlie: Voice/creative agent. Handles TTS, voice workflows, creative content.

Communication

• Agent discussion board: 00_system/agent-discussion.md for cross-agent coordination
• Agent comms inbox/outbox: agent-comms/ folder in personal-agent-os for structured messaging
• Sync bot: Automated bidirectional sync between agents via Gitea hooks

Rules

• Leonard builds alone by default
• MoA only when Leonard flags a real design fork
• Jimmy handles local PC tasks, voice, TTS
• All agents share the same Obsidian vault for context

3. Verified Operations Protocol

Model Switching

1. Check what's running: hermes status
2. Switch model: hermes model <model-name> (session-scoped)
3. Persist switch: hermes config set model.default <model-id>
4. Add fallback: hermes fallback add <model-id>
5. Verify: hermes status should show new model as primary

Cron Jobs

1. List jobs: hermes cron list
2. Create: hermes cron create --name <name> --prompt "<prompt>" --schedule "<cron>"
3. Update: hermes cron update --id <id> --prompt "<new-prompt>"
4. Run: hermes cron run --id <id>
5. Check: hermes cron log --id <id>

Git Sync

1. Local changes → git add -A && git commit -m "update" && git push
2. Vault sync cron runs every 6h: vault-sync job
3. Never commit secrets (.gitignore protects ORK.txt, VPS.txt)

4. Local Setup

Models

• LFM2.5-2.6B: Primary local model. Runs on port 1920. ~2.1GB VRAM.
• FreeToken: Manual launch only. ft.exe serve --model-path C:/models/gpt-oss-20b --port 1919
• Brother 5090: Tailnet fallback. Qwen3.6 27B MTP at 100.64.0.2:8084

Hermes Desktop

• Auto-starts via Hermes Desktop.lnk in Windows Startup
• Built locally with hermes desktop --build-only
• Bot mode built-in, profiles visible as bots

Voice

• Wake word: "hey Jimmy" via sherpa
• Edge TTS AriaNeural provider
• Auto-TTS enabled, barge-in enabled

5. Project Tracking

Projects tracked in 04_projects/<slug>/:

• status.md — current status, phase, priorities
• decisions.md — key decisions with rationale
• notes.md — working notes

Active projects listed in HOME.md (max 3 primary).

6. Security Notes

• Never commit secrets to git. Secrets live in environment variables or .gitignore'd files.
• Gitea tokens should be rotated periodically.
• SSH tunnels must be used for VPS services accessible from the laptop.
• Public repos must be audited for accidental credential exposure.

7. Troubleshooting

Model not responding

• Check port: netstat -ano | grep :<port>
• Check process: tasklist | grep -i <model-name>
• Check GPU: nvidia-smi
• Try manual API call: curl http://localhost:<port>/v1/models

Cron not running

• Check job status: hermes cron list
• Check logs: hermes cron log --id <id>
• Check cron schedule syntax

Vault sync failing

• Check git remote: git remote -v
• Check .gitignore is protecting secrets
• Check Gitea repo exists and is accessible

8. Future Improvements

• Add health check cron for all services
• Build agent-to-agent messaging via Gitea webhooks
• Create project dashboard (auto-generated from status.md files)
• Implement automated vault consolidation with better quality checks
• Add RAG query interface to Hermes desktop