# trycua/hermes-cua-spaces architecture

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

- Interactive diagram: https://gitdiagram.com/trycua/hermes-cua-spaces
- Repository: https://github.com/trycua/hermes-cua-spaces

## Overview

Hermes on Cua Spaces is a terminal-environment plugin that runs Hermes commands inside isolated Cua machines. The main flow is Hermes asking the registered provider for an environment; settings and the Cua client determine which Space to use, and that environment runs terminal work remotely and cleans up created Spaces. Additional branches support streamed desktop/browser tools, optional Linux desktop setup, and Windows command and file-tool compatibility. The sampled excerpts show the core calls; some secondary wiring is supported only by the README and source index.

Main entry points: [`hermes_cua_spaces/environment.py`](https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/environment.py) (Terminal environment), [`hermes_cua_spaces/client.py`](https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/client.py) (Spaces client), [`hermes_cua_spaces/__init__.py`](https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/__init__.py) (Provider registration), [`hermes_cua_spaces/desktop.py`](https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/desktop.py) (Desktop stack setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_plugin["Hermes plugin"]
  node_provider["Provider registration<br/>[__init__.py]"]
  node_settings["Settings<br/>[config.py]"]
  node_environment["Terminal environment<br/>[environment.py]"]
  node_errors["Error mapping<br/>[errors.py]"]
end

subgraph group_space["Space lifecycle"]
  node_client["Spaces client<br/>[client.py]"]
  node_loop["Async loop bridge<br/>[_loop.py]"]
  node_cua["Cua SDK"]
  node_space_machine["Cua Space"]
end

subgraph group_tools["Remote tools"]
  node_desktop["Desktop stack setup<br/>[desktop.py]"]
  node_streams["Tool stream bridge<br/>[streams.py]"]
end

subgraph group_platform["Platform support"]
  node_windows["Windows command adapter<br/>[windows.py]"]
  node_windows_setup["Windows prerequisites<br/>[windows_setup.py]"]
end

node_hermes(("Hermes Agent"))
node_hermes_tools(("Desktop and browser tools"))

node_hermes -->|"requests backend"| node_provider
node_provider -->|"creates environment"| node_environment
node_provider -->|"loads settings"| node_settings
node_environment -->|"uses Space client"| node_client
node_environment -->|"uses settings"| node_settings
node_client -->|"runs SDK calls"| node_loop
node_client -->|"creates and controls"| node_cua
node_client -->|"returns handle"| node_space_machine
node_environment -->|"runs remote work"| node_space_machine
node_client -->|"maps SDK errors"| node_errors
node_environment -->|"reports Space errors"| node_errors
node_environment -->|"ensures Linux stack"| node_desktop
node_desktop -->|"checks and installs"| node_space_machine
node_hermes_tools -->|"requests Space streams"| node_streams
node_streams -->|"opens tool stream"| node_space_machine
node_environment -->|"adapts Windows commands"| node_windows
node_environment -->|"installs prerequisites"| node_windows_setup
node_windows_setup -->|"installs Git and Python"| node_space_machine

click node_provider "https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/__init__.py"
click node_settings "https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/config.py"
click node_environment "https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/environment.py"
click node_errors "https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/errors.py"
click node_client "https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/client.py"
click node_loop "https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/_loop.py"
click node_desktop "https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/desktop.py"
click node_streams "https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/streams.py"
click node_windows "https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/windows.py"
click node_windows_setup "https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/windows_setup.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_provider,node_settings,node_environment,node_errors,node_hermes_tools toneBlue
class node_client,node_loop,node_cua,node_space_machine toneAmber
class node_desktop,node_streams toneMint
class node_windows,node_windows_setup toneRose
class node_hermes toneIndigo
```

## Components

### Hermes plugin

- [Provider registration](https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/__init__.py): `hermes_cua_spaces/__init__.py`
- [Settings](https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/config.py): `hermes_cua_spaces/config.py`
- [Terminal environment](https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/environment.py): `hermes_cua_spaces/environment.py`
- [Error mapping](https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/errors.py): `hermes_cua_spaces/errors.py`

### Space lifecycle

- [Spaces client](https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/client.py): `hermes_cua_spaces/client.py`
- [Async loop bridge](https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/_loop.py): `hermes_cua_spaces/_loop.py`
- **Cua SDK**
- **Cua Space**

### Remote tools

- [Desktop stack setup](https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/desktop.py): `hermes_cua_spaces/desktop.py`
- [Tool stream bridge](https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/streams.py): `hermes_cua_spaces/streams.py`

### Platform support

- [Windows command adapter](https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/windows.py): `hermes_cua_spaces/windows.py`
- [Windows prerequisites](https://github.com/trycua/hermes-cua-spaces/blob/main/hermes_cua_spaces/windows_setup.py): `hermes_cua_spaces/windows_setup.py`

### Other components

- **Hermes Agent**
- **Desktop and browser tools**

## Connections

- Hermes Agent → Provider registration: requests backend (evidence: `README.md`)
- Provider registration → Terminal environment: creates environment (evidence: `hermes_cua_spaces/__init__.py`)
- Provider registration → Settings: loads settings (evidence: `hermes_cua_spaces/__init__.py`)
- Terminal environment → Spaces client: uses Space client (evidence: `hermes_cua_spaces/environment.py`)
- Terminal environment → Settings: uses settings (evidence: `hermes_cua_spaces/environment.py`)
- Spaces client → Async loop bridge: runs SDK calls (evidence: `hermes_cua_spaces/client.py`)
- Spaces client → Cua SDK: creates and controls (evidence: `hermes_cua_spaces/client.py`)
- Spaces client → Cua Space: returns handle (evidence: `hermes_cua_spaces/client.py`)
- Terminal environment → Cua Space: runs remote work (evidence: `README.md`)
- Spaces client → Error mapping: maps SDK errors (evidence: `hermes_cua_spaces/client.py`)
- Terminal environment → Error mapping: reports Space errors (evidence: `hermes_cua_spaces/environment.py`)
- Terminal environment → Desktop stack setup: ensures Linux stack (evidence: `hermes_cua_spaces/environment.py`)
- Desktop stack setup → Cua Space: checks and installs (evidence: `hermes_cua_spaces/desktop.py`)
- Desktop and browser tools → Tool stream bridge: requests Space streams (evidence: `README.md`)
- Tool stream bridge → Cua Space: opens tool stream (evidence: `hermes_cua_spaces/streams.py`)
- Terminal environment → Windows command adapter: adapts Windows commands (evidence: `hermes_cua_spaces/environment.py`)
- Terminal environment → Windows prerequisites: installs prerequisites (evidence: `hermes_cua_spaces/environment.py`)
- Windows prerequisites → Cua Space: installs Git and Python (evidence: `hermes_cua_spaces/windows_setup.py`)
