Agent Architecture Decision

AI Agent Architecture

Decision Document

Hermes, Claude Code, and the Personal Productivity Gap

17 June 2026

João Luís Brazão

1. Executive Summary

Verdict: Keep Hermes. Scope it to business. Fix one broken credential. Defer the local personal productivity agent until concrete use cases are defined.

Hermes is already more secure than this evaluation initially assumed --- Telegram user ID allowlist is configured, self-evolution is disabled, WireGuard IP allowlist protects the dashboard, and all LLM calls route through the LiteLLM proxy. The real problem is not security: it is scope blur. One autonomous agent is currently expected to serve both business automation (brain pipelines, TCN, audit, JBSB) and personal productivity (Obsidian, local queries, personal reminders). These are fundamentally different needs with different risk profiles.

The optimal solution is a phased bifurcated model:

  • Phase 1 (immediate): Harden Hermes, formally scope it to business automation only, fix the broken dashboard password.

  • Phase 1.5 (already running): Open WebUI at localhost:3000 covers interactive personal AI without building anything new.

  • Phase 2 (future, conditional): Build a minimal local MacBook agent only when three or more concrete autonomous personal tasks are identified.

Do not abandon Hermes. Do not replace it. Do not build the local agent before the use cases exist.

2. The Problem

2.1 Current State

The production infrastructure runs one autonomous AI orchestration system: Hermes, deployed on a VPS (Hostinger, Ubuntu 24.04, 76.13.44.83). Hermes operates 24/7, responds to Telegram commands via \@DownRabbitbot, and orchestrates 85 HTTP skills through jb-skills-gateway. It handles business automation across multiple entities: Down a Rabbit Hole brain (content curation, enrichment, graph rebuild), Tuga Car Nuts (article ingestion, taxonomy), JBSB intelligence system (memory decay, contradiction engine), and the Sovereign Audit Pipeline.

Separately, a local AI stack runs on a MacBook Pro M3: Ollama (local model inference) + LiteLLM proxy (localhost:4000) + Open WebUI (localhost:3000) + Colima. This stack is completely airgapped --- zero data leaves the machine.

Claude Code, the interactive AI development environment, has direct MCP-tool access to both Chrome and the VPS via SSH. This creates a third layer of AI capability that did not previously exist.

2.2 The Non-Negotiable Principles

Any architecture must satisfy the following constraints, all of which are permanent:

  • Digital sovereignty: No data to Google, Microsoft, or iCloud. Self-hosted infrastructure only.

  • Light backgrounds only: João is colorblind. All UI must use light scheme. Dark mode is unusable --- this is not a preference, it is a hard accessibility requirement.

  • No external cloud providers for sensitive data: Health records, personal notes, and financial data stay local.

  • LiteLLM as the sole LLM gateway: No service calls any AI provider directly. All calls route through the LiteLLM proxy for cost control, model routing, and key management.

  • Production promotion requires explicit approval: No autonomous deployments to production.

  • CATALOG-FIRST rule: Before building any new skill or agent, search the Skills Catalog. Adapt existing before building new.

2.3 The Gap: Personal Productivity vs Business Automation

Business Automation Needs Personal Productivity Needs

24/7 uptime, event-driven triggers Phone-initiated queries, casual (Telegram, crons) voice-to-text commands

VPS-native execution, DB and Local file access (Obsidian vault), service connections Mac-native integrations

Structured skill workflows, cron Privacy for personal data, no VPS scheduling logging

Hermes was built for the first category. Using it for the second creates scope blur: personal queries go to the VPS, personal data could be logged in VPS databases, and the maintenance burden grows as the agent tries to be everything.

3. Evaluation Criteria

Each option is evaluated against six criteria, scored Low / Medium / High:

Criterion Definition

Feature Richness Does it deliver the autonomous automation capability needed?

Security Posture Attack surface, data exposure, authentication strength

Ease of Use Can João trigger it from a phone without developer intervention?

Real Productivity Does it eliminate actual friction, not Increase theoretical friction?

Maintenance Burden How much ongoing work does it require?

Sovereignty Does it respect all non-negotiable principles? Compliance

4. Four Options Evaluated

Option A --- Status Quo: Keep Hermes as-is, no local agent

No changes. Hermes continues to serve both business and personal use cases from the VPS.

Feature Richness HIGH --- 85 skills, crons, Telegram, full VPS integration

Security Posture MEDIUM --- scope blur; dashboard auth currently broken

Ease of Use HIGH --- Telegram configured, works from phone

Real Productivity LOW --- no change; personal productivity gap Increase unaddressed

Maintenance Burden LOW --- nothing new to build

Sovereignty HIGH --- fully self-hosted Compliance

Verdict: REJECTED --- does not address the problem, leaves the broken auth unresolved.

