# tasdelenn/hermesos architecture

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

- Interactive diagram: https://gitdiagram.com/tasdelenn/hermesos
- Repository: https://github.com/tasdelenn/hermesos

## Overview

HermesOS is a personal assistant platform whose implemented end-to-end flow accepts a task over the Brain HTTP API, dispatches it to a connected worker, executes an allowlisted capability, and records the result for retrieval. Worker enrollment and authenticated WebSocket sessions support that flow; the shared protocol defines its messages. README-documented long-term knowledge and the Python WebSocket prototype are shown as separate capabilities, but their runtime wiring is not established by the sampled source. The graph emphasizes sampled Rust implementation and omits unsupported links.

Main entry points: [`workers/agent-core/src/client.rs`](https://github.com/tasdelenn/hermesos/blob/master/workers/agent-core/src/client.rs) (Worker client), [`brain/src/lib.rs`](https://github.com/tasdelenn/hermesos/blob/master/brain/src/lib.rs) (WebSocket session), [`brain/src/http.rs`](https://github.com/tasdelenn/hermesos/blob/master/brain/src/http.rs) (HTTP API), [`brain/src/tasks.rs`](https://github.com/tasdelenn/hermesos/blob/master/brain/src/tasks.rs) (Task dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_brain["Brain services"]
  node_brain_main["Brain service<br/>[main.rs]"]
  node_http["HTTP API<br/>[http.rs]"]
  node_task_service["Task dispatch<br/>[tasks.rs]"]
  node_task_registry[("Task registry<br/>[tasks.rs]")]
  node_worker_registry["Worker registry<br/>[registry.rs]"]
  node_ws_session["WebSocket session<br/>[lib.rs]"]
  node_python_prototype["Python WS prototype<br/>[brain-server.py]"]
end

subgraph group_worker["Worker execution"]
  node_worker_main["Worker startup<br/>[main.rs]"]
  node_worker_client["Worker client<br/>[client.rs]"]
  node_worker_state[("Worker credentials<br/>[state.rs]")]
  node_capabilities["Capability registry<br/>[capability.rs]"]
end

subgraph group_protocol["Identity and protocol"]
  node_enrollment["Token enrollment<br/>[enrollment.rs]"]
  node_credentials[("Credential store<br/>[credentials.rs]")]
  node_wire_protocol["Message protocol<br/>[lib.rs]"]
end

subgraph group_knowledge["Knowledge system"]
  node_knowledge_base[("Long-term knowledge")]
end

node_user(("Task requester"))
node_device(("Worker device"))

node_user -->|"submits task"| node_http
node_http -->|"dispatches task"| node_task_service
node_http -->|"lists and reads"| node_task_registry
node_task_service -->|"creates and updates"| node_task_registry
node_task_service -->|"selects and dispatches"| node_worker_registry
node_brain_main -->|"starts API"| node_http
node_brain_main -->|"accepts sessions"| node_ws_session
node_ws_session -->|"consumes tokens"| node_enrollment
node_ws_session -->|"verifies credentials"| node_credentials
node_ws_session -->|"registers workers"| node_worker_registry
node_ws_session -->|"reports results"| node_task_service
node_worker_main -->|"starts client"| node_worker_client
node_worker_client -->|"loads and saves"| node_worker_state
node_worker_client -->|"exchanges messages"| node_ws_session
node_worker_client -->|"executes tasks"| node_capabilities
node_capabilities -->|"returns results"| node_worker_client
node_worker_registry -->|"dispatches task"| node_worker_client
node_worker_client -->|"runs on"| node_device
node_ws_session -->|"uses messages"| node_wire_protocol
node_worker_client -->|"uses messages"| node_wire_protocol

click node_brain_main "https://github.com/tasdelenn/hermesos/blob/master/brain/src/main.rs"
click node_http "https://github.com/tasdelenn/hermesos/blob/master/brain/src/http.rs"
click node_task_service "https://github.com/tasdelenn/hermesos/blob/master/brain/src/tasks.rs"
click node_task_registry "https://github.com/tasdelenn/hermesos/blob/master/brain/src/tasks.rs"
click node_worker_registry "https://github.com/tasdelenn/hermesos/blob/master/brain/src/registry.rs"
click node_ws_session "https://github.com/tasdelenn/hermesos/blob/master/brain/src/lib.rs"
click node_enrollment "https://github.com/tasdelenn/hermesos/blob/master/brain/src/enrollment.rs"
click node_credentials "https://github.com/tasdelenn/hermesos/blob/master/brain/src/credentials.rs"
click node_wire_protocol "https://github.com/tasdelenn/hermesos/blob/master/protocol/src/lib.rs"
click node_worker_main "https://github.com/tasdelenn/hermesos/blob/master/workers/agent-core/src/main.rs"
click node_worker_client "https://github.com/tasdelenn/hermesos/blob/master/workers/agent-core/src/client.rs"
click node_worker_state "https://github.com/tasdelenn/hermesos/blob/master/workers/agent-core/src/state.rs"
click node_capabilities "https://github.com/tasdelenn/hermesos/blob/master/workers/agent-core/src/capability.rs"
click node_knowledge_base "https://github.com/tasdelenn/hermesos/tree/master/knowledge"
click node_python_prototype "https://github.com/tasdelenn/hermesos/blob/master/scripts/brain-server.py"

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_brain_main,node_http,node_task_service,node_task_registry,node_worker_registry,node_ws_session,node_python_prototype toneBlue
class node_worker_main,node_worker_client,node_worker_state,node_capabilities toneAmber
class node_enrollment,node_credentials,node_wire_protocol toneMint
class node_knowledge_base,node_user,node_device toneRose
```

## Components

### Brain services

- [Brain service](https://github.com/tasdelenn/hermesos/blob/master/brain/src/main.rs): `brain/src/main.rs`
- [HTTP API](https://github.com/tasdelenn/hermesos/blob/master/brain/src/http.rs): `brain/src/http.rs`
- [Task dispatch](https://github.com/tasdelenn/hermesos/blob/master/brain/src/tasks.rs): `brain/src/tasks.rs`
- [Task registry](https://github.com/tasdelenn/hermesos/blob/master/brain/src/tasks.rs): `brain/src/tasks.rs`
- [Worker registry](https://github.com/tasdelenn/hermesos/blob/master/brain/src/registry.rs): `brain/src/registry.rs`
- [WebSocket session](https://github.com/tasdelenn/hermesos/blob/master/brain/src/lib.rs): `brain/src/lib.rs`
- [Python WS prototype](https://github.com/tasdelenn/hermesos/blob/master/scripts/brain-server.py): `scripts/brain-server.py`

### Worker execution

- [Worker startup](https://github.com/tasdelenn/hermesos/blob/master/workers/agent-core/src/main.rs): `workers/agent-core/src/main.rs`
- [Worker client](https://github.com/tasdelenn/hermesos/blob/master/workers/agent-core/src/client.rs): `workers/agent-core/src/client.rs`
- [Worker credentials](https://github.com/tasdelenn/hermesos/blob/master/workers/agent-core/src/state.rs): `workers/agent-core/src/state.rs`
- [Capability registry](https://github.com/tasdelenn/hermesos/blob/master/workers/agent-core/src/capability.rs): `workers/agent-core/src/capability.rs`

### Identity and protocol

- [Token enrollment](https://github.com/tasdelenn/hermesos/blob/master/brain/src/enrollment.rs): `brain/src/enrollment.rs`
- [Credential store](https://github.com/tasdelenn/hermesos/blob/master/brain/src/credentials.rs): `brain/src/credentials.rs`
- [Message protocol](https://github.com/tasdelenn/hermesos/blob/master/protocol/src/lib.rs): `protocol/src/lib.rs`

### Knowledge system

- [Long-term knowledge](https://github.com/tasdelenn/hermesos/tree/master/knowledge): `knowledge`

### Other components

- **Task requester**
- **Worker device**

## Connections

- Task requester → HTTP API: submits task
- HTTP API → Task dispatch: dispatches task
- HTTP API → Task registry: lists and reads
- Task dispatch → Task registry: creates and updates
- Task dispatch → Worker registry: selects and dispatches
- Brain service → HTTP API: starts API
- Brain service → WebSocket session: accepts sessions
- WebSocket session → Token enrollment: consumes tokens
- WebSocket session → Credential store: verifies credentials
- WebSocket session → Worker registry: registers workers
- WebSocket session → Task dispatch: reports results
- Worker startup → Worker client: starts client
- Worker client → Worker credentials: loads and saves
- Worker client → WebSocket session: exchanges messages
- Worker client → Capability registry: executes tasks
- Capability registry → Worker client: returns results
- Worker registry → Worker client: dispatches task
- Worker client → Worker device: runs on
- WebSocket session → Message protocol: uses messages
- Worker client → Message protocol: uses messages