# xdcloudy/hermes-local architecture

> Architecture diagram of the GitHub repository xdcloudy/hermes-local, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xdcloudy/hermes-local
- Repository: https://github.com/xdcloudy/hermes-local

## Overview

#### 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`

Main entry points: [`apps/desktop/electron/main.ts`](https://github.com/xdcloudy/hermes-local/blob/main/apps/desktop/electron/main.ts) (Electron main), [`scripts/supervisor/Hermes-Supervisor.ps1`](https://github.com/xdcloudy/hermes-local/blob/main/scripts/supervisor/Hermes-Supervisor.ps1) (Process supervisor), [`scripts/Hermes-RuntimeManager.psm1`](https://github.com/xdcloudy/hermes-local/blob/main/scripts/Hermes-RuntimeManager.psm1) (Runtime manager), [`apps/desktop/src/app/index.tsx`](https://github.com/xdcloudy/hermes-local/blob/main/apps/desktop/src/app/index.tsx) (React control centre)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Workstation Control"]
  node_setup["Setup scripts<br/>PowerShell entry points"]
  node_lifecycle["Lifecycle control<br/>PowerShell module<br/>[Common-Hermes.psm1]"]
  node_supervisor["Process supervisor<br/>PowerShell supervisor"]
  node_job["Managed jobs<br/>PowerShell job runtime<br/>[Hermes-Job.ps1]"]
end

subgraph group_runtime["Inference Runtime"]
  node_runtime_manager["Runtime manager<br/>PowerShell module"]
  node_runtime_install["llama.cpp installer<br/>PowerShell installer"]
  node_runtime_catalog["Runtime catalog<br/>runtime manifest"]
  node_model_manifest["GGUF model manifest<br/>model artifact manifest"]
  node_profiles["Execution profiles<br/>profile configuration<br/>[profiles.json]"]
  node_llama{{"llama.cpp server<br/>local inference service"}}
end

subgraph group_desktop["Electron Desktop"]
  node_electron_main["Electron main<br/>privileged desktop process<br/>[main.ts]"]
  node_preload["Constrained preload API<br/>Electron IPC boundary<br/>[preload.ts]"]
  node_renderer["React control centre<br/>Electron renderer<br/>[index.tsx]"]
  node_gateway_client["Gateway RPC and boot<br/>WebSocket JSON-RPC client"]
  node_prompt_stream["Prompt and stream state<br/>session interaction flow<br/>[index.ts]"]
  node_contrib["Contribution runtime<br/>renderer plugin runtime<br/>[runtime-loader.ts]"]
end

subgraph group_agent["Gateway and Agent"]
  node_gateway{{"Local Hermes gateway<br/>loopback gateway"}}
  node_hermes_agent{{"Hermes Agent harness<br/>external agent integration"}}
end

subgraph group_operations["Operations and Delivery"]
  node_task_store["Task Centre store<br/>desktop task state"]
  node_updates["Update orchestration<br/>PowerShell update pipeline"]
  node_desktop_stage["Desktop update staging<br/>PowerShell staging step"]
  node_trust["Trust Centre<br/>desktop trust boundary"]
end

node_setup -->|"provisions"| node_lifecycle
node_setup -->|"installs"| node_runtime_manager
node_lifecycle -->|"controls"| node_supervisor
node_supervisor -->|"tracks"| node_job
node_supervisor -->|"owns"| node_llama
node_supervisor -->|"owns"| node_hermes_agent
node_runtime_manager -->|"installs"| node_runtime_install
node_runtime_install -->|"selects package from"| node_runtime_catalog
node_runtime_manager -->|"verifies"| node_model_manifest
node_runtime_manager -->|"applies"| node_profiles
node_profiles -->|"configures"| node_llama
node_model_manifest -->|"supplies GGUF"| node_llama
node_electron_main -->|"exposes"| node_preload
node_preload -->|"constrains IPC for"| node_renderer
node_renderer -->|"boots"| node_gateway_client
node_renderer -->|"drives"| node_prompt_stream
node_prompt_stream -->|"sends turns and receives events"| node_gateway_client
node_gateway_client -->|"WebSocket JSON-RPC"| node_gateway
node_gateway -->|"routes agent work"| node_hermes_agent
node_hermes_agent -->|"requests inference"| node_llama
node_electron_main -->|"records operations"| node_task_store
node_updates -->|"stages"| node_desktop_stage
node_electron_main -->|"initiates"| node_updates
node_electron_main -->|"enforces"| node_trust
node_renderer -->|"loads extensions"| node_contrib

click node_setup "https://github.com/xdcloudy/hermes-local/blob/main/Setup-Hermes-Local.ps1"
click node_lifecycle "https://github.com/xdcloudy/hermes-local/blob/main/scripts/Common-Hermes.psm1"
click node_supervisor "https://github.com/xdcloudy/hermes-local/blob/main/scripts/supervisor/Hermes-Supervisor.ps1"
click node_job "https://github.com/xdcloudy/hermes-local/blob/main/scripts/supervisor/Hermes-Job.ps1"
click node_runtime_manager "https://github.com/xdcloudy/hermes-local/blob/main/scripts/Hermes-RuntimeManager.psm1"
click node_runtime_install "https://github.com/xdcloudy/hermes-local/blob/main/scripts/runtime/Hermes-RuntimeInstall.ps1"
click node_runtime_catalog "https://github.com/xdcloudy/hermes-local/blob/main/config/runtime/llama-runtime-catalog.json"
click node_model_manifest "https://github.com/xdcloudy/hermes-local/blob/main/models/manifests/Qwen3.6-35B-A3B-APEX-MTP-I-Quality.json"
click node_profiles "https://github.com/xdcloudy/hermes-local/blob/main/config/profiles/profiles.json"
click node_electron_main "https://github.com/xdcloudy/hermes-local/blob/main/apps/desktop/electron/main.ts"
click node_preload "https://github.com/xdcloudy/hermes-local/blob/main/apps/desktop/electron/preload.ts"
click node_renderer "https://github.com/xdcloudy/hermes-local/blob/main/apps/desktop/src/app/index.tsx"
click node_gateway_client "https://github.com/xdcloudy/hermes-local/blob/main/apps/desktop/src/app/gateway/hooks/use-gateway-boot.ts"
click node_prompt_stream "https://github.com/xdcloudy/hermes-local/blob/main/apps/desktop/src/app/session/hooks/use-message-stream/index.ts"
click node_gateway "https://github.com/xdcloudy/hermes-local/blob/main/scripts/Hermes-Gateway.psm1"
click node_task_store "https://github.com/xdcloudy/hermes-local/blob/main/apps/desktop/electron/hermes-local-task-store.ts"
click node_updates "https://github.com/xdcloudy/hermes-local/blob/main/scripts/Hermes-UpdateOrchestrator.psm1"
click node_desktop_stage "https://github.com/xdcloudy/hermes-local/blob/main/scripts/desktop-update/DesktopUpdate-Stage.ps1"
click node_trust "https://github.com/xdcloudy/hermes-local/blob/main/apps/desktop/electron/hermes-local-trust-centre.ts"
click node_contrib "https://github.com/xdcloudy/hermes-local/blob/main/apps/desktop/src/contrib/runtime-loader.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_setup,node_lifecycle,node_supervisor,node_job toneBlue
class node_runtime_manager,node_runtime_install,node_runtime_catalog,node_model_manifest,node_profiles,node_llama toneAmber
class node_electron_main,node_preload,node_renderer,node_gateway_client,node_prompt_stream,node_contrib toneMint
class node_gateway,node_hermes_agent toneRose
class node_task_store,node_updates,node_desktop_stage,node_trust toneIndigo
```

## Components

### Workstation Control

PowerShell is the authoritative local control plane.

- [Setup scripts](https://github.com/xdcloudy/hermes-local/blob/main/Setup-Hermes-Local.ps1): PowerShell entry points · Provision dependencies, runtime, agent integration, configuration, and diagnostics. · `Setup-Hermes-Local.ps1`
- [Lifecycle control](https://github.com/xdcloudy/hermes-local/blob/main/scripts/Common-Hermes.psm1): PowerShell module · Coordinates start, stop, health, repair, rollback, and recovery. · `scripts/Common-Hermes.psm1`
- [Process supervisor](https://github.com/xdcloudy/hermes-local/blob/main/scripts/supervisor/Hermes-Supervisor.ps1): PowerShell supervisor · Owns managed child processes and durable job state. · `scripts/supervisor/Hermes-Supervisor.ps1`
- [Managed jobs](https://github.com/xdcloudy/hermes-local/blob/main/scripts/supervisor/Hermes-Job.ps1): PowerShell job runtime · `scripts/supervisor/Hermes-Job.ps1`

### Inference Runtime

- [Runtime manager](https://github.com/xdcloudy/hermes-local/blob/main/scripts/Hermes-RuntimeManager.psm1): PowerShell module · Separates runtime installation and recovery from model selection. · `scripts/Hermes-RuntimeManager.psm1`
- [llama.cpp installer](https://github.com/xdcloudy/hermes-local/blob/main/scripts/runtime/Hermes-RuntimeInstall.ps1): PowerShell installer · `scripts/runtime/Hermes-RuntimeInstall.ps1`
- [Runtime catalog](https://github.com/xdcloudy/hermes-local/blob/main/config/runtime/llama-runtime-catalog.json): runtime manifest · `config/runtime/llama-runtime-catalog.json`
- [GGUF model manifest](https://github.com/xdcloudy/hermes-local/blob/main/models/manifests/Qwen3.6-35B-A3B-APEX-MTP-I-Quality.json): model artifact manifest · Models are external verified GGUF artifacts. · `models/manifests/Qwen3.6-35B-A3B-APEX-MTP-I-Quality.json`
- [Execution profiles](https://github.com/xdcloudy/hermes-local/blob/main/config/profiles/profiles.json): profile configuration · Defines context, cache, threads, batching, GPU offload, and Flash Attention. · `config/profiles/profiles.json`
- **llama.cpp server**: local inference service · Authenticated loopback OpenAI-compatible inference endpoint.

### Electron Desktop

- [Electron main](https://github.com/xdcloudy/hermes-local/blob/main/apps/desktop/electron/main.ts): privileged desktop process · Launches and probes backends and owns filesystem, Git, SSH, authentication, installation, and updates. · `apps/desktop/electron/main.ts`
- [Constrained preload API](https://github.com/xdcloudy/hermes-local/blob/main/apps/desktop/electron/preload.ts): Electron IPC boundary · `apps/desktop/electron/preload.ts`
- [React control centre](https://github.com/xdcloudy/hermes-local/blob/main/apps/desktop/src/app/index.tsx): Electron renderer · Composes chat, workstation controls, settings, projects, sessions, and overlays. · `apps/desktop/src/app/index.tsx`
- [Gateway RPC and boot](https://github.com/xdcloudy/hermes-local/blob/main/apps/desktop/src/app/gateway/hooks/use-gateway-boot.ts): WebSocket JSON-RPC client · `apps/desktop/src/app/gateway/hooks/use-gateway-boot.ts`
- [Prompt and stream state](https://github.com/xdcloudy/hermes-local/blob/main/apps/desktop/src/app/session/hooks/use-message-stream/index.ts): session interaction flow · Submits turns and maps streamed events into session, tool, approval, compaction, and message state. · `apps/desktop/src/app/session/hooks/use-message-stream/index.ts`
- [Contribution runtime](https://github.com/xdcloudy/hermes-local/blob/main/apps/desktop/src/contrib/runtime-loader.ts): renderer plugin runtime · Loads registered renderer extensions. · `apps/desktop/src/contrib/runtime-loader.ts`

### Gateway and Agent

The Hermes Agent harness is an external core integration.

- [Local Hermes gateway](https://github.com/xdcloudy/hermes-local/blob/main/scripts/Hermes-Gateway.psm1): loopback gateway · Local-first gateway with DPAPI-protected credentials and loopback-only services. · `scripts/Hermes-Gateway.psm1`
- **Hermes Agent harness**: external agent integration · Pinned or reconstructed external agent core.

### Operations and Delivery

- [Task Centre store](https://github.com/xdcloudy/hermes-local/blob/main/apps/desktop/electron/hermes-local-task-store.ts): desktop task state · Surfaces long-running downloads, benchmarks, backup, scanning, and updates. · `apps/desktop/electron/hermes-local-task-store.ts`
- [Update orchestration](https://github.com/xdcloudy/hermes-local/blob/main/scripts/Hermes-UpdateOrchestrator.psm1): PowerShell update pipeline · Stages and safely activates desktop, runtime, and agent updates. · `scripts/Hermes-UpdateOrchestrator.psm1`
- [Desktop update staging](https://github.com/xdcloudy/hermes-local/blob/main/scripts/desktop-update/DesktopUpdate-Stage.ps1): PowerShell staging step · `scripts/desktop-update/DesktopUpdate-Stage.ps1`
- [Trust Centre](https://github.com/xdcloudy/hermes-local/blob/main/apps/desktop/electron/hermes-local-trust-centre.ts): desktop trust boundary · Applies explicit integration and skill trust contracts. · `apps/desktop/electron/hermes-local-trust-centre.ts`

## Connections

- Setup scripts → Lifecycle control: provisions
- Setup scripts → Runtime manager: installs
- Lifecycle control → Process supervisor: controls
- Process supervisor → Managed jobs: tracks
- Process supervisor → llama.cpp server: owns
- Process supervisor → Hermes Agent harness: owns
- Runtime manager → llama.cpp installer: installs
- llama.cpp installer → Runtime catalog: selects package from
- Runtime manager → GGUF model manifest: verifies
- Runtime manager → Execution profiles: applies
- Execution profiles → llama.cpp server: configures
- GGUF model manifest → llama.cpp server: supplies GGUF
- Electron main → Constrained preload API: exposes
- Constrained preload API → React control centre: constrains IPC for
- React control centre → Gateway RPC and boot: boots
- React control centre → Prompt and stream state: drives
- Prompt and stream state → Gateway RPC and boot: sends turns and receives events
- Gateway RPC and boot → Local Hermes gateway: WebSocket JSON-RPC
- Local Hermes gateway → Hermes Agent harness: routes agent work
- Hermes Agent harness → llama.cpp server: requests inference
- Electron main → Task Centre store: records operations
- Update orchestration → Desktop update staging: stages
- Electron main → Update orchestration: initiates
- Electron main → Trust Centre: enforces
- React control centre → Contribution runtime: loads extensions