Option B --- Bifurcated Model [RECOMMENDED]

Hermes is formally scoped to business automation only and hardened. A minimal Python-based agent (\~300 lines) runs locally on MacBook Pro M3, using a second Telegram bot in polling mode (no public IP required). The local agent has access only to local filesystem, Obsidian vault, and localhost:4000. It has no VPS credentials.

Phase 1 (immediate --- 3 actions):

  • Fix Hermes dashboard auth password (ASCII only, no special characters)

  • Document skill risk tiers: read skills execute autonomously; write/destructive skills require Telegram confirmation

  • Create DNS A record for hermes.joaoluisbrazao.cloud (manual step at Hostinger registrar)

Phase 1.5 (already live, no action needed):

  • Open WebUI at localhost:3000 already serves interactive personal AI. Covers 80% of the personal productivity use case.

Phase 2 (future, conditional --- only when 3+ concrete use cases are defined):

  • Minimal local agent: second Telegram bot, polling mode, MacBook only

  • Hard boundary: no VPS SSH credentials on this agent

  • Build only when: autonomous, unattended, phone-triggered personal tasks are specified

Feature Richness HIGH --- Hermes retains full business capability; local agent adds personal layer

Security Posture HIGH --- clear data boundaries; personal data stays local

Ease of Use HIGH --- both agents use Telegram; phone-accessible

Real Productivity HIGH --- Hermes improves; personal gap Increase addressed when use cases exist

Maintenance Burden MEDIUM --- two systems, but local agent is minimal by design

Sovereignty HIGH --- fully self-hosted, local data stays Compliance local

Verdict: RECOMMENDED --- phased approach, no waste, clear boundaries.

Option C --- Replace Hermes: Adopt a lighter tool

Retire Hermes and replace with a lighter, simpler alternative. Paperclip was evaluated as a candidate but confirmed NOT installed on the VPS as of 2026-06-12 (no /opt/prod/paperclip/, no container). No evaluated alternative has been identified.

  • 85 skills represent months of integration work --- all must be rebuilt

  • All business crons depend on the current skill architecture

  • Any replacement inherits the same fundamental security questions

  • Evaluating and migrating takes months; existing automation stops or degrades

Verdict: REJECTED --- disruption cost far exceeds any theoretical benefit.

Option D --- Abandon Autonomous Agents: Claude Code only

Retire Hermes. Rely entirely on Claude Code (with Chrome + VPS SSH MCP access) for all automation.

  • Claude Code is session-based --- no persistence, no crons, no Telegram

  • Brain enrichment stalls (9,349/18,906 nodes, remainder stops)

  • JBSB memory decay and contradiction engine stop

  • All scheduled intelligence work requires manual initiation

Verdict: REJECTED --- viable only as a development mode, not for production operations.

5. Risk Matrix

Risks assessed on two axes: Likelihood (1=Rare, 4=Likely) and Impact (1=Minimal, 4=Critical). Risk Score = Likelihood × Impact.

Risk Status L I Score

Telegram allowlist not MITIGATED 1 4 4 --- LOW enforced

