docs: add Hermes setup upgrade roadmap
This commit is contained in:
root
parent
dea1546d9f
commit
5a928b1925
314
docs/hermes-setup-upgrade-roadmap.md
Normal file
314
docs/hermes-setup-upgrade-roadmap.md
Normal file
@ -0,0 +1,314 @@
|
|||||||
|
# Hermes Setup Upgrade Roadmap
|
||||||
|
|
||||||
|
**Date:** 2026-05-26
|
||||||
|
**Owner:** ByteLyst / S
|
||||||
|
**Repo:** `bytelyst-devops-tools`
|
||||||
|
**Video reference:** [Hermes Agent is the greatest AI tool ever made. Here's how to set it up](https://youtu.be/RoBD7Lc-0MI) by Alex Finn
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
Turn the Hermes setup ideas from the referenced video into a practical ByteLyst upgrade checklist for this VM-backed, Telegram-driven Hermes installation.
|
||||||
|
|
||||||
|
This roadmap is intentionally operational: every item should either improve reliability, safety, agent capability, observability, or restore/migration readiness.
|
||||||
|
|
||||||
|
## Transcript Review Status
|
||||||
|
|
||||||
|
Automated transcript retrieval was attempted through multiple paths:
|
||||||
|
|
||||||
|
- Hermes `youtube-content` transcript helper using `youtube-transcript-api`
|
||||||
|
- `yt-dlp` subtitle extraction
|
||||||
|
- direct YouTube page/player metadata inspection
|
||||||
|
- Invidious caption endpoints
|
||||||
|
- third-party transcript endpoint probing
|
||||||
|
|
||||||
|
The video title and metadata were reachable, but transcript/subtitle retrieval was blocked by YouTube anti-bot checks from this VM/cloud IP. One Invidious endpoint confirmed an English auto-generated caption track exists, but returned an empty caption body.
|
||||||
|
|
||||||
|
Because the full transcript was not retrievable from the VM, this roadmap combines:
|
||||||
|
|
||||||
|
1. the accessible video metadata and setup theme,
|
||||||
|
2. Hermes Agent's current documented capabilities,
|
||||||
|
3. the live health/status of this ByteLyst Hermes installation, and
|
||||||
|
4. ByteLyst's existing operational preferences and safety constraints.
|
||||||
|
|
||||||
|
If a manual transcript is later pasted or uploaded, re-run this review and append a `Transcript-Derived Delta` section with any new actions.
|
||||||
|
|
||||||
|
## Current ByteLyst Hermes Baseline
|
||||||
|
|
||||||
|
Observed on 2026-05-26:
|
||||||
|
|
||||||
|
- Hermes version: `v0.14.0 (2026.5.16)`
|
||||||
|
- Project path: `/usr/local/lib/hermes-agent`
|
||||||
|
- Active model/provider: `gpt-5.4` via OpenAI Codex OAuth
|
||||||
|
- Telegram gateway: configured and running under systemd
|
||||||
|
- Scheduled jobs: `1 active, 1 total`
|
||||||
|
- `Sync Hermes persistent-data backup to GitHub`
|
||||||
|
- schedule: every 30 minutes
|
||||||
|
- delivery: local
|
||||||
|
- script: `sync_hermes_persistent_backup.py`
|
||||||
|
- last status: ok
|
||||||
|
- Config version: `23`
|
||||||
|
- Telegram credentials are present
|
||||||
|
- Most optional provider/API keys are not configured, including OpenRouter, Google/Gemini, Anthropic, Firecrawl/Tavily/Exa, Browserbase/Browser Use, GitHub token, FAL, and ElevenLabs
|
||||||
|
- `hermes doctor` timed out during this review and needs a dedicated diagnostic pass
|
||||||
|
- User preference: do **not** expose the Hermes dashboard publicly
|
||||||
|
|
||||||
|
## Target State
|
||||||
|
|
||||||
|
A healthy ByteLyst Hermes setup should be:
|
||||||
|
|
||||||
|
- **Private by default:** no public dashboard exposure; private access through local shell, Telegram DM, SSH tunnel, Tailscale, or equivalent.
|
||||||
|
- **Recoverable:** configuration, skills, memory, sessions, cron jobs, and scripts are backed up and periodically restore-tested.
|
||||||
|
- **Observable:** gateway, cron, disk, memory, and backup failures surface to Telegram quickly.
|
||||||
|
- **Capable:** web search/extraction, browser automation, GitHub/Gitea operations, vision, file, terminal, cron, memory, session search, and delegation are all configured where useful.
|
||||||
|
- **Safe:** secrets are not committed, destructive commands remain approval-gated, public Caddy exposure is explicitly reviewed, and profiles isolate risky experiments.
|
||||||
|
- **Self-improving:** recurring procedures are captured as skills; stale or wrong skills are patched immediately.
|
||||||
|
|
||||||
|
## Roadmap Checklist
|
||||||
|
|
||||||
|
### Phase 0 — Safety Freeze And Guardrails
|
||||||
|
|
||||||
|
- [ ] Confirm no Caddy route exposes a Hermes dashboard or Hermes API server publicly.
|
||||||
|
- [ ] Add a negative-control check to operational docs: `Hermes dashboard/API must not be public without explicit approval`.
|
||||||
|
- [ ] Verify firewall/Caddy routes for any hostnames pointing to Hermes ports.
|
||||||
|
- [ ] Decide private access pattern for any future dashboard:
|
||||||
|
- [ ] local-only binding
|
||||||
|
- [ ] SSH tunnel
|
||||||
|
- [ ] Tailscale/WireGuard
|
||||||
|
- [ ] Cloudflare Access or equivalent identity gate
|
||||||
|
- [ ] basic auth plus IP allowlist only if a public route is unavoidable
|
||||||
|
- [ ] Keep command approvals at `manual` or `smart`; do not globally use approval bypass for the gateway.
|
||||||
|
|
||||||
|
### Phase 1 — Health Baseline And Diagnostics
|
||||||
|
|
||||||
|
- [ ] Run and capture `hermes --version`.
|
||||||
|
- [ ] Run and capture `hermes config check`.
|
||||||
|
- [ ] Investigate why `hermes doctor` timed out.
|
||||||
|
- [ ] Re-run with a longer timeout from a foreground shell.
|
||||||
|
- [ ] If still hanging, isolate the step by checking logs and dependencies.
|
||||||
|
- [ ] File or fix a Hermes bug if the timeout is reproducible.
|
||||||
|
- [ ] Run `hermes status --all` and save a sanitized baseline summary.
|
||||||
|
- [ ] Check gateway service health:
|
||||||
|
- [ ] `systemctl status hermes-gateway` or the actual installed service unit
|
||||||
|
- [ ] recent gateway logs under `~/.hermes/logs/`
|
||||||
|
- [ ] Telegram send/receive smoke test
|
||||||
|
- [ ] Check cron scheduler health and last-run status.
|
||||||
|
- [ ] Check disk, memory, CPU, open ports, and long-running Hermes processes.
|
||||||
|
- [ ] Create a recurring monthly `Hermes setup review` checklist from this baseline.
|
||||||
|
|
||||||
|
### Phase 2 — Backup, Restore, And Migration Readiness
|
||||||
|
|
||||||
|
- [ ] Keep the existing persistent-data backup cron active.
|
||||||
|
- [ ] Verify the backup repository receives fresh commits after real state changes.
|
||||||
|
- [ ] Confirm the backup intentionally excludes raw secrets and `state.db`.
|
||||||
|
- [ ] Add a restore rehearsal checklist:
|
||||||
|
- [ ] clone backup repo into a temporary directory
|
||||||
|
- [ ] run restore script in dry-run mode if available
|
||||||
|
- [ ] verify config, skills, sessions, cron, memory, and scripts restore into a test profile
|
||||||
|
- [ ] confirm no raw `.env`, OAuth token, or credential file appears in git
|
||||||
|
- [ ] Add a quarterly restore drill reminder cron job or calendar task.
|
||||||
|
- [ ] Document exact restore commands in a ByteLyst ops doc.
|
||||||
|
|
||||||
|
### Phase 3 — Upgrade Strategy
|
||||||
|
|
||||||
|
- [ ] Check whether Hermes is already at the latest stable release before each upgrade.
|
||||||
|
- [ ] Before upgrading:
|
||||||
|
- [ ] run backup sync manually
|
||||||
|
- [ ] capture `hermes --version`, `hermes status --all`, and `hermes config check`
|
||||||
|
- [ ] snapshot config and cron job list
|
||||||
|
- [ ] Upgrade Hermes from an interactive shell, not from a public-facing workflow.
|
||||||
|
- [ ] After upgrade:
|
||||||
|
- [ ] restart gateway
|
||||||
|
- [ ] run Telegram smoke test
|
||||||
|
- [ ] verify cron still runs
|
||||||
|
- [ ] run one safe terminal/file task
|
||||||
|
- [ ] run one memory/session-search task
|
||||||
|
- [ ] Record upgrade date, version, and any manual fixups in `docs/operations.md` or a Hermes-specific ops note.
|
||||||
|
|
||||||
|
### Phase 4 — Provider And Model Resilience
|
||||||
|
|
||||||
|
- [ ] Keep OpenAI Codex OAuth as the primary provider if it remains stable.
|
||||||
|
- [ ] Add at least one fallback provider for resilience:
|
||||||
|
- [ ] OpenRouter
|
||||||
|
- [ ] Google/Gemini
|
||||||
|
- [ ] Anthropic
|
||||||
|
- [ ] local/Ollama if useful for low-risk offline tasks
|
||||||
|
- [ ] Configure provider credentials through Hermes auth/config flows; do not commit keys.
|
||||||
|
- [ ] Define model routing tiers:
|
||||||
|
- [ ] fast/cheap model for routine summaries and simple ops
|
||||||
|
- [ ] strong coding model for repo work
|
||||||
|
- [ ] vision-capable model for screenshots/images
|
||||||
|
- [ ] long-context model for large transcripts and audits
|
||||||
|
- [ ] Test fallback behavior by switching models in a new session.
|
||||||
|
- [ ] Document the preferred default model and fallback order.
|
||||||
|
|
||||||
|
### Phase 5 — Tooling Capability Upgrade
|
||||||
|
|
||||||
|
- [ ] Enable/configure at least one reliable web search/extract backend:
|
||||||
|
- [ ] Exa
|
||||||
|
- [ ] Tavily
|
||||||
|
- [ ] Firecrawl
|
||||||
|
- [ ] SearXNG self-hosted option
|
||||||
|
- [ ] Configure browser automation only if needed and keep it private/safe:
|
||||||
|
- [ ] local Chromium/Camofox, or
|
||||||
|
- [ ] Browserbase/Browser Use
|
||||||
|
- [ ] Configure GitHub/Gitea automation credentials with least privilege.
|
||||||
|
- [ ] Add vision/image capability if screenshots, diagrams, or UI reviews are common.
|
||||||
|
- [ ] Validate the active Telegram toolset includes the capabilities ByteLyst expects:
|
||||||
|
- [ ] terminal
|
||||||
|
- [ ] file
|
||||||
|
- [ ] search/session_search
|
||||||
|
- [ ] memory
|
||||||
|
- [ ] skills
|
||||||
|
- [ ] cronjob
|
||||||
|
- [ ] messaging
|
||||||
|
- [ ] delegation
|
||||||
|
- [ ] browser/web if configured
|
||||||
|
- [ ] Document tool enablement changes and restart/reset requirements.
|
||||||
|
|
||||||
|
### Phase 6 — Telegram Gateway Workflow
|
||||||
|
|
||||||
|
- [ ] Keep Telegram as the primary control plane.
|
||||||
|
- [ ] Preserve the user's preferred progress prefix convention: `1️⃣`, `2️⃣`, etc.
|
||||||
|
- [ ] Ensure home channel and allowed user settings are correct.
|
||||||
|
- [ ] Add smoke-test steps for:
|
||||||
|
- [ ] inbound Telegram command
|
||||||
|
- [ ] outbound completion message
|
||||||
|
- [ ] approval prompt flow
|
||||||
|
- [ ] media/file delivery
|
||||||
|
- [ ] Decide whether Telegram topic/session handling should be enabled or documented.
|
||||||
|
- [ ] Add a runbook for gateway restart/recovery.
|
||||||
|
|
||||||
|
### Phase 7 — Memory, Skills, And Knowledge Capture
|
||||||
|
|
||||||
|
- [ ] Review persistent memory for stale entries and trim anything no longer useful.
|
||||||
|
- [ ] Keep memories declarative and durable; avoid storing task-completion artifacts.
|
||||||
|
- [ ] Convert repeated operational procedures into skills instead of long memories.
|
||||||
|
- [ ] Pin critical ByteLyst/Hermes skills that should not be archived.
|
||||||
|
- [ ] Schedule or manually run curator reviews if enabled.
|
||||||
|
- [ ] Add skills for recurring ByteLyst workflows:
|
||||||
|
- [ ] Gitea Actions troubleshooting
|
||||||
|
- [ ] Caddy + Docker routing changes
|
||||||
|
- [ ] Hermes backup/restore drill
|
||||||
|
- [ ] Telegram gateway recovery
|
||||||
|
- [ ] safe multi-repo commit/push workflow
|
||||||
|
|
||||||
|
### Phase 8 — Cron, Watchdogs, And Autonomous Maintenance
|
||||||
|
|
||||||
|
- [ ] Keep current Hermes backup cron job enabled.
|
||||||
|
- [ ] Add watchdogs that notify Telegram only on actionable failures:
|
||||||
|
- [ ] gateway down
|
||||||
|
- [ ] cron scheduler stale
|
||||||
|
- [ ] backup job failed or no fresh commit within threshold
|
||||||
|
- [ ] disk usage high
|
||||||
|
- [ ] memory pressure high
|
||||||
|
- [ ] Caddy/Gitea critical services down
|
||||||
|
- [ ] Prefer `no_agent=True` script-only watchdogs for fixed health checks.
|
||||||
|
- [ ] Keep noisy health checks silent on success.
|
||||||
|
- [ ] Use self-contained prompts for any LLM-driven cron jobs.
|
||||||
|
- [ ] Avoid recursive cron creation from cron-run sessions.
|
||||||
|
|
||||||
|
### Phase 9 — Private Dashboard / Mission Control Direction
|
||||||
|
|
||||||
|
- [ ] Do not expose Hermes dashboard publicly.
|
||||||
|
- [ ] If a dashboard is useful, make it private-only and operationally scoped.
|
||||||
|
- [ ] Dashboard should show:
|
||||||
|
- [ ] gateway status
|
||||||
|
- [ ] active sessions
|
||||||
|
- [ ] cron job state
|
||||||
|
- [ ] backup freshness
|
||||||
|
- [ ] recent sanitized alerts
|
||||||
|
- [ ] quick links to docs/runbooks
|
||||||
|
- [ ] Any dashboard actions must require authentication and ideally remain reachable only over private network/tunnel.
|
||||||
|
- [ ] Add a Caddy review step before adding any new hostname.
|
||||||
|
|
||||||
|
### Phase 10 — Multi-Agent And Project Execution Workflow
|
||||||
|
|
||||||
|
- [ ] Use `delegate_task` for bounded subtasks inside a parent session.
|
||||||
|
- [ ] Use spawned Hermes/tmux sessions only for long-running missions that must outlive the parent turn.
|
||||||
|
- [ ] Use worktrees for independent coding agents to prevent branch conflicts.
|
||||||
|
- [ ] For durable multi-agent coordination, evaluate Hermes Kanban.
|
||||||
|
- [ ] Document when to use:
|
||||||
|
- [ ] direct tool call
|
||||||
|
- [ ] delegate_task
|
||||||
|
- [ ] background terminal process
|
||||||
|
- [ ] cron job
|
||||||
|
- [ ] Kanban worker
|
||||||
|
- [ ] Add a ByteLyst convention for progress/completion Telegram notifications from concurrent sessions.
|
||||||
|
|
||||||
|
### Phase 11 — Security And Secret Hygiene
|
||||||
|
|
||||||
|
- [ ] Reconfirm raw `.env`, OAuth credentials, tokens, logs, and SQLite WAL/SHM files are excluded from git backups.
|
||||||
|
- [ ] Consider enabling `security.redact_secrets` if the operational tradeoff is acceptable.
|
||||||
|
- [ ] Keep `privacy.redact_pii` decision documented for gateway sessions.
|
||||||
|
- [ ] Rotate old credentials after migration or accidental exposure risk.
|
||||||
|
- [ ] Use least-privilege tokens for GitHub/Gitea, web APIs, and provider keys.
|
||||||
|
- [ ] Add a pre-commit or manual scan step before pushing Hermes backup/config changes.
|
||||||
|
- [ ] Keep approval mode at `manual` or `smart` for Telegram-driven work.
|
||||||
|
|
||||||
|
### Phase 12 — Documentation And Runbooks
|
||||||
|
|
||||||
|
- [ ] Add a Hermes operations index under `docs/`.
|
||||||
|
- [ ] Link this roadmap from `docs/repo-map.md`.
|
||||||
|
- [ ] Create or update runbooks for:
|
||||||
|
- [ ] installing/upgrading Hermes
|
||||||
|
- [ ] restarting the gateway
|
||||||
|
- [ ] restoring persistent data from backup
|
||||||
|
- [ ] configuring providers/models
|
||||||
|
- [ ] enabling/disabling tools
|
||||||
|
- [ ] adding safe cron watchdogs
|
||||||
|
- [ ] private-only dashboard access
|
||||||
|
- [ ] Keep commands copy-pasteable and include expected outputs.
|
||||||
|
- [ ] Store secrets only as placeholder variable names or `.env.example` entries.
|
||||||
|
|
||||||
|
## Priority Execution Plan
|
||||||
|
|
||||||
|
### Immediate — Today / Next Session
|
||||||
|
|
||||||
|
- [ ] Confirm no public Hermes dashboard route exists.
|
||||||
|
- [ ] Investigate `hermes doctor` timeout.
|
||||||
|
- [ ] Verify backup cron freshness and remote push status.
|
||||||
|
- [ ] Add one Telegram watchdog for gateway/backup failure.
|
||||||
|
- [ ] Choose and configure one web search backend.
|
||||||
|
|
||||||
|
### Near-Term — This Week
|
||||||
|
|
||||||
|
- [ ] Add fallback model/provider.
|
||||||
|
- [ ] Document provider routing and model defaults.
|
||||||
|
- [ ] Add gateway recovery runbook.
|
||||||
|
- [ ] Add restore drill runbook and perform one test-profile restore.
|
||||||
|
- [ ] Add Gitea/GitHub least-privilege automation credential path.
|
||||||
|
|
||||||
|
### Medium-Term — This Month
|
||||||
|
|
||||||
|
- [ ] Evaluate private-only dashboard/mission-control UX.
|
||||||
|
- [ ] Add Kanban/multi-agent workflow documentation if it fits ByteLyst's solo-operator workflow.
|
||||||
|
- [ ] Add silent-on-success system watchdogs.
|
||||||
|
- [ ] Clean up stale memory/skills and pin critical skills.
|
||||||
|
- [ ] Schedule quarterly restore drills.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
This roadmap is complete when:
|
||||||
|
|
||||||
|
- [ ] Hermes can be upgraded and rolled back/restored with a documented process.
|
||||||
|
- [ ] Gateway failures and backup failures notify Telegram.
|
||||||
|
- [ ] At least one fallback model/provider is configured and tested.
|
||||||
|
- [ ] Web/search tooling works for current research tasks.
|
||||||
|
- [ ] No Hermes dashboard/API is publicly exposed.
|
||||||
|
- [ ] Backup restore has been tested into a non-production profile.
|
||||||
|
- [ ] Core ByteLyst Hermes procedures exist as docs or skills.
|
||||||
|
- [ ] Sensitive files remain untracked and backup-safe.
|
||||||
|
|
||||||
|
## Notes For Future Transcript Pass
|
||||||
|
|
||||||
|
When the transcript is available, specifically check whether the video recommends any of the following and update this roadmap accordingly:
|
||||||
|
|
||||||
|
- exact provider/model choices
|
||||||
|
- recommended Hermes install path
|
||||||
|
- gateway platform setup details
|
||||||
|
- dashboard or web UI exposure guidance
|
||||||
|
- memory/skill workflows
|
||||||
|
- MCP server recommendations
|
||||||
|
- cron/background agent patterns
|
||||||
|
- voice/STT/TTS setup
|
||||||
|
- any security warnings or anti-patterns
|
||||||
@ -50,6 +50,7 @@ Current key files:
|
|||||||
- `docs/supported-scripts.md`
|
- `docs/supported-scripts.md`
|
||||||
- `docs/operations.md`
|
- `docs/operations.md`
|
||||||
- `docs/remove_user_interactive.md`
|
- `docs/remove_user_interactive.md`
|
||||||
|
- `docs/hermes-setup-upgrade-roadmap.md`
|
||||||
|
|
||||||
### `.github/workflows/`
|
### `.github/workflows/`
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user