xdcloudy/hermes-local

Purpose and entry points

Hermes Local is a Windows-first, local AI workstation integrating Hermes Agent with managed llama.cpp GGUF inference. It provides setup, lifecycle control, model/profile management, diagnostics, benchmarks, recovery, and an Electron control centre.

Primary operator entry points:

• Setup-Hermes-Local.ps1 provisions dependencies, runtime, agent integration, configuration, and diagnostics.

• Start-Hermes-Local.ps1 / Stop-Hermes-Local.ps1 control the managed stack.

• apps/desktop/electron/main.ts starts the packaged Electron application; apps/desktop/src/main.tsx starts its renderer.

Workstation lifecycle and process ownership

PowerShell is the authoritative workstation control plane. Shared lifecycle logic coordinates stack startup, shutdown, health, and recovery; a supervisor owns managed child processes and job state.

• scripts/Common-Hermes.psm1

• scripts/supervisor/Hermes-Supervisor.ps1

• scripts/supervisor/Hermes-Job.ps1

The managed processes include llama.cpp inference, a reconstructed/pinned Hermes Agent harness, and optionally a messaging gateway. Lifecycle scripts are designed for rerun, repair, rollback, and durable operational recovery.

Inference runtime, models, and profiles

The current owned inference backend is llama.cpp, served through authenticated loopback endpoints (default OpenAI-compatible endpoint on port 8011). Runtime installation, identity, package selection, and recovery are separated from model selection and configuration.

• scripts/Hermes-RuntimeManager.psm1

• scripts/runtime/Hermes-RuntimeInstall.ps1

• config/runtime/llama-runtime-catalog.json

Models are external GGUF artifacts, never committed to the repository; manifests and schemas define verified artifacts. Profiles encode execution tuning such as context, cache, threads, batching, GPU offload, and Flash Attention.

• models/manifests/Qwen3.6-35B-A3B-APEX-MTP-I-Quality.json

• config/profiles/profiles.json

• config/schemas/runtime-contracts.schema.json

Desktop client and native boundary

The TypeScript Electron desktop client is the primary interactive control centre. The Electron main process is the privileged boundary: it launches/probes backends, manages installation and updates, handles filesystem/Git/SSH/native authentication, and exposes a constrained preload interface to the React renderer.

• apps/desktop/electron/main.ts

• apps/desktop/electron/preload.ts

• apps/desktop/electron/primary-backend-startup.ts

The renderer’s root application and routing compose chat, workstation controls, settings, project/session surfaces, and overlays.

• apps/desktop/src/app/index.tsx

• apps/desktop/src/app/routes.ts

• apps/desktop/src/hermes.ts

Gateway, sessions, and agent interaction flow

The renderer boots and communicates with the local Hermes gateway through WebSocket/JSON-RPC abstractions. Session prompt actions send turns; stream processing converts gateway events into session, tool, approval, compaction, and message state; chat components render the resulting transcript and artifacts.

• apps/desktop/src/app/gateway/hooks/use-gateway-boot.ts

• apps/desktop/src/lib/gateway-rpc.ts

• apps/desktop/src/app/session/hooks/use-message-stream/index.ts

This is the key runtime data flow: user composer → session prompt actions → local gateway/agent → streamed events → renderer stores → thread/chat UI.

• apps/desktop/src/app/chat/composer/index.tsx

• apps/desktop/src/app/session/hooks/use-prompt-actions/submit.ts

• apps/desktop/src/components/assistant-ui/thread/index.tsx

Durable operations, updates, and trust boundary

Long-running operations—benchmarks, model downloads, backup/restore, security scanning, runtime/desktop/agent updates—use task state surfaced in the desktop Task Centre. Updates use shared orchestration with staging and safe activation rather than direct in-place replacement.

• scripts/Hermes-UpdateOrchestrator.psm1

• scripts/desktop-update/DesktopUpdate-Stage.ps1

• apps/desktop/electron/hermes-local-task-store.ts

Security is local-first: services bind to loopback, credentials are DPAPI-protected for the Windows user, and integrations/skills are governed by explicit trust contracts.

• scripts/Hermes-Gateway.psm1

• config/schemas/trust-contracts.schema.json

• apps/desktop/electron/hermes-local-trust-centre.ts

Extension and delivery boundaries

The renderer includes a contribution/plugin runtime with registries and runtime loading, while the agent remains the external core integration rather than being implemented in this tree.

• apps/desktop/src/contrib/registry.ts

• apps/desktop/src/contrib/runtime-loader.ts

• apps/desktop/src/sdk/runtime.ts

Delivery combines Electron packaging with Windows PowerShell provisioning. External infrastructure is limited primarily to GitHub releases/source, optional winget dependency installation, model download hosts, and optional NVIDIA CUDA; no Docker, WSL, or paid inference API is required.

• Build-Hermes-Launcher.ps1

• apps/desktop/scripts/run-electron-builder.mjs

• Package-Hermes-Launcher.ps1