Hermes Web UI è l'interfaccia web che rende l'agente autonomo Hermes accessibile direttamente dal browser, con la stessa potenza e le stesse funzionalità della riga di comando ma in un layout a tre pannelli intuitivo. Nessuna build, nessun framework: Python e JavaScript vanilla.

190+
Contributori
comunità open source attiva
7.150+
Test automatici
copertura di affidabilità

Perché Hermes

La maggior parte degli strumenti AI resetta la sessione ogni volta. Non sanno chi sei, su cosa hai lavorato o quali convenzioni segue il tuo progetto. Devi spiegarti ogni volta da capo.

Hermes invece mantiene il contesto tra le sessioni, esegue processi pianificati anche quando sei offline e impara dal tuo ambiente più a lungo rimane attivo. Utilizza la tua configurazione esistente dell'agente Hermes e i tuoi modelli, senza richiedere configurazioni aggiuntive.

Cosa lo differenzia da altri strumenti agentici:

  • Memoria persistente — profilo utente, note dell'agente e un sistema di competenze che salva procedure riutilizzabili; Hermes impara il tuo ambiente e non deve reimpararlo.

  • Pianificazione self-hosted — processi cron che si attivano offline e recapitano risultati su Telegram, Discord, Slack, Signal, email e altri.

  • 10+ piattaforme di messaggistica — lo stesso agente disponibile in terminale è raggiungibile anche dal telefono.

  • Competenze auto-miglioranti — Hermes scrive e salva automaticamente le proprie competenza dall'esperienza; non c'è un marketplace da sfogliare o plugin da installare.

  • Provider-agnostico — supporta OpenAI, Anthropic, Google, DeepSeek, OpenRouter e altri.

  • Orchestra altri agenti — può avviare Claude Code o Codex per compiti di codifica intensivi e riportare i risultati nella propria memoria.

  • Self-hosted — le tue conversazioni, la tua memoria, il tuo hardware.

Confronto con il panorama

OpenClaw

Claude Code

Codex CLI

OpenCode

Hermes

Memoria persistente (automatica)

Parziale†

Parziale

Parziale

Processi pianificati (self-hosted)

No‡

No

No

Accesso app di messaggistica

Sì (15+ piattaforme)

Parziale (anteprima Telegram/Discord)

No

No

Sì (10+)

Web UI (self-hosted)

Solo dashboard

No

No

Competenze auto-miglioranti

Parziale

No

No

No

Ecosistema Python/ML

No (Node.js)

No

No

No

Provider-agnostico

No (solo Claude)

Open source

Sì (MIT)

No

† Claude Code ha contesto progetto CLAUDE.md/MEMORY.md e memoria auto-rolling, ma non recall cross-session automatico completo.
‡ Claude Code ha pianificazione gestita in cloud (infrastruttura Anthropic) e /loop scope-sessione; nessun cron self-hosted.

Il competitor più vicino è OpenClaw — entrambi sono agenti self-hosted, always-on e open source con memoria, cron e messaggistica. Le differenze chiave: Hermes scrive e salva automaticamente le proprie competenze come comportamento principale (il sistema di competenze di OpenClaw ruota attorno a un marketplace della comunità); Hermes è più stabile negli aggiornamenti (OpenClaw ha regressioni documentate nelle release e ClawHub ha avuto incidenti di sicurezza con competenze maligne); e Hermes gira nativamente nell'ecosistema Python.

Avvio rapido

Esegui il bootstrap del repository:

plaintext
git clone https://github.com/nesquena/hermes-webui.git hermes-webui cd hermes-webui python3 bootstrap.py

Oppure continua a usare il launcher shell:

plaintext
./start.sh

Per installazioni su VM self-hosted o homelab, ctl.sh racchiude i comuni comandi del ciclo di vita del demone senza richiedere fuser o pkill:

