diff --git a/docs/hermes-setup-upgrade-roadmap.md b/docs/hermes-setup-upgrade-roadmap.md new file mode 100644 index 0000000..f8dac69 --- /dev/null +++ b/docs/hermes-setup-upgrade-roadmap.md @@ -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 diff --git a/docs/repo-map.md b/docs/repo-map.md index 618596c..5b4ed21 100644 --- a/docs/repo-map.md +++ b/docs/repo-map.md @@ -50,6 +50,7 @@ Current key files: - `docs/supported-scripts.md` - `docs/operations.md` - `docs/remove_user_interactive.md` +- `docs/hermes-setup-upgrade-roadmap.md` ### `.github/workflows/`