Il server HTTP offre due facce dello stesso sistema: la chat da usare nel browser e un'API per i client autorizzati. Entrambe passano dagli stessi controlli di identità, proprietà e capacità. Conoscere un indirizzo o un identificatore non concede accesso ai dati di un altro utente.
La porta predefinita della chat è 8770. Sul computer che ospita Metnos puoi aprire:
http://127.0.0.1:8770/Se durante l'installazione hai consentito l'accesso dalla rete locale, puoi usare l'indirizzo privato del server da un telefono o da un altro computer collegato alla stessa rete. Per esempio:
http://192.168.1.33:8770/L'indirizzo è solo un esempio: al termine dell'installazione Metnos stampa
quelli rilevati davvero e salva gli indirizzi di base in
~/.local/share/metnos/install_summary.md. Il percorso della pagina
utenti è /admin/users; /amin/users contiene un refuso e
restituisce correttamente 404.
Durante la fase 4 dell'installazione puoi limitare l'interfaccia al browser
eseguito sul server. In quel caso il servizio ascolta soltanto su
127.0.0.1 e gli indirizzi LAN non funzionano. La procedura
interattiva propone l'accesso LAN per impostazione predefinita; l'avvio manuale
del solo processo HTTP, invece, usa prudentemente il solo computer locale se
non riceve una configurazione esplicita.
Alla fine dell'installazione Metnos stampa anche uno o più collegamenti amministrativi completi. Contengono un codice monouso valido per 15 minuti: aprendone uno, il browser riceve la sessione amministrativa e viene portato in Settings. Questi collegamenti completi non vengono conservati nel riepilogo di installazione; il file salva soltanto gli indirizzi di base.
Se il collegamento è scaduto o è già stato usato, apri
/admin/login e inserisci la chiave amministrativa creata
dall'installazione. Non condividere né il collegamento monouso né la chiave.
Un browser associato a un normale utente riceve invece un cookie distinto. Può usare la chat e le sole superfici ammesse dal suo ruolo, ma non diventa amministratore. Per creare utenti e associare browser consulta Associazioni e identità.
«Ruolo amministratore richiesto».
Questo messaggio significa che l'indirizzo esiste, ma il browser corrente non
ha una sessione amministrativa valida. Apri /admin/login; cambiare
l'indirizzo non aggira il controllo.
Metnos costruisce una sola applicazione aiohttp e vi collega
quattro gruppi di funzioni:
| Gruppo | Responsabilità |
|---|---|
| Agente | Chat, turni, sessioni, dialoghi, allegati, associazione web e callback OAuth. |
| Lavori durevoli | Lavori che sopravvivono alla connessione, eventi persistenti e download controllati degli artefatti. |
| Amministrazione | Settings: modelli, servizi, utenti, dispositivi, executor, attività e sicurezza. |
| Stato complessivo | Verifica congiunta del server, del catalogo e del servizio browser adiacente. |
Il corpo di una richiesta può arrivare a 50 MiB per consentire immagini di riferimento. I turni che eseguono lavoro Python passano da un insieme limitato di esecutori concorrenti, con coda globale e limite per chiamante. Se non c'è capacità, il server risponde in modo esplicito e suggerisce quando riprovare.
Due servizi restano separati: il protocollo degli executor remoti usa
normalmente 127.0.0.1:8765; il componente che controlla il browser
usa normalmente 127.0.0.1:8771. Non sono porte alternative della
chat e non vanno pubblicate come interfacce utente.
| Famiglia | Esempi | Uso |
|---|---|---|
| Chat e stato | /, /agent/health, /.well-known/metnos.json | Interfaccia, vitalità e descrizione minima del nodo. |
| Turni | /agent/turn, /agent/turn/submit, /agent/turns/{id} | Avvio, flusso degli eventi, stato, cronologia, riscontro e nuovo tentativo. |
| Sessioni e dialoghi | /agent/session/*, /agent/dialog/{id}/* | Scrittura da un solo browser e raccolta strutturata degli input. |
| Allegati | /agent/gallery/{turn_id}, /agent/photos/* | Gallerie dell'utente, immagini con collegamenti firmati e proxy web protetto. |
| Lavori durevoli | /agent/workloads, /agent/workloads/{id}/* | Stato, unità, eventi persistenti e artefatti di lavori lunghi. |
| Amministrazione | /admin/users, /admin/devices, /admin/virt, /admin/services | Configurazione e controllo riservati all'amministratore. |
Il registro nel codice resta la fonte completa: questa tabella spiega la struttura senza promettere un elenco immutabile di percorsi.
Prima di chiamare una funzione, il server classifica la richiesta come
anonymous, user o admin.
Un Bearer errato non ricade nell'eventuale fiducia della LAN. Gli header di
un proxy vengono considerati solo se la connessione TCP arriva da un proxy
esplicitamente fidato; un client non può dichiararsi locale scrivendo
X-Forwarded-For.
Il cookie amministrativo dura al massimo sette giorni; quello utente al
massimo novanta. Entrambi sono HttpOnly. L'opzione
Secure viene applicata quando il browser raggiunge Metnos tramite
HTTPS; i criteri SameSite sono più restrittivi per
l'amministratore.
POST /agent/turn accetta JSON oppure dati multipart con testo e
immagini. Può restituire un unico documento JSON o inviare eventi SSE mentre il
turno procede. Se la connessione si interrompe, questo percorso non offre da
solo la stessa ripresa del percorso disaccoppiato.
POST /agent/turn/submit riserva la capacità e risponde
202 con un turn_id. Il lavoro continua anche se la
pagina viene aggiornata. Il browser può ricollegarsi allo stream, ripartire
dall'ultimo evento visto oppure interrogare lo stato persistito.
Stream, stato, cronologia, galleria, riscontro e nuovo tentativo verificano
sempre il proprietario. Indovinare un turn_id non consente di
leggere o ripetere il turno di un altro utente.
Per ogni coppia utente-canale web può scrivere un solo browser alla volta. Se un secondo browser apre la stessa chat, Metnos consente di annullare, rendere attiva la nuova sessione oppure continuare sul nuovo dispositivo la conversazione precedente. Il trasferimento revoca atomicamente il diritto di scrittura del vecchio browser.
La conversazione appartiene all'utente, non al dispositivo. Questo evita che un telefono e un portatile producano due diramazioni concorrenti fingendo di essere la stessa sessione. I dettagli sono nella pagina Associazioni e identità.
10.0.0.0/8,
172.16.0.0/12 e 192.168.0.0/16; l'elenco è
configurabile e non concede da solo un'identità.curl -fsS http://127.0.0.1:8770/agent/health
curl -fsS http://127.0.0.1:8770/.well-known/metnos.json
curl -fsS -H "Authorization: Bearer <chiave-amministrativa>" \
http://127.0.0.1:8770/agent/stack/healthLa prima richiesta dimostra soltanto che il processo risponde. L'ultima, riservata all'amministratore, controlla anche il catalogo e il contratto del servizio browser: è la verifica più utile prima di un collaudo completo.
Per il trasporto dei messaggi continua con Canali di conversazione. Per chi può entrare e con quale identità consulta Associazioni e identità.