plaintext
./ctl.sh start # demone in background, PID in ~/.hermes/webui.pid ./ctl.sh status # PID, uptime, host/porta bindata, percorso log, /health ./ctl.sh logs --lines 100 # tail ~/.hermes/webui.log ./ctl.sh restart ./ctl.sh stop

ctl.sh start esegue il bootstrap in modalità foreground/no-browser dietro il wrapper demone, scrive i log in ~/.hermes/webui.log e rispetta .env e gli override inline come HERMES_WEBUI_HOST=0.0.0.0 ./ctl.sh start.

Avanzato: prefill di recall dinamico e chat con Gateway

Due funzionalità opzionali per distribuzioni self-hosted — allegare il prefill di recall sessione dinamico ai turni del browser (router Joplin/Obsidian/Notion/llm-wiki) e instradare la chat del browser attraverso un Hermes Gateway in esecuzione — sono documentate in docs/advanced-chat-setup.md. La maggior parte degli utenti non ne ha bisogno.

Il bootstrap eseguirà:

  1. Rileva Hermes Agent e, se mancante, tenta l'installer ufficiale (curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash).

  2. Trova o crea un ambiente Python con le dipendenze WebUI.

  3. Avvia il server web e attende /health.

  4. Apre il browser a meno che non si passi --no-browser.

  5. Ti porta alla procedura di onboarding iniziale dentro la WebUI.

Una guida community per setup nativo Windows è documentata in @markwang2658/hermes-windows-native-guide (repo companion: @markwang2658/hermes-windows-native). Note dalla community riportate in #1952:

  • Memoria: misurato dalla community ~330 MB nativo vs ~1080 MB con WSL2+Docker (varia per configurazione).

  • Cosa funziona: chat, browser workspace, gestione sessioni, tutti i temi.

  • Limitazioni note: alcuni percorsi file in stile POSIX compaiono nel browser workspace; gli strumenti dell'agente che presumono bash potrebbero non funzionare nativamente.

  • Setup Windows nativo: installa Python 3.11+, poi dalla root di hermes-agent in PowerShell: python -m venv venvpip install -r requirements.txtpwsh .\start.ps1 (auto-scopre venv\Scripts\python.exe).

  • Relazione WSL2: non è prerequisito — un venv costruito in WSL2 (venv/bin/python, ELF) non è invocabile da Python nativo Windows, quindi usa il setup nativo sopra. WSL2 rimane utile come installazione parallela se vuoi il bootstrap completo bootstrap.py + runtime Linux.

Se la configurazione del provider è ancora incompleta dopo l'installazione, la procedura di onboarding ti indicherà di completarla con hermes model invece di cercare di replicare il setup CLI completo nel browser. Per una walkthrough dettagliata della procedura guidata, scelte provider, Base URL di server modelli locali e riesecuzioni sicure, vedi docs/onboarding.md. Se un assistente AI aiuta con installazione, reinstallazione, bootstrap, configurazione provider o supporto al primo avvio, fagli leggere docs/onboarding-agent-checklist.md prima di eseguire comandi o ispezionare log.

Funzionalità

