PROJECT.md — Hermes OS

Mobile-first dashboard for Hermes Agent. Visibility into state, control over behavior, and self-improvement — all from your phone.

Architecture

Phone/Browser → Next.js (port 3100) → proxy routes → Hermes WebAPI (8643) + Gateway (8642)

All API calls proxy through Next.js server-side route handlers. No CORS, no cross-origin issues. The frontend makes same-origin requests only.

Modules

Pulse (/)

Home screen. Status card (model, online/offline), stats (sessions, tokens, platforms), memory usage bars, platform breakdown, quick links to Skills/Cron/Soul/Config, recent sessions list. Pull-to-refresh.

Memory (/memory)

Agent + User memory tabs. View entries, inline edit, delete with confirm, add new. Usage bar with char limit. All mutations go through WebAPI.

History (/history)

Session list with platform filter (All/CLI/Telegram/Discord/Web) and full-text search. New session creation (/history/new). Session replay with:

Newest-first message order
Verbosity toggle: Compact (text only) / Normal (+ tool calls) / Full (+ reasoning + expanded results)
Message input to continue sessions
Thinking indicator while agent runs
Session delete with confirm
Refresh button

Skills (/skills)

Categorized skill browser with search/filter. Skill detail renders SKILL.md as proper markdown (headings, code blocks, tables, blockquotes). Shows linked files.

Cron (/cron)

Job list grouped by status (active/paused/other). Manual trigger button. Detail page (/cron/[id]) with job metadata, prompt, and output history read from filesystem.

Soul (/soul)

SOUL.md editor. Direct filesystem read/write. Save/revert with dirty detection.

Config (/config)

Read-only config viewer. Model, terminal, memory, display sections.

Stack

Next.js 15, TypeScript, Tailwind CSS v4
TanStack Query for server state
Lucide icons, react-markdown + remark-gfm
PWA manifest + service worker
systemd user services for persistence

Services

# Deploy (build + install services + restart)
bash deploy/deploy.sh 3100

# Manual control
systemctl --user status hermes-os
systemctl --user status hermes-webapi
systemctl --user restart hermes-os

Environment

Variable	Default	Description
`HERMES_BACKEND_URL`	`http://127.0.0.1:8643`	WebAPI (FastAPI)
`HERMES_GATEWAY_URL`	`http://127.0.0.1:8642`	Gateway (aiohttp, cron jobs)
`HERMES_SOUL_PATH`	`~/.hermes/SOUL.md`	Persona file
`HERMES_CRON_OUTPUT`	`~/.hermes/cron/output`	Cron output directory

2.5 KiB Raw Blame History