Dashboard password broken OPEN 2 3 6 --- MEDIUM (#951)

Write skills execute without OPEN 2 4 8 --- HIGH confirm

Local agent receives VPS FUTURE RISK 2 4 8 --- HIGH credentials (if not prevented)

MacBook sleeps, agent misses FUTURE RISK 3 2 6 --- MEDIUM tasks

LiteLLM proxy outage OPEN 2 3 6 --- MEDIUM (dependency)

HONCHO re-enabled MITIGATED 1 4 4 --- LOW accidentally

6. Risk Mitigation Options

6.1 Telegram User ID Allowlist (already implemented)

Hermes only responds to messages from João's Telegram user ID, configured in TELEGRAM_ALLOWED_USERS. Verify this is a numeric user ID, not a \@username (usernames can be changed; user IDs cannot). Test: send a message from a second Telegram account --- Hermes must ignore it.

6.2 Skill Risk Tiers

Add a SKILL_RISK_TIER metadata field to each skill in jb-skills-gateway. Three tiers:

  • read --- query operations, status checks, report generation: execute autonomously

  • write --- database mutations, file changes, container restarts: require a Telegram confirmation reply within 60 seconds before execution

  • destructive --- production deployments, schema changes, bulk deletes: blocked; Claude Code + human approval only

Implementation: add SKILL_RISK_TIER to the SKILL_META dict in each skill file; Hermes middleware reads the tier before executing.

6.3 Dashboard Auth Fix (#951)

Current password uses the £ character (UTF-8 multibyte). HTTP Basic Auth implementations handle multibyte characters inconsistently. Fix: replace with an ASCII-only password (letters + numbers + standard symbols). Store in Vaultwarden. Apply to /opt/jb/hermes/.env. Restart hermes-joao-dashboard container.

6.4 Local Agent Data Boundary (Phase 2 design constraint)

When building the local agent, enforce at design time:

  • No VPS SSH private key accessible to the agent process

  • No VPS API tokens, DB passwords, or service credentials

  • LiteLLM base URL: localhost:4000 only (not the VPS address)

  • Obsidian vault path read-only by default; write operations require explicit confirmation

6.5 WireGuard IP Allowlist (already implemented)

Hermes dashboard nginx configuration restricts access to WireGuard subnet (10.8.0.0/24) and localhost. The dashboard is unreachable from the public internet even if basic auth fails. Verify this configuration survives nginx config reloads and container restarts.

7. Final Hard Verdict

Should you forget Hermes-like products or go with a lighter version?

Neither. Keep Hermes. Scope it. Harden it.

Hermes is not the problem. The problem is that Hermes has been asked to be two things at once: a business automation engine and a personal assistant. These roles have different risk profiles, different data sensitivity levels, and different uptime requirements. The solution is to clarify the boundary, not to replace the tool.

The security posture is already strong. Telegram allowlist is configured. Self-evolution is disabled. WireGuard protects the dashboard. All LLM calls are proxied. The one open vulnerability --- the broken dashboard password --- takes 10 minutes to fix. That is not a reason to rethink the architecture.

The 85 skills represent significant investment. Brain enrichment, JBSB, TCN ingestion, the audit pipeline, and the Sovereign Audit are all running because Hermes exists. Replacing it means rebuilding all of that. No evaluated alternative has been identified that would improve on the current architecture. Paperclip is not installed and has not been evaluated.

Claude Code + Chrome + SSH MCP is not a substitute for autonomous agents. It is a complement. Claude Code works when João is present and approves every action. Crons, background pipelines, and Telegram-triggered automation require a persistent process. That is Hermes's job.

The personal productivity gap is real but not urgent. Open WebUI at localhost:3000 already serves interactive personal AI today, without building anything. The local MacBook agent (Phase 2) is worth building when you can name three specific automations you want it to run autonomously. "Personal productivity" is not specific enough. "Create an Obsidian note from a voice message I send via Telegram while away from my desk" is.

The Architecture Today (after Phase 1 fixes)

Layer System Scope

Autonomous / 24×7 Hermes (VPS) Business automation only --- hardened, skill risk tiers documented

Interactive / Open WebUI Personal AI queries, local models, Personal (MacBook) 100% sovereign

Interactive / Claude Code Complex tasks with human approval, Complex (MacBook) Chrome + VPS SSH

Phase 2 (future) Local agent Phone-triggered personal (MacBook) automations --- build when use cases exist

8. Immediate Actions

Prioritised by urgency. Items marked [MANUAL] require João to act directly.

Action 1 --- Fix Hermes Dashboard Auth Password [URGENT --- 10 minutes]

Vikunja: #951

  • SSH into VPS: ssh vps

  • Edit /opt/jb/hermes/.env --- change HERMES_DASHBOARD_BASIC_AUTH_PASSWORD to ASCII-only value

  • Save to Vaultwarden immediately after

  • Restart: docker compose -f /opt/jb/hermes/docker-compose.yml restart hermes-joao-dashboard

  • Verify: curl -u username:newpassword https://admin.joaoluisbrazao.cloud/hermes/

Action 2 --- Create DNS A Record for hermes.joaoluisbrazao.cloud [MANUAL --- 5 minutes]

Vikunja: #943

  • Log in to Hostinger DNS panel

  • Add A record: hermes.joaoluisbrazao.cloud → 76.13.44.83, TTL: 300

  • After propagation: certbot certonly --nginx -d hermes.joaoluisbrazao.cloud

Action 3 --- Document Skill Risk Tiers [MEDIUM --- 1 hour]

  • Add SKILL_RISK_TIER to SKILL_META in each skill in /opt/jb-skills-gateway/skills/

  • Start with 5 representative skills: brain.query (read), brain.ingest-article (write), one destructive placeholder

  • Document the tier enforcement pattern in infrastructure-docs ADR-0010

Action 4 --- Verify Telegram Allowlist is Numeric User ID [LOW --- 2 minutes]

  • SSH into VPS: grep TELEGRAM_ALLOWED_USERS /opt/jb/hermes/.env

  • Confirm value is a numeric ID (e.g. 123456789), not a \@username

Action 5 --- Identify 3 Personal Productivity Use Cases for Phase 2 [FUTURE]

  • Write them down before building anything

  • Each must be: autonomous (runs without João present), phone-triggered (Telegram), local data (Obsidian/Mac files)

  • Only start Phase 2 when all three are defined

End of Document --- 17 June 2026