---
title: "Hermes Web UI: Interfaccia Web per l'Agente AI Autonomo e Self-Hosted"
date: "2026-06-01"
category: "Sviluppo Software"
tags: ["agente-autonomo", "hermes-ai", "intelligenza artificiale", "self-hosted", "web-ui"]
author: "Giuseppe Carruezzo"
description: "Scopri Hermes Web UI: l'interfaccia intuitiva a tre pannelli per l'agente AI Hermes. Memoria persistente, supporto multi-provider e gestione self-hosted."
source: "https://ainsights.it/blog/hermes-web-ui-interfaccia-ai-autonoma"
---

# Hermes Web UI: Interfaccia Web per l'Agente AI Autonomo e Self-Hosted

![Hermes Web UI: Interfaccia Web per l'Agente AI Autonomo e Self-Hosted](/blogai/backend/uploads/6a1dc0f1d9edc.webp)

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.
    

Il panorama è in rapida evoluzione. Per un confronto dettagliato, vedi `docs/why-hermes.md`.

### Confronto con il panorama

<table style="min-width: 150px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p></p></th><th colspan="1" rowspan="1"><p>OpenClaw</p></th><th colspan="1" rowspan="1"><p>Claude Code</p></th><th colspan="1" rowspan="1"><p>Codex CLI</p></th><th colspan="1" rowspan="1"><p>OpenCode</p></th><th colspan="1" rowspan="1"><p>Hermes</p></th></tr><tr><td colspan="1" rowspan="1"><p>Memoria persistente (automatica)</p></td><td colspan="1" rowspan="1"><p>Sì</p></td><td colspan="1" rowspan="1"><p>Parziale†</p></td><td colspan="1" rowspan="1"><p>Parziale</p></td><td colspan="1" rowspan="1"><p>Parziale</p></td><td colspan="1" rowspan="1"><p>Sì</p></td></tr><tr><td colspan="1" rowspan="1"><p>Processi pianificati (self-hosted)</p></td><td colspan="1" rowspan="1"><p>Sì</p></td><td colspan="1" rowspan="1"><p>No‡</p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>Sì</p></td></tr><tr><td colspan="1" rowspan="1"><p>Accesso app di messaggistica</p></td><td colspan="1" rowspan="1"><p>Sì (15+ piattaforme)</p></td><td colspan="1" rowspan="1"><p>Parziale (anteprima Telegram/Discord)</p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>Sì (10+)</p></td></tr><tr><td colspan="1" rowspan="1"><p>Web UI (self-hosted)</p></td><td colspan="1" rowspan="1"><p>Solo dashboard</p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>Sì</p></td><td colspan="1" rowspan="1"><p>Sì</p></td></tr><tr><td colspan="1" rowspan="1"><p>Competenze auto-miglioranti</p></td><td colspan="1" rowspan="1"><p>Parziale</p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>Sì</p></td></tr><tr><td colspan="1" rowspan="1"><p>Ecosistema Python/ML</p></td><td colspan="1" rowspan="1"><p>No (Node.js)</p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>Sì</p></td></tr><tr><td colspan="1" rowspan="1"><p>Provider-agnostico</p></td><td colspan="1" rowspan="1"><p>Sì</p></td><td colspan="1" rowspan="1"><p>No (solo Claude)</p></td><td colspan="1" rowspan="1"><p>Sì</p></td><td colspan="1" rowspan="1"><p>Sì</p></td><td colspan="1" rowspan="1"><p>Sì</p></td></tr><tr><td colspan="1" rowspan="1"><p>Open source</p></td><td colspan="1" rowspan="1"><p>Sì (MIT)</p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>Sì</p></td><td colspan="1" rowspan="1"><p>Sì</p></td><td colspan="1" rowspan="1"><p>Sì</p></td></tr></tbody></table>

† 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.
    

Il bootstrap nativo Windows non è ancora supportato. Usa Linux, macOS o WSL2. Per auto-avvio all'accesso in Windows/WSL, vedi `docs/wsl-autostart.md`.

Una guida community per setup nativo Windows è documentata in [@markwang2658/hermes-windows-native-guide](https://github.com/markwang2658/hermes-windows-native-guide) (repo companion: [@markwang2658/hermes-windows-native](https://github.com/markwang2658/hermes-windows-native)). Note dalla community riportate in [#1952](https://github.com/nesquena/hermes-webui/issues/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 venv` → `pip install -r requirements.txt` → `pwsh .\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

<table style="min-width: 250px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p></p></th><th colspan="1" rowspan="1"><p></p></th><th colspan="1" rowspan="1"><p></p></th><th colspan="1" rowspan="1"><p></p></th><th colspan="1" rowspan="1"><p></p></th><th colspan="1" rowspan="1"><p></p></th><th colspan="1" rowspan="1"><p></p></th><th colspan="1" rowspan="1"><p></p></th><th colspan="1" rowspan="1"><p>Cosa</p></th><th colspan="1" rowspan="1"><p>Come lo trova</p></th></tr><tr><td colspan="1" rowspan="1"><p>Directory agente Hermes</p></td><td colspan="1" rowspan="1"><p>Variabile d'ambiente <code>HERMES_WEBUI_AGENT_DIR</code>, poi <code>$HERMES_HOME/hermes-agent</code> (default Windows <code>%LOCALAPPDATA%\hermes\hermes-agent</code>, default POSIX <code>~/.hermes/hermes-agent</code>), poi sibling <code>../hermes-agent</code></p></td><td colspan="1" rowspan="1"><p>Python eseguibile</p></td><td colspan="1" rowspan="1"><p>Prima venv agente, poi <code>.venv</code> in questo repo, poi system <code>python3</code></p></td><td colspan="1" rowspan="1"><p>Directory stato</p></td><td colspan="1" rowspan="1"><p>Variabile d'ambiente <code>HERMES_WEBUI_STATE_DIR</code>, poi <code>$HERMES_HOME/webui</code> (default Windows <code>%LOCALAPPDATA%\hermes\webui</code>, default POSIX <code>~/.hermes/webui</code>)</p></td><td colspan="1" rowspan="1"><p>Workspace default</p></td><td colspan="1" rowspan="1"><p>Variabile d'ambiente <code>HERMES_WEBUI_DEFAULT_WORKSPACE</code>, poi <code>~/workspace</code>, poi directory stato</p></td><td colspan="1" rowspan="1"><p>Porta</p></td><td colspan="1" rowspan="1"><p>Variabile d'ambiente <code>HERMES_WEBUI_PORT</code> o primo argomento, default <code>8787</code></p></td></tr></tbody></table>

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:

<table style="min-width: 75px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p>Variabile</p></th><th colspan="1" rowspan="1"><p>Default</p></th><th colspan="1" rowspan="1"><p>Descrizione</p></th></tr><tr><td colspan="1" rowspan="1"><p><code>HERMES_WEBUI_AGENT_DIR</code></p></td><td colspan="1" rowspan="1"><p>auto-scoperta</p></td><td colspan="1" rowspan="1"><p>Percorso del checkout hermes-agent</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>HERMES_WEBUI_PYTHON</code></p></td><td colspan="1" rowspan="1"><p>auto-scoperta</p></td><td colspan="1" rowspan="1"><p>Eseguibile Python</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>HERMES_WEBUI_HOST</code></p></td><td colspan="1" rowspan="1"><p><code>127.0.0.1</code></p></td><td colspan="1" rowspan="1"><p>Indirizzo bind (<code>0.0.0.0</code> per tutti IPv4, <code>::</code> per tutti IPv6, <code>::1</code> per IPv6 loopback)</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>HERMES_WEBUI_PORT</code></p></td><td colspan="1" rowspan="1"><p><code>8787</code></p></td><td colspan="1" rowspan="1"><p>Porta</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>HERMES_WEBUI_STATE_DIR</code></p></td><td colspan="1" rowspan="1"><p><code>$HERMES_HOME/webui</code> (default Windows <code>%LOCALAPPDATA%\hermes\webui</code>, default POSIX <code>~/.hermes/webui</code>)</p></td><td colspan="1" rowspan="1"><p>Dove sessioni e stato sono memorizzati</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>HERMES_WEBUI_DEFAULT_WORKSPACE</code></p></td><td colspan="1" rowspan="1"><p><code>~/workspace</code></p></td><td colspan="1" rowspan="1"><p>Workspace default</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>HERMES_WEBUI_DEFAULT_MODEL</code></p></td><td colspan="1" rowspan="1"><p><em>(default provider)</em></p></td><td colspan="1" rowspan="1"><p>Override modello opzionale; lascia non settato per usare il default del provider Hermes attivo</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>HERMES_WEBUI_PASSWORD</code></p></td><td colspan="1" rowspan="1"><p><em>(non settato)</em></p></td><td colspan="1" rowspan="1"><p>Imposta per abilitare autenticazione password</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>HERMES_WEBUI_CSP_CONNECT_EXTRA</code></p></td><td colspan="1" rowspan="1"><p><em>(non settato)</em></p></td><td colspan="1" rowspan="1"><p>Origini <code>http(s)://</code> o <code>ws(s)://</code> separate da spazi da aggiungere alla direttiva CSP report-only <code>connect-src</code> per deploy reverse-proxy o tunnel</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>HERMES_WEBUI_EXTENSION_DIR</code></p></td><td colspan="1" rowspan="1"><p><em>(non settato)</em></p></td><td colspan="1" rowspan="1"><p>Directory locale opzionale servita a <code>/extensions/</code>; deve puntare a una directory esistente prima che l'iniezione estensione sia abilitata</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>HERMES_WEBUI_EXTENSION_SCRIPT_URLS</code></p></td><td colspan="1" rowspan="1"><p><em>(non settato)</em></p></td><td colspan="1" rowspan="1"><p>URL script same-origin separati da virgola opzionali da iniettare; vedi <code>docs/EXTENSIONS.md</code></p></td></tr><tr><td colspan="1" rowspan="1"><p><code>HERMES_WEBUI_EXTENSION_STYLESHEET_URLS</code></p></td><td colspan="1" rowspan="1"><p><em>(non settato)</em></p></td><td colspan="1" rowspan="1"><p>URL stylesheet same-origin separati da virgola opzionali da iniettare; vedi <code>docs/EXTENSIONS.md</code></p></td></tr><tr><td colspan="1" rowspan="1"><p><code>HERMES_HOME</code></p></td><td colspan="1" rowspan="1"><p>Windows: <code>%LOCALAPPDATA%\hermes</code>; POSIX: <code>~/.hermes</code></p></td><td colspan="1" rowspan="1"><p>Directory base per stato Hermes (affetta tutti i percorsi)</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>HERMES_CONFIG_PATH</code></p></td><td colspan="1" rowspan="1"><p><code>$HERMES_HOME/config.yaml</code></p></td><td colspan="1" rowspan="1"><p>Percorso file config Hermes</p></td></tr></tbody></table>

### 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](https://tailscale.com) 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.

**Limitazione nota (#681)**: nel setup two-container, gli strumenti触发ati dalla WebUI girano nel **container WebUI**, non nel container agente. Se ti servono git/node/etc. sul filesystem della WebUI, usa il setup single-container, estendi il Dockerfile della WebUI, o usa la community [immagine all-in-one](https://github.com/sunnysktsang/hermes-suite).

**Nota confine sorgente (#2453)**: il setup multi-container monta `hermes-agent-src` read-only nella WebUI di default. Questo previene riscritture sorgente lato WebUI ma è ancora un bridge di accoppiamento implementazione, non un confine API Agente stabile. Vedi `docs/rfcs/agent-source-boundary.md` per l'inventario corrente di decoupling sorgente/API.

### Modalità di fallimento comuni

<table style="min-width: 75px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p>Sintomo</p></th><th colspan="1" rowspan="1"><p>Causa probabile</p></th><th colspan="1" rowspan="1"><p>Fix</p></th></tr><tr><td colspan="1" rowspan="1"><p><code>PermissionError</code> all'avvio</p></td><td colspan="1" rowspan="1"><p>UID mismatch su bind mount</p></td><td colspan="1" rowspan="1"><p>Imposta <code>UID=$(id -u)</code> in <code>.env</code></p></td></tr><tr><td colspan="1" rowspan="1"><p><code>.env: permission denied</code> (#1389)</p></td><td colspan="1" rowspan="1"><p><code>fix_credential_permissions()</code> ha imposto 0600</p></td><td colspan="1" rowspan="1"><p>Imposta <code>HERMES_SKIP_CHMOD=1</code> in <code>.env</code></p></td></tr><tr><td colspan="1" rowspan="1"><p>Workspace appare vuoto</p></td><td colspan="1" rowspan="1"><p>UID mismatch su mount <code>/workspace</code></p></td><td colspan="1" rowspan="1"><p>Imposta <code>UID=$(id -u)</code> in <code>.env</code></p></td></tr><tr><td colspan="1" rowspan="1"><p><code>git: command not found</code> nella chat</p></td><td colspan="1" rowspan="1"><p>Limite architetturale two-container (#681)</p></td><td colspan="1" rowspan="1"><p>Usa single-container o estendi Dockerfile</p></td></tr><tr><td colspan="1" rowspan="1"><p>WebUI non trova sorgente agente</p></td><td colspan="1" rowspan="1"><p>Volume <code>hermes-agent-src</code> malconfigurato</p></td><td colspan="1" rowspan="1"><p>Usa i volumi nominati dai file compose così come sono</p></td></tr><tr><td colspan="1" rowspan="1"><p>Podman condiviso <code>.hermes</code> fallisce</p></td><td colspan="1" rowspan="1"><p>Limitazione Podman 3.4 <code>keep-id</code></p></td><td colspan="1" rowspan="1"><p>Usa Podman 4+ o single-container</p></td></tr><tr><td colspan="1" rowspan="1"><p>API host a <code>localhost</code> fallisce dalla WebUI</p></td><td colspan="1" rowspan="1"><p><code>localhost</code> container significa il container, non il tuo host (#3012)</p></td><td colspan="1" rowspan="1"><p>Usa <code>http://host.docker.internal:&lt;port&gt;</code> su Docker Desktop, o <code>http://host.containers.internal:&lt;port&gt;</code> su Podman</p></td></tr><tr><td colspan="1" rowspan="1"><p>WebUI non vede <code>~/.hermes</code> dopo <code>sudo docker compose</code></p></td><td colspan="1" rowspan="1"><p><code>${HOME}</code> espanso alla home dell'utente root (#3006)</p></td><td colspan="1" rowspan="1"><p>Esegui Compose come tuo utente, o passa <code>HERMES_HOME</code>/<code>HERMES_WORKSPACE</code> assoluti con <code>sudo -E</code></p></td></tr></tbody></table>

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

**Nota:** Di default, Docker Compose si binda a `127.0.0.1` (solo localhost). Per esporre su una rete, cambia la porta in `"8787:8787"` in `docker-compose.yml` e imposta `HERMES_WEBUI_PASSWORD` per abilitare l'autenticazione.

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

### Verdetto — 4.7/5

### FAQ

## Fonti e riferimenti

1.  [Repository principale Hermes WebUI](https://github.com/nesquena/hermes-webui)
2.  [Documentazione ufficiale (docs/)](https://github.com/nesquena/hermes-webui/tree/master/docs)
3.  [Hermes Agent repository](https://github.com/NousResearch/hermes-agent)
4.  [Immagini Docker GHCR](https://github.com/nesquena/hermes-webui/pkgs/container/hermes-webui)

---

*Fonte: [https://ainsights.it/blog/hermes-web-ui-interfaccia-ai-autonoma](https://ainsights.it/blog/hermes-web-ui-interfaccia-ai-autonoma)*