Chat e agente

  • Risposte in streaming via SSE (i token appaiono man mano che sono generati)

  • Supporto modelli multi-provider — qualsiasi provider API Hermes (OpenAI, Anthropic, Google, DeepSeek, Nous Portal, OpenRouter, MiniMax, Xiaomi MiMo, Z.AI); menu a discesa modelli popolato dinamicamente dalle chiavi configurate

  • Invio un messaggio mentre uno è in elaborazione — viene accodato automaticamente

  • Modifica inline qualsiasi messaggio utente passato e rigenera da quel punto

  • Riprova l'ultima risposta dell'assistente con un clic

  • Annulla un'attività in esecuzione direttamente dal footer del composer (pulsante Stop accanto a Invia)

  • Card delle chiamate strumento inline — ciascuna mostra nome strumento, args e snippet risultato; toggle espandi/comprimi tutto per turni multi-strumento

  • Card di delega subagent — attività dell'agente figlio mostrate con icona distinta e bordo rientrato

  • Render inline diagrammi Mermaid (flowchart, sequence diagram, gantt chart)

  • Visualizzazione reasoning/pensiero — card a tema oro collassabili per extended thinking Claude e blocchi reasoning o3

  • Card di approvazione per comandi shell pericolosi (allow once/session/always/deny)

  • Auto-reconnect SSE su brevi interruzioni di rete (resilienza tunnel SSH)

  • Gli allegati file persistono tra ricariche pagina e sono memorizzati per default fuori dal workspace attivo (~/.hermes/webui/attachments/<session_id>/, o HERMES_WEBUI_ATTACHMENT_DIR/<session_id>/ se configurato)

  • Timestamp messaggio (HH:MM accanto a ogni messaggio, data completa all'hover)

  • Pulsante copia blocco codice con feedback "Copiato!"

  • Evidenziazione sintassi via Prism.js (Python, JS, bash, JSON, SQL e altri)

  • Render HTML sicuro nelle risposte AI (bold, italic, code convertiti in markdown)

  • Streaming token con throttle rAF per rendering più fluido durante risposte lunghe

  • Indicatore utilizzo contesto nel footer composer — conteggio token, costo e barra di riempimento (model-aware)

Sessioni

  • Creare, rinominare, duplicare, eliminare, cercare per titolo e contenuto messaggio

  • Azioni sessione via menu per sessione — pin, sposta in progetto, archivia, duplica, elimina

  • Pin/star sessioni in cima alla sidebar (indicatore oro)

  • Archivia sessioni (nasconde senza eliminare, toggle per mostrare)

  • Progetti sessione — gruppi nominati con colori per organizzare sessioni

  • Tag sessione — aggiungi #tag ai titoli per chip colorati e click-to-filter

  • Raggruppate per Oggi/Ieri/Prime nella sidebar (gruppi data collassabili)

  • Download come trascrizione Markdown, export JSON completo, o import da JSON

  • Le sessioni persistono tra ricariche pagina e riconnessioni tunnel SSH

  • Il titolo della scheda browser riflette il nome della sessione attiva

  • Bridge sessione CLI — le sessioni CLI dall'SQLite store di hermes-agent appaiono nella sidebar con badge oro "cli"; clicca per importare con cronologia completa e rispondi normalmente

  • Visualizzazione token/costo — token input, token output, costo stimato mostrati per conversazione (toggle in Impostazioni o comando /usage)

Browser workspace file

  • Albero directory con expand/collapse (singolo clic per toggle, doppio clic per navigare)

  • Navigazione breadcrumb con segmenti percorso cliccabili

  • Anteprima inline di testo, codice, Markdown (renderizzato) e immagini

  • Link chat usando workspace://path/to/file aprono file nel pannello preview destra

  • Modifica, crea, elimina e rinomina file; crea cartelle

  • Download file binario (auto-rilevato dal server)

  • Anteprima file si auto-chiude alla navigazione directory (con guardia modifica non salvata)

  • Rilevamento Git — nome branch e badge conteggio file dirty nell'header workspace

  • Il pannello destro è ridimensionabile con drag

  • Anteprima codice con evidenziazione sintassi (Prism.js)

Input vocale

  • Pulsante microfono nel composer (Web Speech API)

  • Tocca per registrare, tocca di nuovo o invia per fermare

  • Trascrizione interima live appare nella textarea

  • Auto-stop dopo ~2s di silenzio

  • Si aggiunge al contenuto textarea esistente (non sostituisce)

  • Nascosto se il browser non supporta Web Speech API (Chrome, Edge, Safari)

Profili

  • Chip profilo nel footer composer — dropdown che mostra tutti i profili con stato gateway e info modello

  • Punti stato gateway (verde = in esecuzione), info modello, conteggio competenze per profilo

  • Pannello gestione profili — crea, cambia e elimina profili dalla sidebar

  • Clona config dal profilo attivo alla creazione

  • Campi endpoint personalizzati opzionali alla creazione — Base URL e API key scritti nel config.yaml del profilo al momento della creazione, così Ollama, LMStudio e altri endpoint locali possono essere configurati senza modificare file manualmente

  • Switch seamless — nessun restart server; ricarica config, competenze, memoria, cron, modelli

  • Tracciamento profilo per-sessione (registra quale profilo era attivo alla creazione)

Autenticazione e sicurezza

  • Auth password opzionale — disabilitato di default, zero attrito per localhost

  • Abilita via variabile d'ambiente HERMES_WEBUI_PASSWORD o pannello Impostazioni

  • Passkeys/WebAuthn opzionali — registra da Impostazioni -> Sistema dopo login con password; la pagina login mostra solo login passkey dopo che almeno una passkey esiste

  • Dopo aver registrato almeno una passkey, Impostazioni -> Sistema può rimuovere la password e mantenere abilitato il solo login passkey; l'auth password rimane il percorso bootstrap/recupero finché non scegli di andare passwordless; le passkey sono same-origin e memorizzate localmente nella directory stato WebUI

  • Cookie HTTP-only firmato HMAC con TTL 24h

  • Pagina login minimal a tema scuro a /login

  • Header di sicurezza su tutte le risposte (X-Content-Type-Options, X-Frame-Options, Referrer-Policy)

  • Limite dimensione corpo POST 20MB

  • Risorse CDN pinnate con hash integrità SRI

Temi

  • L'aspetto è diviso in due assi: Tema (system, dark, light) e Skin (default, ares, mono, slate, poseidon, sisyphus, charizard, sienna, catppuccin, nous, geist-contrast / Geist Contrast)

  • Switch via Impostazioni -> Aspetto (anteprima live istantanea) o /theme <theme-or-skin>

  • Persiste tra ricariche (server-side in settings.json + localStorage per caricamento senza flicker)

  • Le Skin usano data-skin più variabili CSS; la modalità scura si risolve tramite classe .dark, non un asse tema custom data-theme — vedi THEMES.md

Impostazioni e configurazione

  • Hermes Control Center (pulsante launcher sidebar) — tab Conversazione (export/import/clear), tab Preferenze (modello, tasto invio, tema, lingua, tutti i toggle), tab Sistema (versione, password)

  • Tasto invio: Enter (default) o Ctrl/Cmd+Enter

  • Toggle mostra/nascondi sessioni CLI (abilitato di default)

  • Toggle visualizzazione utilizzo token (off di default, anche via comando /usage)

  • Control Center si apre sempre sul tab Conversazione; si resetta alla chiusura

  • Guardia modifiche non salvate — prompt scarta/salva alla chiusura con modifiche non persistenti

  • Alert completamento cron — notifiche toast e badge non letto sul tab Attività

  • Alert errori agente in background — banner quando una sessione non attiva incontra un errore

Comandi slash

  • Digita / nel composer per dropdown autocomplete

  • Built-in: /help, /clear, /compress [focus topic], /compact (alias), /model <name>, /workspace <name>, /new, /usage, /theme

  • Freccia naviga, Tab/Enter seleziona, Escape chiude

  • Comandi non riconosciuti passano through all'agente

Pannelli

  • Chat — lista sessioni, ricerca, pin, archivio, progetti, nuova conversazione

  • Attività — visualizza, crea, modifica, esegui, pausa/ripresa, elimina processi cron; cronologia esecuzioni; alert completamento

  • Competenze — lista tutte le competenze per categoria, ricerca, anteprima, crea/modifica/elimina; visualizzatore file collegati

  • Memoria — visualizza e modifica MEMORY.md e USER.md inline

  • Profili — crea, cambia, elimina profili agente; clona config

  • Todos — lista attività live dalla sessione corrente

  • Spazi — aggiungi, rinomina, rimuovi workspace; quick-switch dalla topbar

Responsivo mobile

  • Sidebar a hamburger — overlay a scorrimento sul mobile (<640px)

  • Schede top sidebar rimangono disponibili sul mobile; nessun nav fixed inferiore che ruba altezza chat

  • Pannello file a scorrimento dal bordo destro

  • Target touch minimi 44px su tutti gli elementi interattivi

  • Chat/composer a altezza piena sui telefoni senza spaziatura nav-inferiore

  • Layout desktop completamente invariato

Configurazione e accesso

start.sh auto-scopre quasi tutto; le sottosezioni下面 coprono i knob per quando non può, e come raggiungere la UI da remoto.

Cosa start.sh scopre automaticamente

Cosa

Come lo trova

Directory agente Hermes

Variabile d'ambiente HERMES_WEBUI_AGENT_DIR, poi $HERMES_HOME/hermes-agent (default Windows %LOCALAPPDATA%\hermes\hermes-agent, default POSIX ~/.hermes/hermes-agent), poi sibling ../hermes-agent

Python eseguibile

Prima venv agente, poi .venv in questo repo, poi system python3

Directory stato

Variabile d'ambiente HERMES_WEBUI_STATE_DIR, poi $HERMES_HOME/webui (default Windows %LOCALAPPDATA%\hermes\webui, default POSIX ~/.hermes/webui)

Workspace default

Variabile d'ambiente HERMES_WEBUI_DEFAULT_WORKSPACE, poi ~/workspace, poi directory stato

Porta

Variabile d'ambiente HERMES_WEBUI_PORT o primo argomento, default 8787

Se la scoperta trova tutto, non serve altro.

Override (solo se l'auto-scoperta fallisce)

plaintext
export HERMES_WEBUI_AGENT_DIR=/path/to/hermes-agent export HERMES_WEBUI_PYTHON=/path/to/python export HERMES_WEBUI_PORT=9000 export HERMES_WEBUI_AUTO_INSTALL=1 # abilita auto-install dipendenze agente (disabilitato di default) ./start.sh

Oppure inline:

plaintext
HERMES_WEBUI_AGENT_DIR=/custom/path ./start.sh 9000

Lista completa variabili d'ambiente:

Variabile

Default

Descrizione

HERMES_WEBUI_AGENT_DIR

auto-scoperta

Percorso del checkout hermes-agent

HERMES_WEBUI_PYTHON

auto-scoperta

Eseguibile Python

HERMES_WEBUI_HOST

127.0.0.1

Indirizzo bind (0.0.0.0 per tutti IPv4, :: per tutti IPv6, ::1 per IPv6 loopback)

HERMES_WEBUI_PORT

8787

Porta

HERMES_WEBUI_STATE_DIR

$HERMES_HOME/webui (default Windows %LOCALAPPDATA%\hermes\webui, default POSIX ~/.hermes/webui)

Dove sessioni e stato sono memorizzati

HERMES_WEBUI_DEFAULT_WORKSPACE

~/workspace

Workspace default

HERMES_WEBUI_DEFAULT_MODEL

(default provider)

Override modello opzionale; lascia non settato per usare il default del provider Hermes attivo

HERMES_WEBUI_PASSWORD

(non settato)

Imposta per abilitare autenticazione password

HERMES_WEBUI_CSP_CONNECT_EXTRA

(non settato)

Origini http(s):// o ws(s):// separate da spazi da aggiungere alla direttiva CSP report-only connect-src per deploy reverse-proxy o tunnel

HERMES_WEBUI_EXTENSION_DIR

(non settato)

Directory locale opzionale servita a /extensions/; deve puntare a una directory esistente prima che l'iniezione estensione sia abilitata

HERMES_WEBUI_EXTENSION_SCRIPT_URLS

(non settato)

URL script same-origin separati da virgola opzionali da iniettare; vedi docs/EXTENSIONS.md

HERMES_WEBUI_EXTENSION_STYLESHEET_URLS

(non settato)

URL stylesheet same-origin separati da virgola opzionali da iniettare; vedi docs/EXTENSIONS.md

HERMES_HOME

Windows: %LOCALAPPDATA%\hermes; POSIX: ~/.hermes

Directory base per stato Hermes (affetta tutti i percorsi)

HERMES_CONFIG_PATH

$HERMES_HOME/config.yaml

Percorso file config Hermes

Accesso remoto (SSH tunnel, Tailscale, telefono)

Il server si binda a 127.0.0.1 di default. Per raggiungerlo da un'altra macchina usa un tunnel SSH (ssh -N -L 8787:127.0.0.1:8787 user@host, che start.sh stampa per te via SSH), o unisci il tuo server e il telefono a una rete Tailscale e naviga a http://<server-tailscale-ip>:8787 con HERMES_WEBUI_HOST=0.0.0.0 + HERMES_WEBUI_PASSWORD settati. Walkthrough completo (incl. un field report community ARM64-Android): docs/remote-access.md.

Lancio manuale (senza start.sh)

Se preferisci avviare il server direttamente:

plaintext
cd /path/to/hermes-agent # o dove sys.path può trovare moduli Hermes HERMES_WEBUI_PORT=8787 venv/bin/python /path/to/hermes-webui/server.py

Nota: usa il Python della venv agente (o qualsiasi ambiente Python che abbia le dipendenze dell'agente Hermes installate). Il Python di sistema mancherà di openai, httpx e altri pacchetti richiesti.

Health check:

plaintext
curl http://127.0.0.1:8787/health

Docker

Immagini pre-build (amd64 + arm64) sono pubblicate su GHCR a ogni release.

Per una guida di setup completa che copre tutti e 3 i file compose, modalità di fallimento comuni e migrazione bind-mount, vedi docs/docker.md. Il README copre il percorso felice di 5 minuti.

Quickstart 5 minuti (singolo container)

Il setup più semplice: un container WebUI che esegue l'agente in-process.

plaintext
git clone https://github.com/nesquena/hermes-webui cd hermes-webui cp .env.docker.example .env # Modifica .env se il tuo host UID non è 1000 (es. macOS dove gli UID partono da 501) docker compose up -d # Apri http://localhost:8787

Esegui Compose come l'utente che possiede la tua Hermes home. sudo docker compose up -d può far espandere ${HOME} alla home dell'utente root, così Docker monta la directory .hermes sbagliata invece della tua vera ~/.hermes e la WebUI parte con config.yaml (not found, using defaults). Preferisci aggiungere il tuo utente al gruppo Docker e eseguire docker compose up -d; se devi usare sudo, imposta prima percorsi assoluti, per esempio HERMES_HOME=/home/you/.hermes HERMES_WORKSPACE=/home/you/workspace sudo -E docker compose up -d, poi verifica con docker compose config.

Il container auto-scopre il tuo UID/GID dal volume ~/.hermes montato così i file scritti dall'agente rimangono leggibili da te sull'host.

Per abilitare protezione password (richiesta se esponi la porta fuori 127.0.0.1):

plaintext
echo "HERMES_WEBUI_PASSWORD=change-me-to-something-strong" >> .env docker compose up -d --force-recreate

docker run manuale (no compose)

plaintext
docker pull ghcr.io/nesquena/hermes-webui:latest docker run -d \ -e WANTED_UID=$(id -u) -e WANTED_GID=$(id -g) \ -v ~/.hermes:/home/hermeswebui/.hermes \ -e HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui \ -v ~/workspace:/workspace \ -p 127.0.0.1:8787:8787 \ ghcr.io/nesquena/hermes-webui:latest

Build locale

plaintext
docker build -t hermes-webui . docker run -d \ -e WANTED_UID=$(id -u) -e WANTED_GID=$(id -g) \ -v ~/.hermes:/home/hermeswebui/.hermes \ -e HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui \ -v ~/workspace:/workspace \ -p 127.0.0.1:8787:8787 \ hermes-webui

Setup multi-container

Se vuoi agente e WebUI in container separati (per isolamento, o perché hai già un gateway agente altrove):

plaintext
# Agente + WebUI docker compose -f docker-compose.two-container.yml up -d # Agente + Dashboard + WebUI docker compose -f docker-compose.three-container.yml up -d

Entrambi i file compose usano volumi Docker nominati di default, il che risolve il problema UID/GID per costruzione. Se hai bisogno di bind mount per condividere una directory host esistente, vedi docs/docker.md per la ricetta completa di migrazione.

Modalità di fallimento comuni

Sintomo

Causa probabile

Fix

PermissionError all'avvio

UID mismatch su bind mount

Imposta UID=$(id -u) in .env

.env: permission denied (#1389)

fix_credential_permissions() ha imposto 0600

Imposta HERMES_SKIP_CHMOD=1 in .env

Workspace appare vuoto

UID mismatch su mount /workspace

Imposta UID=$(id -u) in .env

git: command not found nella chat

Limite architetturale two-container (#681)

Usa single-container o estendi Dockerfile

WebUI non trova sorgente agente

Volume hermes-agent-src malconfigurato

Usa i volumi nominati dai file compose così come sono

Podman condiviso .hermes fallisce

Limitazione Podman 3.4 keep-id

Usa Podman 4+ o single-container

API host a localhost fallisce dalla WebUI

localhost container significa il container, non il tuo host (#3012)

Usa http://host.docker.internal:<port> su Docker Desktop, o http://host.containers.internal:<port> su Podman

WebUI non vede ~/.hermes dopo sudo docker compose

${HOME} espanso alla home dell'utente root (#3006)

Esegui Compose come tuo utente, o passa HERMES_HOME/HERMES_WORKSPACE assoluti con sudo -E

Per il deep dive su ciascuno, vedi docs/docker.md.

Esecuzione test

I test scoprono il repo e l'agente Hermes dinamicamente — nessun percorso hardcoded.

plaintext
cd hermes-webui pytest tests/ -v --timeout=60

Oppure usando esplicitamente la venv agente:

plaintext
/path/to/hermes-agent/venv/bin/python -m pytest tests/ -v

I test girano contro un server isolato con una directory stato separata. I dati di produzione e i cron reali non vengono mai toccati. Snapshot corrente: ~7.150 test raccolti su ~700 file di test, eseguiti in CI su Python 3.11, 3.12 e 3.13 (3 shard paralleli ciascuno).

Architettura

Nessuna build, nessun framework, nessun bundler — un server HTTP Python standard library e JavaScript vanilla. Il backend risiede in api/, il frontend in static/.

Backend (api/)

plaintext
server.py HTTP routing shell + auth middleware api/ auth.py Optional password authentication, signed cookies, passkeys config.py Discovery, globals, model detection, reloadable config helpers.py HTTP helpers, security headers models.py Session model + CRUD + CLI/state.db bridge onboarding.py First-run onboarding wizard, OAuth provider support profiles.py Profile state management, hermes_cli wrapper routes.py All GET + POST route handlers (if/elif dispatch, no decorators) state_sync.py /insights sync — message_count to state.db streaming.py SSE engine, run_agent, cancellation, compression updates.py Self-update check and release notes upload.py Multipart parser, file upload handler workspace.py File ops, workspace helpers, git detection

Frontend (static/)

plaintext
index.html HTML template style.css All CSS incl. mobile responsive, themes + skins ui.js DOM helpers, renderMd, tool cards, context indicator workspace.js File preview, file ops, git badge, central api() fetch wrapper sessions.js Session CRUD, collapsible groups, search, reload recovery messages.js send(), SSE handlers, live streaming, session recovery panels.js Cron, skills, memory, profiles, settings (Control Center) commands.js Slash command autocomplete boot.js Mobile nav, voice input, theme/skin boot, bfcache handler

Test + packaging

plaintext
tests/ Pytest suite (~7,150 tests; isolated server/state fixtures) pyproject.toml Tooling config (ruff lint gate) — not a packaged distribution Dockerfile python:3.12-slim container image docker-compose.yml Compose with named volume and optional auth .github/workflows/ CI: ruff + sharded pytest, browser smoke, Docker smoke, multi-arch Docker build + GitHub Release on tag

Lo stato vive fuori dal repo a ~/.hermes/webui/ di default (sessioni, workspace, impostazioni, progetti, last_workspace). Override con HERMES_WEBUI_STATE_DIR. Note di progettazione complete e catalogo endpoint in ARCHITECTURE.md.

Documentazione

Inizia qui

  • docs/why-hermes.md — perché Hermes, il modello mentale e confronto dettagliato con Claude Code / Codex / OpenCode / Cursor

  • docs/onboarding.md — procedura guidata primo avvio, setup provider, Base URL server modelli locali, Riesecuzioni sicure

  • docs/troubleshooting.md — flussi diagnostici per fallimenti comuni (es. "AIAgent not available")

Utilizzo e personalizzazione

  • THEMES.md — sistema tema + skin, guida tema custom

  • docs/workspace-git.md — controlli Git del workspace

  • docs/EXTENSIONS.md — iniezione estensione WebUI controllata dall'amministratore

Deploy e operazioni

  • docs/remote-access.md — SSH tunnel, Tailscale e accesso telefono (incl. field report community ARM64-Android)

  • docs/advanced-chat-setup.md — opzionale prefill recall dinamico e chat con Gateway-backed per deploy self-hosted

  • docs/docker.md — setup Docker compose, fallimenti comuni e migrazione bind-mount

  • docs/supervisor.md — setup supervisor processi: launchd, systemd, supervisord, runit, s6

  • docs/wsl-autostart.md — auto-avvio WSL2 all'accesso Windows

  • docs/onboarding-agent-checklist.md — regole di sicurezza e controlli pass/fail per supporto installazione guidata da assistente

Contribuzione e progettazione

  • CONTRIBUTING.md — stile contribuzione, aspettative PR, verifica locale

  • ARCHITECTURE.md — progettazione sistema, tutti gli endpoint API, note implementazione

  • TESTING.md — piano test browser manuale e riferimento copertura automatizzata

  • DESIGN.md — token di progettazione e direzione calm-console

  • docs/UIUX-GUIDE.md — principi UI/UX derivati dai documenti di progettazione e inventory visuali

  • docs/CONTRACTS.md — indice contratto/progetto/RFC per contributori e agenti

  • docs/rfcs/README.md — indice RFC per proposte architetturali e di durabilità più grandi

Storia release e piano

  • CHANGELOG.md — note di rilascio per versione

  • ROADMAP.md — feature roadmap e storia sprint

  • SPRINTS.md — piano sprint in avanti con obiettivi parity CLI + Claude

  • CONTRIBUTORS.md — crediti completi comunità

Contributori

Hermes WebUI è costruito con l'aiuto della comunità open source. Ogni PR — che sia mergiato direttamente, assorbito in un batch release, o recuperato da una proposta più grande — plasma il progetto, e siamo grati a tutti coloro che hanno dedicato tempo a contribuire.

Oltre 190 contributori hanno spedito codice atterrato in un release tag. Il credit roll completo, continuamente aggiornato — include tutti con una o due PR e il roll special-thanks per progettazione e lavoro architetturale — vive in CONTRIBUTORS.md.

Repository

plaintext
git@github.com:nesquena/hermes-webui.git
Il nostro verdetto
4.7/ 5

FAQ

Fonti e riferimenti

  1. Repository principale Hermes WebUI
  2. Documentazione ufficiale (docs/)
  3. Hermes Agent repository
  4. Immagini Docker GHCR