Work: spazi di lavoro isolati

Work è l'interfaccia nativa di Libre WebUI per gli agenti di programmazione. Ogni attività Work combina una conversazione permanente, una route esplicita tra modello e provider e un file system dedicato in /workspace. Il modello selezionato può esaminare e modificare file, eseguire comandi in un container Docker o Pod Kubernetes limitato all'attività e avviare un'anteprima nel browser.

Work è implementato direttamente in Libre WebUI. Non richiede Libre Claw né un altro daemon per agenti.

Solo utenti attendibili

Ogni API Work richiede un account autenticato con accesso a Work. Per impostazione predefinita, ciò significa soltanto gli amministratori; un amministratore può aprire Work a tutti gli utenti attivi dalla scheda Gestione utenti in Impostazioni (gli spazi di lavoro in cartelle dell'host restano comunque riservati agli amministratori, perché eseguono il bind mount di percorsi del server). Work consente intenzionalmente a un modello di eseguire comandi shell arbitrari in una sandbox. Le attività usano il traffico di rete in uscita, a meno che il criterio di runtime denominato selezionato non lo disabiliti. Considera ogni persona a cui concedi l'accesso a Work un operatore attendibile del runtime, non un semplice utente della chat.

Funzionalità principali della versione

Questa versione introduce Work come flusso completo per le attività:

• Azioni distinte Work e Chat nella barra laterale principale, con la modalità attiva evidenziata chiaramente.
• Attività Work nella normale barra laterale anziché in un secondo elenco. Le posizioni delle attività esistenti restano stabili durante gli aggiornamenti delle esecuzioni e l'attività selezionata può essere eliminata direttamente.
• Un'identità di sandbox dedicata e un volume Docker permanente o PVC Kubernetes per ogni attività. Le sandbox possono essere arrestate o ricreate senza eliminare i file dell'attività.
• Conversazione permanente, stato dell'esecuzione, attività degli strumenti, selezione del modello e proprietà dell'attività nel database di Libre WebUI.
• Un flusso di esecuzione in tempo reale e autenticato per testo dell'assistente, ragionamento esposto dal provider, chiamate agli strumenti e relativi risultati, utilizzo, competenze dei worker e modifiche dello stato.
• Competenze dei worker di proprietà del server, che insegnano al modello selezionato come esaminare, modificare, verificare e visualizzare in anteprima in modo efficiente senza scrivere file di controllo nel progetto.
• Modelli Ollama locali capaci di usare strumenti, modelli Ollama Cloud e plugin dei provider di completamento o chat configurati.
• Una suddivisione reattiva Conversazione/Spazio di lavoro con dimensionamento trascinabile e accessibile da tastiera sul desktop e un selettore della superficie attiva sugli schermi più piccoli.
• Viste integrate File, Attività, Git, Terminale, Anteprima e Schermo: la vista Schermo è il desktop Work Computer osservabile e istruibile.
• Evidenziazione della sintassi nelle modalità chiara e scura, formattazione del codice lato browser, rilevamento dei conflitti di salvataggio e bozze temporanee non salvate.
• Un'informativa ignorabile e specifica per utente quando viene selezionato un provider di modelli remoto.
• Traduzioni complete di Work in tutte le 25 lingue supportate, compreso il layout arabo nativo da destra a sinistra, mentre codice, percorsi, identificatori dei modelli e output dei comandi restano da sinistra a destra.

L'unità permanente è lo spazio di lavoro dell'attività, non un container sempre in esecuzione. Libre WebUI avvia, arresta e può ricreare il container dell'attività quando necessario, conservando il relativo volume denominato.

Architettura

È Libre WebUI, non il modello o il browser, a scegliere nomi della sandbox e dello spazio di lavoro, immagine, mount, utente, limiti, modalità di rete e porta dell'anteprima. Il modello riceve soltanto questi strumenti:

• list_files
• read_file
• write_file
• delete_file
• move_file
• search_files
• run_command
• start_preview
• stop_preview

delete_file e move_file sono protetti a livello di percorso come gli altri strumenti per i file: rifiutano di uscire dallo spazio di lavoro, non attraversano mai collegamenti simbolici, richiedono un flag ricorsivo esplicito prima di rimuovere una directory e non sovrascrivono mai la destinazione di uno spostamento. Poiché passano attraverso l'helper per i file anziché una shell, funzionano anche mentre è in esecuzione un'anteprima, quando run_command è bloccato.

Le richieste ai modelli vengono effettuate dal backend di Libre WebUI. Non provengono dal container Work e non dipendono dai criteri di rete del container.

Requisiti

Work necessita di un backend sandbox configurato:

• Il backend predefinito richiede che Docker sia installato, con un daemon raggiungibile e l'autorizzazione per il processo del backend a invocare docker oppure l'eseguibile configurato tramite WORK_DOCKER_COMMAND.
• Il backend Kubernetes richiede credenziali API, oltre a Role e RoleBinding con ambito dello spazio dei nomi, spazio dei nomi della sandbox e NetworkPolicy creati dal chart Helm quando work.enabled=true.

Ogni backend richiede inoltre:

• Un modello capace di usare strumenti ed esposto tramite:
  • un servizio Ollama integro, compresi i modelli raggiunti tramite Ollama Cloud; oppure
  • un plugin di completamento/chat attivo, con un modello esatto configurato e credenziali per l'amministratore corrente.
• Spazio di archiviazione del runtime sufficiente per l'immagine, i progetti generati e le dipendenze locali dei progetti.
• Un account autenticato con accesso a Work. Per impostazione predefinita Work è riservato agli amministratori; un amministratore può aprirlo a tutti gli utenti attivi.

Libre WebUI controlla le funzionalità del modello dichiarate da Ollama prima di creare un'esecuzione e rifiuta un modello Ollama che non dichiara tools. I modelli basati su plugin devono supportare il protocollo di chiamata agli strumenti del relativo provider. Se un modello remoto selezionato rifiuta gli strumenti, l'esecuzione non riesce; Work non passa silenziosamente a un modello o provider diverso.

Avvio in locale

Per la configurazione Work supportata più semplice, esegui Libre WebUI e Docker sullo stesso computer del browser:

docker info
npx libre-webui@latest

Apri http://localhost:8080, accedi come amministratore, seleziona Work nella barra laterale, scegli un modello compatibile e descrivi il progetto o la modifica.

Se Docker manca, è arrestato o non è accessibile, Work mostra Runtime non disponibile con il motivo restituito dal backend e disabilita il compositore Esegui. Libre WebUI non ricorre mai all'esecuzione diretta dei comandi Work sull'host.

L'immagine del runtime viene esaminata al primo utilizzo e scaricata automaticamente se assente. La prima operazione può quindi richiedere più tempo di quelle successive.

Usare l'interfaccia Work

Creare e riaprire le attività

Seleziona Work accanto a Chat nella barra laterale. Inserisci un'istruzione, scegli un modello e seleziona Esegui. Il primo messaggio crea l'attività, la prima esecuzione, la route del provider e lo spazio di lavoro permanente.

Ogni attività resta nella barra laterale principale. Quando la riapri, vengono ripristinati conversazione recente, vista File, selezione corrente di provider/modello e spazio di lavoro. I messaggi meno recenti della conversazione possono essere caricati in pagine. Puoi rinominare l'attività dal titolo ed eliminarla definitivamente dal menu dell'attività selezionata o dalla barra laterale.

Per ogni attività può essere attiva una sola esecuzione. Un'istruzione successiva crea un'altra esecuzione sulla stessa conversazione e sullo stesso file system.

Il compositore accetta la dettatura: il pulsante del microfono usa l'API vocale del browser, quando disponibile, oppure un modello di trascrizione vocale configurato come alternativa e aggiunge la trascrizione a quanto era già stato digitato. Nella conversazione, i file creati o spostati da un'esecuzione appaiono come indicatori selezionabili sotto l'attività dello strumento che li ha prodotti; selezionandone uno, il file si apre nell'editor File dello spazio di lavoro e, sugli schermi stretti, si passa alla superficie dello spazio di lavoro. Gli indicatori provengono soltanto dagli strumenti che modificano dati, quindi un'esecuzione che legge venti file ma ne scrive uno mostra esattamente quell'unico artefatto.

Incaricare un agente

Quando sono disponibili persona, la vista iniziale offre Incarica come agente: scegline una e l'attività creata diventerà un agente permanente dotato di nome anziché un'attività occasionale. Un agente mantiene la persona tra le esecuzioni: nome e prompt di sistema della persona vengono anteposti al prompt di sistema Work, che viene sempre superato dal contratto del runtime della sandbox. La barra laterale fissa gli agenti in un gruppo Agenti dedicato sopra le attività occasionali; ognuno mostra avatar della persona, indicatore di attività e stato su una sola riga. Quando la barra laterale è compatta restano nel rail soltanto gli avatar degli agenti fissati; le attività Work occasionali ricompaiono quando la barra laterale viene espansa.

La riga di stato ha due livelli. Per gli agenti incaricati, al termine di un'esecuzione una richiesta economica al modello e priva di strumenti chiede uno stato di circa 8 parole («Posta in arrivo vuota. 2 risposte pronte.»); la risposta è limitata a un'unica riga di 90 caratteri e in caso di errore o timeout si usa il livello deterministico, cioè la prima riga del messaggio finale dell'assistente. Le attività occasionali e le esecuzioni non riuscite usano soltanto il livello deterministico; WORK_STATUS_BLURB_MODEL=0 disabilita completamente la richiesta al modello. Gli agenti riportano anche un indicatore di elementi non letti: l'apertura dell'attività fa avanzare un marcatore monotono di visualizzazione per attività, sincronizzato tra dispositivi, e la barra laterale mostra un punto quando un'esecuzione ha raggiunto uno stato terminale dopo tale marcatore.

Gli agenti comunicano il proprio stato anche tramite le notifiche, nell'app e, quando abilitate, tramite push web: work-run-finished quando un'esecuzione viene completata, work-run-attention quando si ferma in attesa di input o non riesce e work-takeover nel momento in cui l'agente chiede a una persona di assumere il controllo dello schermo. Il banner sullo schermo è visibile soltanto mentre la scheda Schermo è aperta, quindi è la notifica push a raggiungerti altrove. Ogni notifica rimanda direttamente all'agente.

Puoi incaricare un agente con una persona di tua proprietà o condivisa con te; la vista condivisa non espone mai i ricordi della persona del proprietario. Se in seguito la persona viene eliminata, l'agente continua a funzionare senza di essa e viene registrato un avviso. L'API accetta personaId e isAgent alla creazione dell'attività; un'attività creata con una persona diventa automaticamente un agente.

Scheda Agente

Il riquadro dello spazio di lavoro di un agente si apre su una prima scheda aggiuntiva, Agente, che costituisce la pagina dell'agente:

• Identità: avatar e nome della persona, indicatore di attività e riga di stato più recente.
• Schermo: quando il criterio dell'attività concede Work Computer, viene mostrata una miniatura compatta e in tempo reale dello schermo dell'agente, disponibile in sola visualizzazione. È un vero visualizzatore e conta nel limite dei visualizzatori per attività; selezionandola si apre la scheda Schermo completa con controllo, apprendimento e audio.
• Routine: automazioni associate a questa attività. Ogni avvio viene eseguito nello spazio di lavoro e nella conversazione dell'agente, con il suo modello e runtime, non in una nuova attività, così una routine di riepilogo mattutino si accumula in un unico luogo. Le righe mostrano la pianificazione in parole con un interruttore per sospendere/riprendere; il modulo incorporato + Routine è già associato all'agente. Un'occorrenza avviata mentre l'agente è occupato non riesce esplicitamente con work-task-busy anziché entrare in coda.
• Revisione automatica: l'interruttore delle approvazioni del singolo agente e le regole Consenti sempre che l'agente ha raccolto (rimuovi una regola per richiuderne l'ambito). Quando il criterio dell'attività impone la revisione, l'interruttore resta bloccato su attivo.
• Competenze insegnate: procedure dimostrate in modalità apprendimento, con un interruttore per abilitare o disabilitare ogni competenza.

Strumenti collegati (server MCP e OpenAPI)

Gli agenti Work possono chiamare gli stessi server di strumenti configurati per la chat — MCP oppure OpenAPI, registrati da un amministratore in Impostazioni → Strumenti. Gli strumenti compaiono all'agente con i loro nomi qualificati (server__tool) e le chiamate partono dal backend di Libre WebUI attraverso il gateway degli strumenti irrobustito (traffico in uscita protetto contro SSRF, credenziali per utente, limiti di dimensione e di tempo), mai dall'interno della sandbox.

L'offerta è onesta su ciò che un'esecuzione autonoma può davvero usare:

• Un'attività offline non ne offre nessuno: con o senza traffico in uscita dal backend, un'attività priva di accesso alla rete resta offline, per la stessa ragione di web_search.
• Un server che richiede una credenziale personale non ancora salvata dall'utente viene escluso al momento dell'offerta, perché un'esecuzione autonoma non può fermarsi a chiederla. Aggiungi la credenziale in Impostazioni → Strumenti e l'esecuzione successiva offrirà quel server.
• La modalità di accesso agli strumenti (solo amministratori oppure tutti gli utenti) e la visibilità per singolo server valgono esattamente come in chat, e le associazioni ai server di strumenti di un personaggio restringono i server che il suo agente incaricato vede.
• Quando le approvazioni sono attive, gli strumenti collegati che il server classifica come con effetti collaterali si fermano in attesa della tua decisione come qualsiasi azione soggetta a controllo; gli strumenti di sola lettura vengono eseguiti senza chiedere.

Delega tra agenti (menzioni con @)

Gli agenti incaricati possono passarsi il lavoro. Digita @ nel compositore di Work per menzionare un altro dei tuoi agenti; l'agente corrente vede l'elenco dei colleghi (nomi e righe di stato) nelle proprie istruzioni e delega le richieste corrispondenti con lo strumento message_agent. La delega è coordinamento tramite messaggi, deliberatamente non tramite computer condivisi: ogni agente mantiene il proprio spazio di lavoro e la propria sandbox isolati e il destinatario non può vedere la conversazione di partenza, quindi la richiesta deve portare con sé il proprio contesto.

La delega è asincrona. Lo strumento restituisce subito il controllo, l'agente destinatario esegue nella propria attività (la sua conversazione mostra la richiesta con l'etichetta Delegata da il mittente) e quando termina — completata, in attesa di input, non riuscita o annullata — la sua risposta finale viene consegnata nella conversazione dell'agente delegante come messaggio con l'etichetta Rapporto da quell'agente. Se il delegante è ancora in esecuzione, il rapporto raggiunge il suo modello al round successivo; se è inattivo, il rapporto resta semplicemente in attesa nella conversazione: un rapporto non avvia mai automaticamente un'esecuzione, quindi due agenti non possono rimbalzarsi le richieste all'infinito. Le esecuzioni delegate non possono delegare a loro volta, un destinatario occupato fa fallire onestamente il tentativo anziché accodarlo e, quando le approvazioni sono attive, message_agent si ferma per la revisione come qualsiasi altra azione con effetti collaterali (una regola Consenti sempre è limitata a quel singolo agente destinatario).

Approvazione delle azioni (Revisione automatica)

Le azioni con effetti collaterali possono fermarsi in attesa della tua decisione prima di essere eseguite. Quando le approvazioni sono attive per un'attività — il criterio Work imposta Richiedi approvazione per le azioni con effetti collaterali oppure l'interruttore Revisione automatica dell'agente è attivo — l'esecuzione si ferma prima di eseguire run_command, computer_act, delete_file, move_file o message_agent e mostra una scheda di decisione nella conversazione: Consenti una volta, Consenti sempre oppure Nega.

• Consenti una volta esegue esattamente questa chiamata e chiede di nuovo la volta successiva.
• Consenti sempre esegue la chiamata e salva una regola sull'attività: per l'intero strumento nel caso delle azioni su file e sul computer, limitata al programma del comando (il suo primo token) per run_command — approvare npm run build preapprova i futuri comandi npm, non l'intera shell — e limitata al singolo agente destinatario per message_agent. Le regole sono elencate nella sezione Revisione automatica della scheda Agente e possono essere rimosse da lì.
• Nega rifiuta la chiamata. Al modello viene comunicato che l'utente ha negato l'azione e che non deve ritentarla così com'è; l'esecuzione prosegue con questa risposta.

Un'approvazione in attesa genera anche una notifica (nell'app e via web push quando è abilitata), perché l'esecuzione può essere già da minuti in lavoro non presidiato quando raggiunge il controllo. Se nessuno decide entro cinque minuti la richiesta scade, l'azione non viene eseguita e l'esecuzione termina come Richiede input con una normale consegna, invece di consumare in attesa il proprio budget.

Le approvazioni controllano le azioni, non la visibilità: write_file e gli strumenti di sola lettura restano senza controllo e ogni decisione finisce nel registro di controllo della sicurezza.

Comprendere lo stato dell'attività

L'interfaccia riconduce gli stati permanenti del backend a un insieme più piccolo rivolto agli utenti:

Stato nell'interfaccia	Stato del backend	Colore dell'indicatore
Inattiva	idle	rgb(255, 255, 255)
Elaborazione	preparing o running	rgb(48, 121, 255)
Completata	completed	rgb(76, 212, 117)
Richiede input	needs_input o cancelled	rgb(255, 204, 0)
Errore	failed	rgb(255, 61, 129)

Arrestare un'esecuzione attiva ne cambia lo stato in Richiede input e ne conserva i file. Anche l'esaurimento del budget di sicurezza per i turni o le chiamate agli strumenti termina con Richiede input dopo il passaggio finale senza strumenti, così un lavoro incompleto non viene mai etichettato come Completato.

Un'esecuzione attiva non blocca la conversazione: un messaggio inviato mentre l'agente lavora si aggiunge immediatamente alla conversazione e raggiunge il modello al turno successivo, così puoi orientare, correggere o aggiungere contesto senza arrestare l'esecuzione; il pulsante di arresto resta disponibile accanto a quello di invio.

Ridimensionare lo spazio di lavoro

Al breakpoint desktop xl, Conversazione e Spazio di lavoro condividono una suddivisione trascinabile:

• La larghezza predefinita della conversazione è del 45%.
• L'intervallo preferito va dal 30% al 70%, nel rispetto delle larghezze minime dei contenuti.
• Il rapporto salvato è specifico per l'utente connesso in quel browser.
• I tasti freccia spostano il separatore del 2%; tieni premuto Maiusc per il 10%.
• Inizio e Fine selezionano rispettivamente il minimo e il massimo disponibili.
• Invio o un doppio clic ripristinano la suddivisione.

I controlli seguono la direzione di scrittura attiva. In arabo, Conversazione si trova a destra e Spazio di lavoro a sinistra; il ridimensionamento tramite puntatore e tasti freccia continua a funzionare nella direzione visiva prevista.

Sugli schermi più piccoli, usa il controllo Conversazione/Spazio di lavoro nell'intestazione dell'attività per cambiare superficie.

File

La scheda File esplora i figli diretti di /workspace, apre esclusivamente file di testo UTF-8 validi e salva le modifiche nel volume dell'attività. Le sequenze di byte non valide vengono rifiutate anziché sostituite con caratteri segnaposto che causerebbero una perdita di informazioni.

L'editor offre:

• evidenziazione della sintassi nelle modalità chiara e scura per i comuni linguaggi web, di sistema, di scripting, dati e markup;
• Cmd/Ctrl+S per salvare;
• Shift+Alt+F per formattare i file supportati;
• rilevamento ottimistico dei conflitti di salvataggio, così una vista precedente nell'editor non può sovrascrivere silenziosamente un file modificato dopo la sua apertura;
• bozze non salvate specifiche per attività e percorso nell'archiviazione di sessione del browser; e
• avvisi di navigazione mentre è aperta una modifica non salvata.

L'evidenziazione in tempo reale si interrompe oltre 8,000 caratteri o 400 righe per mantenere reattiva la modifica. La formattazione è disponibile fino a 100,000 caratteri e 4,000 righe per JavaScript/JSX, TypeScript/TSX, varianti JSON, CSS/SCSS/Less, HTML, Markdown/MDX e YAML.

Quando il modello modifica un file aperto, la scheda File apre una vista Modifiche in rosso/verde che mostra esattamente gli elementi aggiunti e rimossi dall'inizio del turno, comprimendo le lunghe sequenze rimaste invariate. Un interruttore nella barra degli strumenti passa dal diff all'editor e viceversa; i contatori +added −removed riassumono il turno a colpo d'occhio. La base del confronto è l'ultimo contenuto visto dal browser prima del turno, quindi i file aperti per la prima volta dopo il turno non mostrano un diff.

Le bozze del browser sono uno stato di praticità, non un backup. Vengono cancellate dopo un salvataggio riuscito o l'eliminazione dell'attività e normalmente scompaiono alla fine della sessione del browser.

Attività

La scheda Attività mostra chiamate e risultati degli strumenti, operazioni sui file, output dei comandi ed errori. I metadati degli strumenti possono essere espansi nella conversazione. L'output di comandi e strumenti viene visualizzato da sinistra a destra anche quando l'interfaccia circostante procede da destra a sinistra.

Durante un'esecuzione attiva, Libre WebUI apre un flusso autenticato di eventi inviati dal server e mostra i progressi man mano che il backend li riceve. Il flusso può contenere:

• uno snapshot iniziale e successive modifiche di run_state;
• reasoning_delta quando il provider selezionato espone esplicitamente il ragionamento;
• testo assistant_delta;
• attività tool_call e tool_result;
• misurazioni usage;
• notifiche skill_loaded per le indicazioni dei worker fornite dal server; e
• eventi terminali error o done.

Disponibilità e granularità del ragionamento dipendono dal modello e dal provider. Libre WebUI mostra soltanto il contenuto di ragionamento restituito dal provider tramite la sua API; non può recuperare una catena di pensiero nascosta e alcuni modelli non forniscono alcun flusso di ragionamento. Il testo dell'assistente e l'attività degli strumenti continuano a essere trasmessi, quando supportati, indipendentemente dal ragionamento.

L'output viene intenzionalmente limitato. Un risultato troncato non dimostra che un comando non abbia prodotto altro output; chiedi al modello di esaminare un risultato più ristretto o di eseguire un comando più mirato.

Git

La scheda Git offre operazioni locali di controllo del codice sorgente per il solo /workspace dell'attività:

• inizializzare un repository con un ramo main;
• esaminare lo stato porcelain, i conteggi ahead/behind e fino a 20 commit recenti;
• esaminare un diff testuale limitato per un percorso modificato;
• aggiungere allo stage fino a 200 percorsi selezionati esplicitamente alla volta;
• eseguire il commit delle modifiche nello stage usando nome utente e indirizzo email dell'amministratore connesso oppure un indirizzo no-reply locale all'istanza quando l'account non ha un indirizzo email;
• creare un ramo locale dopo il primo commit; e
• passare a un ramo locale esistente quando il worktree è pulito.

Questa superficie è intenzionalmente solo locale. Non dispone di controlli per clone, fetch, pull, push, gestione remota, comandi Git arbitrari, token, chiavi SSH o pull request. Tali operazioni richiedono un broker di credenziali attendibile distinto, idealmente una GitHub App o un token di installazione equivalente limitato a un repository e un'operazione. Non inserire credenziali Git di lunga durata in /workspace, nell'ambiente del container dell'attività o nella configurazione del repository.

Le letture Git possono essere eseguite mentre l'attività è inattiva o attiva. Le scritture Git vengono rifiutate mentre un'esecuzione del modello, un terminale interattivo o un'anteprima detengono il container dell'attività. Il cambio di ramo richiede inoltre un worktree pulito. Ciò impedisce che l'interfaccia entri in competizione con il modello o con un processo di lunga durata sugli stessi file.

Ogni comando Git dell'interfaccia è un array fisso di argomenti eseguito come UID/GID 1000:1000 nel container dell'attività; l'input dell'utente non viene mai valutato da una shell. Per questa superficie, il runtime disabilita configurazione Git di sistema/globale, prompt, hook, helper delle credenziali, firma dei commit, ricorsione dei sottomoduli, driver diff esterni, textconv e protocolli di rete. Rifiuta repository il cui worktree non è esattamente /workspace o la cui directory Git/comune si risolve fuori da /workspace. Le azioni di scrittura Git che potrebbero elaborare il contenuto dei file vengono inoltre bloccate quando la configurazione del repository definisce un filtro eseguibile clean, smudge o process.

Questi controlli proteggono l'API Git di Libre WebUI. Un amministratore può comunque usare il Terminale e il modello può comunque usare run_command per eseguire normali comandi Git nella sandbox. La sandbox e il confine del deployment restano quindi i controlli di sicurezza per i comandi arbitrari.

Competenze integrate dei worker

Ogni esecuzione riceve una guida dello spazio di lavoro di proprietà del server. Descrive il confine permanente di /workspace, la radice del container di sola lettura, lo stato temporaneo dei processi e di /tmp, i criteri di rete, i limiti di comandi e output e il ciclo di vita dell'anteprima. Le competenze integrate indicano al modello di:

• esaminare istruzioni del progetto, manifesti, lockfile, script e stato corrente del repository prima di apportare modifiche;
• conservare il lavoro non correlato e raggruppare letture o ricerche indipendenti;
• proseguire con l'implementazione anziché fermarsi dopo un piano;
• eseguire verifiche mirate prima di controlli più ampi;
• diagnosticare un errore anziché riprovare senza criterio; e
• verificare l'applicazione prima di avviare l'anteprima come processo finale di lunga durata.

La guida esiste soltanto nel contesto del modello. Libre WebUI non crea un file AGENTS.md, una directory di competenze o altri file di controllo nello spazio di lavoro dell'utente. Le istruzioni fornite dal progetto restano indicazioni per il progetto e non possono superare il confine di sicurezza del container o degli strumenti.

Terminale

La scheda Terminale collega una shell interattiva allo stesso container in sandbox in cui lavora il modello, così un amministratore può esaminare lo stato, eseguire manualmente una build o diagnosticare ciò che un'esecuzione ha lasciato, senza uscire dal browser.

La shell viene eseguita con criteri del container identici a quelli di ogni strumento del modello: utente senza privilegi 1000:1000, directory di lavoro /workspace, nel container già protetto e privo di funzionalità. Un terminale non concede privilegi ulteriori rispetto allo strumento run_command del modello: è un'interfaccia rivolta alle persone verso lo stesso confine, non un modo per aggirarlo.

Comportamento operativo:

• Autenticazione — il browser scambia la normale intestazione Authorization tramite HTTP con un ticket monouso e di breve durata, associato al protocollo del terminale Work e all'attività esatta. Soltanto tale ticket e l'ID dell'attività appaiono nell'URL di upgrade /ws/work-terminal. Prima di ogni input della shell, Libre ricontrolla stato dell'account corrente, accesso a Work, esistenza e proprietà dell'attività. La revoca chiude immediatamente la shell e libera il relativo lease del runtime.
• Controlli dell'origine — quando CORS_ORIGIN o BASE_URL è configurato, gli upgrade del browser devono corrispondere a una di tali origini. Configurane almeno una per i deployment remoti. Gli upgrade senza origine restano disponibili per Electron e client non browser, ma richiedono comunque lo stesso ticket associato all'attività e gli stessi controlli di autorizzazione in tempo reale; usa TLS, firewall e criteri del reverse proxy per controllare tali client.
• Ammissione — un terminale aperto acquisisce un lease del runtime esattamente come un comando o un'anteprima e conta ai fini di WORK_MAX_ACTIVE_RUNTIMES_*.
• Durata del container — un terminale collegato mantiene il container in esecuzione e impedisce al percorso di arresto per inattività di rimuoverlo durante la sessione.
• Concorrenza — WORK_TERMINAL_MAX_SESSIONS_PER_TASK (valore predefinito 2) limita il numero di shell simultanee per attività.
• Timeout di inattività — WORK_TERMINAL_IDLE_TIMEOUT_MS (valore predefinito 15 minuti) chiude una sessione inutilizzata e libera il relativo lease.
• Durante un'esecuzione attiva — la scheda spiega che il modello detiene il container e apre la shell al termine del turno.

Il terminale comunica direttamente con l'API del motore Docker, perché una sessione TTY richiede un flusso bidirezionale sottratto alla connessione, che la CLI Docker fornisce soltanto a un vero terminale di controllo. Usa WORK_DOCKER_SOCKET; in alternativa DOCKER_HOST, ovvero un socket unix:// o un endpoint tcp:// HTTP semplice come un proxy del socket, il cui inoltro consapevole di HTTP trasporta il flusso sottratto tramite un tunnel standard Connection: Upgrade; altrimenti /var/run/docker.sock. Se questo client non è in grado di comunicare con il valore DOCKER_HOST, ad esempio ssh:// o tcp:// con DOCKER_TLS_VERIFY impostato, il terminale viene indicato come non disponibile con tale motivo anziché collegarsi silenziosamente altrove; il resto di Work continua a funzionare. Sul backend Kubernetes, la stessa sessione usa la sottorisorsa exec come WebSocket TTY attraverso il server API, compresi i frame di ridimensionamento, senza alcun endpoint Docker.

Le sessioni del terminale sono interattive e non vengono registrate. I comandi digitati al loro interno non appaiono nella timeline Attività dell'attività.

Anteprima

La scheda Anteprima avvia, arresta, incorpora e apre l'applicazione web generata. Quando il campo del comando è vuoto, Libre WebUI esamina lo spazio di lavoro e:

• esegue uno script dev nel file package.json radice con host e porta richiesti;
• serve un file index.html radice tramite un server statico incluso e senza dipendenze; oppure
• usa le stesse regole per un'unica app in una directory annidata.

Le applicazioni radice hanno la precedenza. Se vengono trovate più app annidate ugualmente probabili o non esiste un punto di ingresso supportato, Work restituisce un errore su cui è possibile intervenire anziché tentare un comando npm non correlato. Per altri layout di progetto o server, inserisci un comando personalizzato prima di selezionare Avvia anteprima. I comandi personalizzati iniziano in /workspace, quindi includi la directory relativa quando necessario, ad esempio cd apps/web && npm run dev -- --host 0.0.0.0 --port 4173. Un processo personalizzato deve restare in ascolto su 0.0.0.0 e sulla porta WORK_PREVIEW_PORT configurata. Work attende fino a 15 secondi che la porta sia pronta.

Il modello può avviare l'anteprima anche tramite il proprio strumento start_preview. Questo è l'unico modo supportato affinché un modello lasci in esecuzione un processo. Le normali chiamate run_command eliminano i processi discendenti in background al termine del comando.

Schermo (Work Computer)

Guarda la dimostrazione completa: un'esecuzione reale e non modificata (30x, poi in tempo reale) di un agente Work che esplora sul proprio schermo le gallerie di immagini della NASA, sceglie fotografie e quindi crea e prova una galleria Three.js interattiva, tutto a partire da un solo prompt.

Un'attività il cui criterio abilita Work Computer ottiene una scheda Schermo: una finestra in tempo reale su un desktop virtuale eseguito nella stessa sandbox, con gestore delle finestre, dock e browser Chromium su uno schermo 1280×800. Puoi guardare l'agente al lavoro, assumere il controllo di mouse e tastiera, ascoltare l'audio del computer e insegnargli attività tramite dimostrazione. L'apertura della scheda avvia su richiesta la sessione GUI (nulla viene eseguito finché qualcuno non osserva) e collega un visualizzatore VNC tramite WebSocket.

Per abilitarlo basta un clic di un amministratore: la pagina iniziale di Work mostra una scheda Work Computer con il pulsante Abilita. Premendolo, viene creata l'immagine GUI inclusa sul daemon Docker del deployment (la prima build richiede alcuni minuti) e viene creato un criterio Work Computer pronto all'uso, senza comandi docker build manuali né campi del criterio da compilare. Dietro un proxy filtrato dell'API Docker, l'endpoint di build viene negato intenzionalmente; scarica invece l'immagine pubblicata sull'host Docker (ghcr.io/libre-webui/libre-work-computer, con tag libre-work-computer:latest) oppure creala lì da deploy/work-computer/: in seguito Abilita salterà la build e creerà soltanto il criterio. Le attività che usano tale criterio devono avere accesso alla rete; lo schermo viene raggiunto tramite una porta del container pubblicata su loopback, esattamente come l'anteprima.

Modello di sicurezza: il server VNC nel container resta in ascolto su localhost dietro due password per sessione, una di sola visualizzazione fornita a ogni osservatore autorizzato e una con controllo completo rilasciata soltanto a chi detiene il lease di controllo corrente; in questo modo è il server VNC stesso a rendere inattivo l'input di tutti gli altri. Il bridge WebSocket è l'unica superficie raggiungibile, pubblicata sul loopback dell'host Docker e mai esposta direttamente. Ogni visualizzatore si autentica con un ticket monouso associato alla propria sessione e all'attività, lo stesso meccanismo del Terminale; l'accesso corrente a Work viene ricontrollato a ogni connessione, quindi la revoca dell'accesso di un utente interrompe immediatamente i suoi schermi. Fino a quattro visualizzatori simultanei possono osservare uno schermo e l'osservazione conta come attività ai fini del controllo di inattività. Osservazione ed esecuzione non entrano mai in competizione: aprire lo schermo mentre l'agente sta eseguendo un turno collega la sandbox della stessa esecuzione; uno schermo osservato non impedisce l'avvio dell'esecuzione successiva e la sessione sopravvive al termine dell'esecuzione, anche nei deployment per team in cui le esecuzioni vengono effettuate in un processo worker distinto. Il profilo del browser viene conservato in /workspace/.browser-profile, così gli accessi eseguiti nel computer sopravvivono ai riavvii del container.

Controllo da parte dell'agente: un'attività con Work Computer offre al modello anche due strumenti aggiuntivi. computer_observe restituisce uno screenshot completo del desktop insieme a posizione del cursore, identità della finestra attiva, URL corrente del browser, indicazione se lo stato attivo della tastiera appartiene alla pagina anziché all'interfaccia del browser, un descrittore compatto dell'elemento attivo e un hash dello screenshot. I segnali semantici provengono da un endpoint DevTools in ascolto sul loopback del container e risultano assenti nelle immagini GUI create prima della sua introduzione. computer_act esegue un batch di massimo 24 azioni di mouse e tastiera (spostamento, clic, doppio clic, clic destro, digitazione, combinazioni di tasti, scorrimento e attesa) e restituisce lo screenshot dopo la stabilizzazione. Tre protezioni del runtime mantengono affidabili i batch: le azioni type/key possono includere un'asserzione focus e non riescono in modo sicuro quando il campo dichiarato non ha lo stato attivo della tastiera, così il testo non può finire silenziosamente nella barra degli indirizzi; un batch si arresta in anticipo quando appare una finestra, cambia il titolo o lo stato attivo si sposta a metà batch, perché le coordinate rimanenti erano destinate allo schermo precedente; un batch può inoltre dichiarare un risultato previsto, relativo a titolo, URL o area dello schermo modificata, che il runtime verifica con una scadenza adattiva: «pending» significa non ancora osservato, mai riuscito per supposizione.

Dopo un batch, lo schermo si stabilizza in modo adattivo, tramite interrogazioni finché non smette di cambiare, anziché dopo un ritardo fisso. Ogni risultato contiene inoltre prove che il modello deve leggere: i clic a coordinate esplicite restituiscono una ricevuta che indica se sono cambiati pixel vicini al clic; scroll_until scorre verso un testo di destinazione o il bordo della pagina e comunica se è diventato visibile; ogni osservazione viene confrontata con la precedente, così uno schermo invariato viene indicato esplicitamente. I batch possono dichiarare un subgoal su una sola riga, che viene conservato con il risultato come checkpoint e ripetuto nei prompt di ripristino. Il ciclo dell'agente rileva le situazioni di stallo nel riferimento visivo (tre azioni identiche su uno schermo invariato attivano un avviso di ripristino; un'ulteriore ripetizione termina l'esecuzione chiedendo input anziché consumare i turni rimanenti) e l'ambiguità crescente (aspettative consecutive non verificate attivano un avviso per ristabilire il riferimento). La telemetria del ciclo, comprendente turni, latenza degli strumenti, screenshot, protezioni e verdetti sulle aspettative, viene impressa su ogni record permanente degli strumenti e riepilogata al termine dell'esecuzione.

Gli screenshot raggiungono il modello come vero contenuto immagine su ogni route dei provider: Ollama, Anthropic, Gemini e i plugin di chat e Responses compatibili con OpenAI. Il modello che guida l'attività dovrebbe quindi essere un modello di visione. Se il provider rifiuta l'input immagine, come nel caso di un modello di solo testo, l'esecuzione non fallisce: per il resto dell'esecuzione gli screenshot vengono eliminati, al modello viene indicato di basarsi sulle osservazioni testuali e una nota nella trascrizione spiega il funzionamento degradato. Tuttavia, un modello che non può vedere lo schermo esegue verifiche molto meno efficaci, quindi per le attività sul computer è preferibile un modello di visione. Soltanto gli screenshot più recenti restano nel contesto in tempo reale del modello e le trascrizioni permanenti delle attività conservano esclusivamente l'osservazione testuale, mai i byte delle immagini.

Il browser viene fornito con il blocco dei contenuti integrato: uBlock Origin Lite per pubblicità e tracker, fissato e verificato tramite checksum durante la creazione dell'immagine e con modalità di filtraggio fissata da un criterio gestito, oltre a un componente che chiude automaticamente i banner di consenso ai cookie. Pubblicità e schermate di consenso consumano inutilmente screenshot, token e clic dell'agente. Le richieste pubblicitarie vengono neutralizzate secondo lo stile di uBlock: gli script pubblicitari noti vengono risolti in stub locali innocui, così le pagine continuano a funzionare. L'agente riceve l'istruzione di non inserire mai credenziali né completare verifiche CAPTCHA/2FA; segnala invece l'ostacolo. Per le attività non attendibili, associa un criterio GUI a un resolver DNS con filtri: un browser desktop rende il criterio del traffico di rete in uscita ancora più importante.

Audio: per impostazione predefinita lo schermo è disattivato, in base a una regola del browser per cui l'audio richiede un clic; il pulsante dell'altoparlante nel riquadro Schermo trasmette in tempo reale l'audio del computer. Nella sandbox, PulseAudio riproduce verso un sink nullo; il relativo monitor viene acquisito come PCM non elaborato e servito tramite un secondo bridge WebSocket autenticato e pubblicato sul loopback, con gli stessi ticket, ricontrollo dell'accesso e limite dei visualizzatori per attività dello schermo. Richiede un'immagine GUI creata da deploy/work-computer/ in questa versione o in una successiva.

Controllo: il pulsante Assumi il controllo nel riquadro Schermo ti assegna mouse e tastiera, per accedere, superare un CAPTCHA o svolgere qualsiasi passaggio che l'agente non deve eseguire; Ho finito restituisce lo schermo all'agente. Un'unica sessione VNC serve entrambi i ruoli: il server nel container conserva una password con controllo completo e una di sola visualizzazione, generate per sessione e mai registrate; gli osservatori ricevono soltanto quella di visualizzazione e la password di controllo viene rilasciata esclusivamente al detentore corrente di un lease di controllo. Il lease ha un TTL limitato (un controllo abbandonato scade entro due minuti), viene rinnovato mentre l'interfaccia di controllo è aperta ed è cooperativo: non può essere sottratto a un altro utente.

Un criterio può disabilitare del tutto il controllo tramite Consenti controllo dello schermo nell'editor dei criteri: nelle attività che lo usano vengono nascosti i controlli Assumi il controllo e Insegna, l'endpoint per il controllo rifiuta le richieste e request_takeover dell'agente segnala che non è possibile passare il controllo a nessuno; l'osservazione resta disponibile. Mentre una persona detiene il controllo, sia computer_observe sia computer_act dell'agente sono bloccati, quindi l'agente non può contrastare l'input né acquisire screenshot di ciò che digiti. Anche l'agente può chiedere il tuo intervento: il suo strumento request_takeover pubblica un banner nel riquadro Schermo con la motivazione e attende che tu assuma il controllo e lo restituisca. Le credenziali inserite durante il controllo passano direttamente dalla tastiera alla pagina: non attraversano mai il modello o la trascrizione dell'attività. Il controllo richiede un'immagine GUI creata da deploy/work-computer/ in questa versione o in una successiva; le sessioni basate su immagini precedenti restano osservabili, ma per tutti in sola visualizzazione.

Modalità apprendimento: Insegna un'attività nel riquadro Schermo registra una dimostrazione. Guidi lo schermo reale assumendo il controllo esattamente come descritto sopra, con un indicatore di registrazione visibile, mentre vengono acquisite a coordinate dello schermo le azioni del puntatore, della tastiera e di scorrimento. Ogni clic viene anche ancorato: una sonda di sola lettura risolve l'elemento interattivo sotto il puntatore, con tag, ID ed etichetta visibile, e l'URL della pagina corrente; in questo modo i passaggi del playbook indicano i propri obiettivi, ad esempio «Fai clic su "button#submit (Place order)"», e le coordinate vengono declassate a indicazione della posizione occupata dal controllo durante la dimostrazione.

Il salvataggio crea un playbook in modo deterministico, senza alcun modello nel ciclo: le sequenze di tasti vengono raggruppate in stringhe digitate, la distinzione tra clic e trascinamento usa una soglia di 8 pixel, le pause diventano passaggi di attesa espliciti e il testo digitato che menziona termini relativi a segreti o ha la forma di una credenziale (almeno 8 caratteri che combinano tre classi di caratteri) viene rimosso e sostituito dall'istruzione di usare request_takeover in quel passaggio. Il playbook è una procedura in linguaggio naturale, con obiettivi ancorati come prima scelta e coordinate come suggerimenti, reinterpretata tramite computer_observe; contiene condizioni di utilizzo, input, passaggi, verifica, un ambito consentito ricavato dagli host effettivamente visitati durante la dimostrazione (la riproduzione deve arrestarsi e chiedere conferma prima di lasciarli: una procedura insegnata non eredita mai un'autorità superiore a quanto mostrato), confini di approvazione e gestione degli errori basata sull'arresto e la richiesta di conferma.

Il playbook viene salvato come una normale competenza, con prefisso dello slug taught-, quindi appare nella pagina Competenze con versioni, modifica e condivisione. Le esecuzioni Work abilitate per il computer caricano nel proprio prompt di sistema le competenze insegnate abilitate del proprietario e le riportano nell'elenco delle competenze dell'esecuzione; riprodurre un'attività insegnata è quindi una normale esecuzione la cui richiesta corrisponde alla procedura. Dopo un'esecuzione terminata, gli indicatori delle competenze offrono una recensione riuscito/non riuscito con un solo clic, che aggiunge una riga datata alla sezione Cronologia dei risultati della competenza, con le voci più recenti per prime, numero limitato e ciascuna come normale versione della competenza; la cronologia della procedura resta con la procedura. Non digitare password reali durante la registrazione: esegui la dimostrazione fino all'accesso, salva e lascia che request_takeover gestisca le credenziali durante la riproduzione.

Provider, routing e divulgazione dei dati

Route dei provider supportate

Route	Convalida e comportamento
Ollama locale	Ollama deve essere integro e il modello esatto deve dichiarare il supporto degli strumenti.
Ollama Cloud	Instradato esplicitamente tramite Ollama; i modelli con suffisso cloud mostrano l'informativa sul provider remoto.
Plugin di completamento/chat	Il plugin deve essere attivo, elencare il modello esatto e disporre di una credenziale per l'amministratore corrente.
Plugin Anthropic	Usa l'adattatore di Work per i messaggi e l'uso degli strumenti di Anthropic.
Plugin Gemini	Usa l'adattatore di Work per contenuti e chiamate di funzioni di Gemini.
Altri plugin compatibili	Usano la forma OpenAI per messaggi, strumenti e scelta degli strumenti nella richiesta.

Il tipo di provider e l'ID del plugin vengono archiviati sia nell'attività sia in ogni esecuzione. Il nome di un modello non sceglie mai la route da solo. Attivare un plugin con lo stesso nome di modello di un modello Ollama non consente di intercettare un'attività esistente.

Dati ricevuti da un provider

Per ogni turno del modello, il provider selezionato può ricevere:

• il prompt di sistema Work;
• le competenze integrate dei worker e i limiti correnti del runtime;
• fino ai 30 messaggi utente/assistente più recenti della conversazione, entro 256 KB;
• le definizioni degli strumenti Work;
• la cronologia delle chiamate agli strumenti dell'assistente; e
• i risultati degli strumenti, che possono includere elenchi di directory, contenuti di file richiesti, risultati delle ricerche, output dei comandi ed errori.

Il volume denominato non viene caricato per intero. Tuttavia, il contenuto dei file o l'output dei comandi restituito da uno strumento diventa parte della conversazione del modello e viene inviato al provider selezionato. Prima di usare codice sorgente sensibile, esamina i criteri del provider remoto in materia di conservazione, addestramento, prezzi e utilizzo.

Le credenziali dei provider restano nel backend di Libre WebUI, sia che siano configurate per l'intero deployment sia per un singolo utente. Vengono usate per le richieste ai modelli dal backend e non sono mai montate nel container Work.

La crittografia delle credenziali a livello dell'applicazione non equivale alla crittografia dell'intera attività. Conversazioni Work, risultati degli strumenti, output dei comandi e metadati delle attività sono normali contenuti del database, mentre i file e le dipendenze dello spazio di lavoro sono normali file nel volume Docker o PVC Kubernetes dell'attività. Usa controlli di accesso all'host e crittografia del disco quando il modello di minaccia del deployment richiede la crittografia dei dati archiviati.

Informativa sui provider remoti

Ai fini dell'informativa, Work considera remoti i modelli dei plugin e i nomi Ollama che terminano in :cloud o -cloud. Se ne selezioni uno, si apre un avviso ignorabile che spiega il flusso dei dati verso il provider e la possibilità di più chiamate fatturabili. La preferenza di chiusura viene memorizzata per utente di Libre WebUI.

Tutte le route dei provider usano lo stesso budget WORK_MAX_AGENT_ROUNDS, con valore predefinito di 48 turni. Non esiste un limite distinto di 12 turni per i plugin. Il budget di sicurezza delle chiamate agli strumenti è il valore maggiore tra 128 chiamate e otto chiamate per ogni turno configurato. Quando il budget dei turni è esaurito, Libre WebUI chiede al modello un passaggio finale senza strumenti che descriva il lavoro completato, i controlli, gli ostacoli e i passaggi rimanenti. Registra quindi lo stato terminale dell'esecuzione come Richiede input, anziché esporre un'eccezione non elaborata per il limite dei turni o contrassegnare come completo un lavoro incompleto. Un'esecuzione successiva continua nello stesso spazio di lavoro permanente. Una singola esecuzione Work può comunque effettuare molte richieste fatturabili al provider.

Spazi di lavoro in cartelle dell'host (facoltativi)

Nel backend Docker, /workspace di un'attività è normalmente un volume denominato che esiste soltanto per tale attività, quindi il modello non può raggiungere i file reali. Un deployment Docker può invece consentire di associare un'attività a una cartella effettiva sull'host. Kubernetes rifiuta gli spazi di lavoro in cartelle dell'host e usa un PVC di proprietà dell'attività.

Imposta entrambe le variabili, quindi riavvia il backend:

WORK_HOST_WORKSPACES_ENABLED=true
WORK_HOST_WORKSPACE_ROOTS=/Users/you/Projects

WORK_HOST_WORKSPACE_ROOTS è un elenco di directory radice separate da :; per impostazione predefinita usa la home directory dell'utente del server. Quando la funzionalità è attiva, nella schermata iniziale di Work appare un campo facoltativo Cartella dello spazio di lavoro. Lascialo vuoto e l'attività si comporterà esattamente come prima, usando il proprio volume isolato.

Prima di essere accettato, un percorso deve essere assoluto, esistere, essere una directory e risolversi, attraversando gli eventuali collegamenti simbolici, in una posizione interna a una delle directory radice configurate. Le directory denominate .ssh, .gnupg, .aws, .config, .kube, .docker, .claude, .libre-webui o node_modules vengono rifiutate senza eccezioni. Il percorso risolto viene archiviato con l'attività e mostrato nella relativa intestazione, così è sempre visibile su quale cartella opera un'attività.

Questo riduce la protezione della sandbox

Uno spazio di lavoro sull'host consente al modello di leggere e scrivere i file reali; le altre protezioni del container, come utente non root, funzionalità rimosse e limiti delle risorse, non si frappongono più tra il modello e tale directory. Mantieni disabilitata la funzionalità se non ti serve, limita il più possibile le directory radice e preferisci directory sottoposte a controllo di versione.

Persistenza e ciclo di vita del runtime

Libre WebUI separa lo stato permanente dallo stato di esecuzione:

Stato	Archiviazione	Durata
Proprietà, titolo, provider e stato dell'attività	Database di Libre WebUI	Fino all'eliminazione dell'attività o dell'utente proprietario
Esecuzioni, errori, messaggi e attività degli strumenti	Database di Libre WebUI	Fino all'eliminazione dell'attività
File dello spazio di lavoro	Volume Docker o PVC K8s dell'attività	Sopravvivono ad annullamento, arresto anteprima e riavvii di sandbox e app
File system radice e file temporanei	Container o Pod dell'attività	Sostituibili; possono essere arrestati o ricreati
Processo di anteprima	Sandbox dell'attività in esecuzione	Effimero; conservato soltanto finché ne viene verificata l'integrità
Bozza non salvata nell'editor	Archiviazione di sessione del browser	Stato temporaneo utile durante la sessione del browser

Ogni attività riceve un UUID generato dal server. I nomi della sandbox e dello spazio di lavoro vengono derivati nel backend e non sono mai accettati da una richiesta del browser. Libre WebUI crea le risorse del runtime con etichette di gestione e proprietà dell'attività. Prima di riutilizzarle o eliminarle, verifica l'etichetta di proprietà dell'attività e rifiuta una risorsa la cui etichetta appartiene a un'altra attività.

Le sandbox vengono preparate su richiesta. Le operazioni degli helper per i file arrestano una sandbox altrimenti inattiva, i comandi la arrestano al completamento e un'anteprima di cui è stata verificata l'integrità può mantenerla in esecuzione affinché l'utente esamini l'app. Lo spazio di lavoro permanente viene montato nuovamente quando la sandbox della stessa attività viene riavviata o ricreata.

Gli amministratori possono definire criteri di runtime denominati dalla scheda Gestione utenti in Impostazioni: preset che combinano immagine di runtime, limiti di memoria/CPU/PID, dimensione dello spazio di lavoro in Kubernetes, timeout di inattività, impostazione predefinita della rete e due interruttori di funzionalità. Work Computer (GUI + browser) fornisce alle attività del criterio un desktop virtuale e la scheda Schermo; Consenti controllo dello schermo stabilisce se una persona può assumere il controllo di tali schermi e, poiché l'insegnamento registra tramite un controllo, se la modalità apprendimento è disponibile. Un'attività creata con un criterio viene eseguita con tale configurazione; ogni campo lasciato vuoto eredita i valori globali del deployment e l'eliminazione di un criterio riporta le relative attività a tali valori alla successiva ricreazione del container. I criteri modificano soltanto risorse e questi interruttori di funzionalità: il profilo di protezione, con utente non root, file system radice di sola lettura, funzionalità rimosse e isolamento di rete, non è un campo del criterio e non può essere indebolito per singolo criterio.

WORK_RUNTIME_IDLE_TIMEOUT_MS limita la durata del periodo di tolleranza dell'anteprima: quando è impostato, una verifica arresta qualsiasi sandbox priva di attività, cioè senza comandi completati, terminali collegati o richieste di anteprima tramite il proxy firmato, per il numero specificato di millisecondi, liberandone lo slot di ammissione. L'arresto è economico e lo spazio di lavoro persiste, quindi un'anteprima arrestata per inattività si riavvia semplicemente all'uso successivo. Il valore predefinito (0) mantiene il comportamento attuale: un'anteprima viene eseguita finché non viene arrestata esplicitamente.

All'avvio del backend, le esecuzioni attive vengono contrassegnate come non riuscite e lo stato delle anteprime viene cancellato: il ciclo dell'agente e il proxy dell'anteprima sono terminati con il processo e non possono essere ripresi. Il driver selezionato elenca quindi in un'unica query i container o Pod gestiti. Le sandbox in esecuzione di proprietà di attività note vengono arrestate perché un comando interrotto potrebbe essere ancora in esecuzione senza supervisore; quelle già arrestate restano invariate; le sandbox gestite la cui riga dell'attività non esiste più vengono rimosse. La proprietà deriva dall'etichetta dell'attività, mai dal nome della risorsa. La rimozione degli elementi orfani presuppone che una sola istanza Libre WebUI sia proprietaria di uno spazio dei nomi del runtime o daemon Docker. Non indirizzare due istanze alle stesse risorse Work. Se il driver non può dimostrare il completamento della pulizia, Work resta chiuso in sicurezza, riprova ogni 10 secondi e blocca le nuove operazioni modificabili finché non viene ripristinato l'accesso al runtime.

Comportamento della rete

Verifica il criterio di rete selezionato

Le attività senza un criterio di runtime denominato iniziano con la rete abilitata. Un amministratore può definire un criterio denominato con la rete disattivata per impostazione predefinita e l'autore può selezionarlo durante la creazione dell'attività. Non esiste un interruttore di rete indipendente per singola attività e la modifica successiva del criterio richiede la ricreazione della sandbox prima che entri in vigore la nuova configurazione del runtime.

Nel backend Docker, le attività con rete si collegano a una rete bridge gestita dedicata (libre-webui-work per impostazione predefinita, WORK_NETWORK_NAME), creata con la comunicazione tra container disabilitata (com.docker.network.bridge.enable_icc=false). Ne derivano due conseguenze:

• una sandbox Work non può aprire connessioni verso un'altra sandbox Work; e
• una sandbox Work non può raggiungere i container del deployment sulla rete bridge predefinita condivisa di Docker, compresi un database o un container Ollama nella stessa posizione che non siano pubblicati intenzionalmente.

Libre WebUI rifiuta di avviare un'attività con rete se esiste già una rete con il nome configurato che non è quella gestita, anziché collegare silenziosamente le sandbox alla rete dell'operatore.

In Kubernetes, il Pod della sandbox usa la stessa etichetta di rete abilitata. Il chart Helm installa una NetworkPolicy con negazione predefinita, traffico in ingresso limitato all'anteprima e traffico internet in uscita soltanto per i Pod con rete abilitata, escludendo i valori configurati in work.networkPolicy.blockedEgressCidrs. La NetworkPolicy è efficace soltanto quando viene applicata dal CNI del cluster; consulta la guida di Kubernetes.

Il traffico verso l'esterno resta consentito, perché download dei pacchetti, operazioni Git remote e API esterne rendono utile Work. Non si tratta di un firewall in uscita. Il codice generato può comunque riuscire a raggiungere:

• servizi sull'host Docker;
• sistemi sulla rete locale dell'host;
• servizi internet; e
• endpoint dei metadati dell'infrastruttura, a seconda del deployment.

Hook dei criteri per il traffico in uscita

Per un confine più restrittivo, usa insieme:

• WORK_RUNTIME_DNS (Docker) — indirizzi IPv4/IPv6 dei resolver separati da virgole e imposti su ogni sandbox con rete (--dns). Indirizzandolo a un resolver con filtri, puoi applicare elenchi di nomi consentiti/negati senza modificare Libre WebUI. Le voci che non sono indirizzi vengono rifiutate e registrate, così il valore non può mai inserire flag Docker aggiuntivi.
• Regole del firewall dell'host o upstream (Docker) sulla sottorete del bridge gestito, che è stabile perché la rete è denominata e gestita.
• WORK_NETWORK_NAME (Docker) indirizzato a una rete creata in precedenza con opzioni del driver personalizzate: Libre WebUI verifica che riporti l'etichetta gestita e l'opzione di disabilitazione ICC, quindi creala con entrambe.

Il filtraggio DNS limita la risoluzione dei nomi, non il traffico diretto agli IP. Un deployment che deve garantire l'assenza di traffico diretto agli IP necessita anche di regole del firewall a livello di host, cluster o rete upstream.

Non supporre che inserire codice in Work gli impedisca di trasmettere dati. Concedi l'accesso a Work soltanto a utenti attendibili. Usa un criterio di runtime denominato con rete disabilitata quando un'attività deve iniziare offline; non esiste una variabile di ambiente per l'intero deployment che modifichi il criterio predefinito.

L'accesso alla rete non aggiunge credenziali. Libre WebUI non monta chiavi SSH, credenziali cloud, profili del browser, home directory dell'host o socket Docker nei container delle attività. Il codice può comunque trasmettere credenziali o segreti scritti in /workspace da un utente o dal modello.

Questo traffico della sandbox è distinto dal traffico del modello. Le richieste Ollama e dei plugin vengono sempre inviate dal backend di Libre WebUI alla route del provider selezionata esplicitamente.

Confine di sicurezza della sandbox

Un container Docker di Work:

• viene eseguito come UID/GID non root 1000:1000;
• usa /workspace come directory di lavoro;
• monta soltanto il volume denominato dell'attività selezionata in /workspace;
• usa un file system radice di sola lettura e un file system temporaneo /tmp limitato;
• rimuove tutte le funzionalità Linux;
• abilita no-new-privileges;
• non dispone di privilegi e usa un processo init;
• applica limiti per CPU, memoria, processi, durata dei comandi e output;
• limita lo swap allo stesso valore della memoria (--memory-swap uguale a --memory), così il limite di memoria non può essere aggirato tramite swap;
• si collega alla rete gestita della sandbox con la comunicazione tra container disabilitata oppure non si collega ad alcuna rete; e
• pubblica soltanto la porta dell'anteprima configurata verso una porta host loopback assegnata da Docker.

Ogni proprietà viene verificata nuovamente tramite docker inspect prima di riutilizzare un container e l'intero insieme viene sottoposto a hash nell'etichetta ai.libre-webui.policy del container. Un container il cui criterio precede un aggiornamento di Libre WebUI viene distrutto e ricreato anziché riutilizzato, così una modifica di protezione raggiunge automaticamente le attività esistenti.

Il driver Kubernetes applica un contesto di sicurezza del Pod equivalente: UID/GID non root, file system radice di sola lettura, seccomp RuntimeDefault, nessuna escalation dei privilegi, tutte le funzionalità rimosse, archiviazione effimera limitata, limiti delle risorse, nessun token ServiceAccount e un PVC di proprietà dell'attività in /workspace. Verifica le etichette dell'attività e l'impronta digitale del criterio prima di riutilizzare o eliminare un Pod o PVC.

La convalida dei percorsi rifiuta percorsi assoluti, segmenti di attraversamento, barre rovesciate, caratteri NUL e percorsi troppo lunghi. Gli helper per i file risolvono i percorsi reali e rifiutano le fughe tramite collegamenti simbolici. Le scritture usano un file temporaneo e una ridenominazione atomica.

Questi controlli riducono l'esposizione accidentale dell'host; non rendono Work una macchina virtuale né un ambiente sicuro per l'analisi di malware. I container condividono il kernel dell'host del runtime. Una vulnerabilità di Docker, Kubernetes, runtime, immagine, dipendenza o kernel può superare il confine previsto.

I volumi denominati Docker non dispongono di una quota disco indipendente. Un progetto generato o l'installazione di un pacchetto può esaurire lo spazio di archiviazione Docker, quindi monitora la crescita dei volumi e applica limiti di archiviazione a livello di host. Kubernetes richiede una dimensione PVC; l'applicazione effettiva della quota dipende dal provisioner di archiviazione selezionato.

Elenco di controllo per la protezione di Docker in produzione

Questo elenco di controllo è specifico del backend Docker. Gli operatori Kubernetes devono inoltre convalidare RBAC con ambito dello spazio dei nomi, contesto di sicurezza dei Pod, classe di archiviazione e applicazione della NetworkPolicy da parte del CNI del chart, come descritto nella guida di Kubernetes.

L'applicazione può impostare flag dei container, convalidare percorsi degli spazi di lavoro e proteggere la propria API. Non può applicare criteri firewall dell'host, quote del driver di archiviazione o il livello di privilegi del daemon Docker ricevuto. Considerali attività di deployment esplicite per un'istanza client privata.

1. Isolare il controllo di Docker

Il container principale di Libre WebUI necessita del controllo del daemon per creare ed esaminare i container Work. Un socket Docker montato è quindi una credenziale del piano di controllo, non un normale mount di dati: compromettere l'applicazione web può comportare la compromissione dell'host Docker.

La prima mitigazione è inclusa in questo repository: docker-compose.socket-proxy.yml mantiene il socket completamente fuori dal container Libre WebUI. Un proxy del socket detiene /var/run/docker.sock su una rete interna e inoltra soltanto le sezioni dell'API usate da Work, ovvero container, immagini, volumi, reti, exec e info, mentre gli endpoint swarm, segreti, configurazioni, build, commit e sistema vengono negati prima di raggiungere il daemon. Libre WebUI viene indirizzato al proxy con DOCKER_HOST=tcp://docker-socket-proxy:2375 e non necessita del mount del socket né dell'appartenenza al relativo gruppo; CLI, terminale interattivo e diagnostica Docker seguono tutti tale endpoint. Il proxy riduce la superficie dell'API, non il raggio d'impatto degli endpoint inoltrati: chi può creare container può comunque eseguire il bind mount di percorsi dell'host, quindi il confine descritto di seguito resta importante.

Per un confine di produzione più forte, esegui Libre WebUI e il relativo daemon Work su una VM dedicata senza carichi di lavoro non correlati. Per una protezione ancora maggiore, fornisci a Work un daemon Docker rootless dedicato o un host di runtime separato ed esponi a Libre WebUI soltanto tale daemon. Prima del rilascio, verifica proprietà dei file, routing delle anteprime, pulizia e supporto del terminale con tale daemon. Montare semplicemente in sola lettura lo stesso socket rootful dell'host non rende di sola lettura l'API Docker.

2. Bloccare l'accesso di gestione dalla sandbox all'host

Disabilitare la comunicazione tra container impedisce alle sandbox Work di raggiungersi a vicenda; non impedisce loro di raggiungere i servizi in ascolto sull'host Docker. Esamina il bridge gestito e la sottorete effettivi anziché presupporre un indirizzo:

docker network inspect libre-webui-work \
  --format 'id={{.Id}} subnets={{range .IPAM.Config}}{{.Subnet}} {{end}}'
ss -lntup

Usa il gestore firewall permanente dell'host per rifiutare il traffico proveniente da tale bridge verso i servizi di gestione dell'host, in particolare SSH, API Docker, database e porte di monitoraggio/amministrazione. Prova la regola da un container usa e getta collegato a libre-webui-work, prova i download dei pacchetti consentiti e rendi quindi persistente la regola. La catena DOCKER-USER di Docker controlla il traffico inoltrato; il traffico destinato all'host Docker stesso può richiedere anche una regola INPUT/hook di input sull'interfaccia bridge.

3. Limitare le destinazioni in uscita

Blocca gli endpoint dei metadati cloud, gli intervalli dell'infrastruttura privata e gli intervalli della LAN del client dalla sottorete Work, a meno che un progetto non ne abbia esplicitamente bisogno. Combina un resolver con filtri tramite WORK_RUNTIME_DNS con regole firewall dell'host o upstream. Il filtraggio DNS può essere aggirato tramite un indirizzo IP letterale. Anche un proxy HTTP da solo è insufficiente finché comandi arbitrari possono aprire connessioni di rete dirette; applica il criterio di routing fuori dal container.

Mantieni criteri di runtime denominati distinti quando i client necessitano di comportamenti diversi, ad esempio un runtime offline/senza rete, uno limitato ai registri dei pacchetti e uno con traffico in uscita aperto. Il criterio denominato controlla se Libre collega la rete della sandbox; firewall esterni e regole proxy applicano comunque le restrizioni a livello di destinazione per un criterio con rete abilitata.

4. Applicare quote di archiviazione effettive

I limiti di CPU, memoria, swap e PID non limitano il volume denominato. Prima di servire più client, scegli un backend di archiviazione con quote applicabili per spazio di lavoro, ad esempio quote di progetto XFS, volumi logici basati su quote o un driver volume/PVC con limite di dimensione. Il driver Docker local predefinito su un normale file system ext4 non ottiene una quota affidabile per volume soltanto perché viene documentata una dimensione.

Monitora sia ogni volume ai.libre-webui.managed=true sia la directory radice dei dati Docker, invia un avviso prima che il file system si riempia e prova la modalità di errore. Un contatore nell'interfaccia o una verifica periodica con du può avvisare, ma non costituisce un confine di applicazione perché un container può consumare lo spazio restante tra due controlli.

5. Verificare il criterio distribuito

Dopo ogni modifica all'immagine o ai criteri del daemon, crea un'attività Work usa e getta e verifica lo stato effettivo con docker inspect: UID non root, radice in sola lettura, tutte le funzionalità rimosse, no-new-privileges, limiti di memoria/swap/CPU/PID, soltanto il volume dell'attività montato e la rete prevista. Verifica inoltre che il container principale di Libre WebUI abbia soltanto i mount previsti e che il traffico in ingresso pubblico raggiunga l'app tramite il reverse proxy o tunnel autenticato, non tramite una porta Docker o di anteprima pubblicata accidentalmente.

Sicurezza e raggiungibilità dell'anteprima

Per un'attività Docker, il driver pubblica la porta dell'anteprima configurata su una porta assegnata dinamicamente nel loopback del backend. Per Kubernetes, il backend interno al cluster raggiunge direttamente l'IP del Pod della sandbox. Il modello e il browser non possono scegliere un upstream arbitrario. Libre WebUI firma un URL di funzionalità per l'attività e l'endpoint esatti, verifica a ogni richiesta che l'anteprima sia ancora in esecuzione e inoltra traffico HTTP e WebSocket tramite /api/work/previews. L'arresto o il riavvio dell'anteprima revoca il vecchio URL.

Le risposte dell'anteprima rimuovono credenziali Libre WebUI e cookie upstream. Il contenuto HTML viene limitato sia da una sandbox iframe sia da una CSP della risposta che consente script, moduli, finestre modali e download senza concedere l'accesso alla stessa origine. La CSP protegge anche un'anteprima aperta in una scheda distinta. Il codice generato dell'applicazione resta non attendibile e può usare il traffico di rete in uscita per trasmettere qualsiasi dato leggibile dal proprio spazio di lavoro o dagli input del browser. Considera l'URL di un'anteprima in esecuzione un segreto di breve durata e non condividerlo.

Poiché il browser carica il proxy sulla stessa origine pubblica di Libre WebUI, i browser remoti e i reverse proxy HTTPS funzionano senza esporre porte Docker o IP dei Pod e senza attivare il blocco dei contenuti misti. I reverse proxy devono conservare gli upgrade WebSocket per /api/work/previews/; la configurazione Nginx fornita lo fa.

L'applicazione principale consente come sorgenti dei frame soltanto la propria origine e Cloudflare Turnstile. Le risposte dell'anteprima ignorano il criterio Helmet principale, così possono trasmettere i corpi delle richieste e applicare il criterio sandbox più ristretto descritto sopra. Il criterio dell'elemento incorporante cross-origin resta disabilitato perché i server di sviluppo generati normalmente non inviano intestazioni delle risorse compatibili.

Matrice dei deployment

La disponibilità di Work dipende dalla macchina e dal processo che eseguono il backend di Libre WebUI, non soltanto dal browser o dall'interfaccia desktop.

Deployment	Esecuzioni e file Work	Anteprima incorporata
npx libre-webui su un computer locale	Supportato quando Docker è installato, in esecuzione e invocabile dall'utente del backend.	Supportata tramite il proxy firmato sull'origine dell'applicazione.
Sviluppo dal codice sorgente su un computer locale	Supportato con gli stessi requisiti per Docker e provider.	Supportata tramite l'origine dell'API di sviluppo sulla porta 3001.
Client desktop Electron	Condizionale. Electron usa un backend Libre WebUI esterno e non offre un runtime Work distinto.	Supportata tramite l'URL proxy firmato del backend.
Backend bare metal o VM su un host remoto	Esecuzioni, file e chiamate ai provider funzionano quando Docker è disponibile su tale host.	Supportata quando il reverse proxy pubblico conserva il traffico HTTP e WebSocket.
Docker Compose standard del repository	Supportato per impostazione predefinita su Docker Desktop: l'immagine include la CLI Docker, Compose monta il socket Docker dell'host e le porte di Work passano per host.docker.internal. Docker Engine nativo richiede inoltre un valore WORK_PREVIEW_BIND non pubblico e raggiungibile.	Supportata tramite la stessa origine pubblica di Libre WebUI.
Deployment Kubernetes/Helm corrente	Supportato con --set work.enabled=true: le sandbox vengono eseguite come Pod con spazi di lavoro PVC (esecuzioni, file, comandi, Git, terminali interattivi e schermo e audio di Work Computer all'IP del Pod), sotto un Role con ambito dello spazio dei nomi e NetworkPolicy con negazione predefinita, senza alcun socket Docker. Consulta la guida di Kubernetes.	Supportata quando il backend viene eseguito nel cluster: il proxy firmato raggiunge direttamente l'IP del Pod della sandbox.

Eseguire Work quando Libre WebUI è in Docker

Ogni file Compose del repository abilita Work: l'immagine include la CLI Docker e il file Compose monta /var/run/docker.sock. Docker Desktop funziona con i valori di routing predefiniti forniti. Docker Engine nativo richiede inoltre WORK_PREVIEW_BIND impostato su un'interfaccia host non pubblica raggiungibile dai container fratelli, come descritto più avanti.

Work controlla il daemon dell'host tramite tale socket, quindi i container delle attività sono fratelli del container Libre WebUI, non figli. Appaiono in docker ps sull'host e vengono eliminati secondo le stesse regole del ciclo di vita di un'installazione nativa.

Montare il socket Docker in un'applicazione web concede a tale container un controllo equivalente a root sull'host Docker. Work non può funzionare senza di esso, quindi Libre WebUI lo abilita anziché distribuire una funzionalità che silenziosamente non fa nulla. La conseguenza è esplicita: ogni amministratore di Libre WebUI è di fatto un amministratore dell'host Docker. Gli operatori sono responsabili delle conseguenze per sicurezza del daemon, rete, ciclo di vita, backup e controllo degli accessi. Elimina la riga /var/run/docker.sock dal file Compose per disattivare Work; nessun'altra funzionalità dipende da essa.

Per mantenere Work senza fornire il socket all'applicazione web, esegui invece il deployment con docker-compose.socket-proxy.yml: un proxy del socket su una rete interna detiene il socket e inoltra soltanto le sezioni dell'API usate da Work, mentre Libre WebUI lo raggiunge tramite DOCKER_HOST. Consulta Isolare il controllo di Docker per capire che cosa copre tale confine e che cosa non copre.

Devono essere soddisfatte tre condizioni; il pannello Work indica quella che non lo è:

1. La CLI Docker deve essere presente nell'immagine. È inclusa nell'immagine ufficiale; un'immagine personalizzata richiede docker-cli oppure un valore WORK_DOCKER_COMMAND che vi punti. Altrimenti: The "docker" CLI is not installed….
2. Il socket deve essere montato. Altrimenti: No Docker daemon is reachable….
3. L'utente del backend deve appartenere al gruppo del socket. L'immagine viene eseguita come nodejs (uid 1001) e il socket appartiene in genere a root o docker, quindi Compose passa group_add: ['${DOCKER_GID:-0}']. Il valore predefinito è adatto a Docker Desktop; un host Linux richiede il proprio ID di gruppo. Altrimenti: The Docker socket is mounted but the Libre WebUI user cannot open it….

# Read the socket's group as seen INSIDE a container. A macOS host reports a
# different value, because Docker Desktop proxies the socket through a VM.
echo "DOCKER_GID=$(docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  alpine stat -c '%g' /var/run/docker.sock)" >> .env
docker compose up -d --force-recreate

Le porte delle anteprime delle attività restano associate al loopback dell'host Docker. Libre WebUI espone ogni anteprima in esecuzione tramite un URL proxy firmato sulla stessa origine, compresi risorse HTTP e upgrade WebSocket. Funziona dietro HTTPS e tunnel remoti senza aprire alla rete le porte Docker effimere. I documenti dell'anteprima ricevono un criterio sandbox restrittivo nel browser e l'arresto o riavvio di un'anteprima ne revoca l'URL precedente.

Quando il backend stesso viene eseguito in Docker, pubblicazione e connessione possono usare indirizzi diversi. Mantieni WORK_PREVIEW_BIND=127.0.0.1 per evitare di esporre le porte effimere e imposta WORK_DOCKER_PUBLISHED_HOST sull'indirizzo dell'host Docker raggiungibile dal container del backend (host.docker.internal in Docker Desktop). I profili Compose inclusi impostano entrambi i valori e mappano il nome host. I deployment Linux nativi devono sostituire WORK_PREVIEW_BIND con il gateway del bridge Docker (o un'altra interfaccia host esplicitamente raggiungibile e non pubblica); la sola mappatura di host.docker.internal non rende raggiungibile un listener sul loopback dell'host. Non associare mai queste porte effimere non elaborate a 0.0.0.0.

La concorrenza viene limitata separatamente: il valore predefinito di WORK_MAX_ACTIVE_RUNTIMES_PER_USER è 2 e quello di WORK_MAX_ACTIVE_RUNTIMES_GLOBAL è 3, così un amministratore può eseguire una seconda attività mentre la prima è occupata. La risposta delle funzionalità comunica entrambi i limiti e l'occupazione in tempo reale. Aumentali se l'host dispone di memoria e CPU sufficienti.

Per Kubernetes, installa il chart con work.enabled=true anziché esporre un socket del runtime del nodo. Il chart crea RBAC con ambito definito, spazio dei nomi della sandbox, criteri di rete e configurazione Pod/PVC descritti nella guida di Kubernetes.

Configurazione del runtime

Work legge queste variabili nel processo backend:

Variabile	Valore predefinito	Scopo
WORK_RUNTIME_BACKEND	docker	Driver della sandbox: docker o kubernetes
WORK_RUNTIME_IMAGE	node:22.22-bookworm@sha256:2d178f2785b96dfbf62a416ca2e40f50e30150b4ff3320d706f0d96e90600eb3	Immagine usata per le sandbox delle attività
WORK_DOCKER_COMMAND	docker	Eseguibile CLI del backend Docker
WORK_COMMAND_TIMEOUT_MS	120000	Timeout predefinito dei comandi
WORK_MAX_OUTPUT_CHARS	50000	Output massimo acquisito per comandi e ricerche
WORK_MAX_AGENT_ROUNDS	48	Budget di turni modello/strumenti per esecuzione, indipendente dal provider
WORK_MEMORY_LIMIT	2g	Limite di memoria per contenitore
WORK_CPU_LIMIT	2	Limite di CPU per contenitore
WORK_PIDS_LIMIT	256	Limite di processi per contenitore
WORK_PREVIEW_PORT	4173	Porta su cui l'app deve essere in ascolto nel contenitore
WORK_PREVIEW_BIND	127.0.0.1	Interfaccia host su cui viene pubblicata la porta di anteprima
WORK_DOCKER_PUBLISHED_HOST	come WORK_PREVIEW_BIND	Host/IP contattato dal backend per le porte Work pubblicate da Docker
WORK_COMPUTER_SCREEN_PORT	6080	Porta WebSocket nel contenitore del bridge dello schermo
WORK_COMPUTER_AUDIO_PORT	6081	Porta WebSocket nel contenitore del bridge audio
WORK_RUN_LEASE_WAIT_MS	60000	Tempo di attesa di un'esecuzione per il titolare temporaneo del lease del runtime
WORK_MAX_ACTIVE_RUNTIMES_GLOBAL	3	Attività simultanee basate su contenitori per istanza Libre WebUI
WORK_MAX_ACTIVE_RUNTIMES_PER_USER	2	Attività simultanee basate su contenitori per amministratore
WORK_MAX_TASKS_GLOBAL	500	Limite di attività Work persistenti per istanza Libre WebUI
WORK_MAX_TASKS_PER_USER	100	Limite di attività Work persistenti per amministratore
WORK_NETWORK_NAME	libre-webui-work	Rete bridge gestita delle sandbox per le attività con accesso alla rete
WORK_RUNTIME_DNS	non impostato	IP dei resolver separati da virgole imposti alle attività con accesso alla rete
WORK_DOCKER_SOCKET	DOCKER_HOST se unix:// o tcp://, altrimenti /var/run/docker.sock	Endpoint Docker Engine usato per i terminali interattivi
WORK_TERMINAL_MAX_SESSIONS_PER_TASK	2	Terminali interattivi simultanei per attività
WORK_TERMINAL_IDLE_TIMEOUT_MS	900000	Timeout di inattività prima della chiusura di una sessione del terminale
WORK_RUNTIME_IDLE_TIMEOUT_MS	0 (disabilitato)	Arresta una sandbox dopo questo periodo di inattività (anteprime incluse)
WORK_K8S_NAMESPACE	libre-webui-work	Namespace Pod/PVC delle sandbox Kubernetes
WORK_K8S_STORAGE_CLASS	valore predefinito del cluster	StorageClass per i PVC degli spazi di lavoro Kubernetes
WORK_K8S_WORKSPACE_SIZE	5Gi	Dimensione predefinita del PVC Kubernetes per attività
WORK_K8S_POD_READY_TIMEOUT_MS	900000	Attesa massima affinché un Pod della sandbox sia pronto
WORK_K8S_POD_GONE_TIMEOUT_MS	60000	Attesa massima affinché un Pod della sandbox eliminato scompaia

In produzione, usa una versione o un digest fisso dell'immagine. Un tag immagine modificabile può cambiare sia gli strumenti da riga di comando disponibili sia il confine di sicurezza senza che Libre WebUI cambi.

Le operazioni di esecuzione, anteprima, assistenza sui file, comando e ricreazione della sandbox condividono lo stesso conteggio della capacità nel processo. Un'operazione annidata in un'attività già conteggiata non viene conteggiata come un'altra attività. Le richieste che superano un limite di ammissione delle attività o dei runtime restituiscono HTTP 429.

Limiti fissi del protocollo e dell'interfaccia utente

Elemento	Limite
Nuova attività o messaggio di esecuzione	65,536 caratteri e byte UTF-8
Identificatore del modello alla creazione/aggiornamento dell'attività	500 caratteri e byte UTF-8
ID del provider del plugin	200 caratteri
Esecuzioni attive per attività	1
Testo del comando	20,000 caratteri
Timeout del comando richiesto da uno strumento	Da 1 a 600 secondi
Disponibilità dell'anteprima	15 secondi
Lettura/scrittura di file	2,000,000 byte di testo UTF-8
Elenco diretto di directory	Prime 1,000 voci
Pagina dei messaggi	Fino a 200 messaggi e 1,000,000 byte
Singolo messaggio persistente	100 KB
Contesto della conversazione inviato a un modello	Ultimi 30 messaggi utente/assistente, fino a 256 KB
Output persistente degli strumenti	Circa 20,000 caratteri sorgente più un indicatore
Evidenziazione nell'editor in tempo reale	8,000 caratteri e 400 righe
Formattazione nel browser	100,000 caratteri e 4,000 righe
Output dello stato Git	2,000,000 caratteri acquisiti
Output del diff Git	600,000 caratteri acquisiti
Cronologia Git	20 commit locali
Percorsi in una singola richiesta Git di staging	200
Messaggio di commit Git	4,000 caratteri
Ciclo dell'agente, per ogni percorso del provider	48 turni per impostazione predefinita, configurati da WORK_MAX_AGENT_ROUNDS
Budget di sicurezza delle chiamate agli strumenti	max(128, configured rounds × 8) chiamate

L'accesso ai file è riservato al testo UTF-8. L'editor integrato non è un editor di file binari e un file più grande di 2 MB non può essere aperto tramite l'API per i file di Work.

Riepilogo dell'API

Tutti gli endpoint si trovano sotto /api/work e richiedono l'autenticazione, oltre all'accesso corrente a Work definito nel database. Per impostazione predefinita, Work è riservato agli amministratori; un amministratore può consentire agli utenti attivi di eseguire le normali operazioni sulle attività. La selezione delle cartelle dell'host e gli endpoint amministrativi per criteri e accesso rimangono riservati agli amministratori.

Metodo	Percorso	Scopo
GET	/capabilities	Disponibilità e limiti del runtime/provider selezionato
GET	/tasks	Elenca le attività dell'amministratore corrente
POST	/tasks	Crea un'attività e la sua prima esecuzione asincrona
GET	/tasks/:id	Carica lo stato dell'attività e i messaggi recenti
GET	/tasks/:id/messages	Carica una pagina di messaggi meno recenti
PATCH	/tasks/:id	Rinomina o cambia il percorso esplicito del modello
DELETE	/tasks/:id	Rimuove l'attività e lo spazio di lavoro persistente
POST	/tasks/:id/runs	Avvia un'esecuzione successiva
POST	/tasks/:id/messages	Invia un messaggio all'agente durante un'esecuzione attiva
GET	/tasks/:taskId/runs/:runId/events	Trasmette eventi autenticati dell'esecuzione in tempo reale tramite SSE
POST	/tasks/:id/cancel	Annulla l'esecuzione attiva
GET	/tasks/:id/approvals	Approvazioni in attesa e stato della Revisione automatica dell'attività
PUT	/tasks/:id/approvals	Attiva o disattiva l'adesione alle approvazioni per l'attività
POST	/tasks/:id/approvals/:approvalId	Decide un'approvazione in attesa (consenti una volta o sempre, nega)
DELETE	/tasks/:id/approval-rules/:ruleId	Rimuove una regola Consenti sempre
GET	/computer/setup	Stato della configurazione di Work Computer (amministratore)
POST	/computer/setup	Crea l'immagine GUI e il criterio (amministratore)
POST	/tasks/:id/computer/start	Avvia la sessione Work Computer dell'attività
GET	/tasks/:id/computer/control	Indica chi controlla lo schermo; richiesta di controllo dell'agente
POST	/tasks/:id/computer/control	Assume (o rinnova) il controllo dello schermo
DELETE	/tasks/:id/computer/control	Restituisce il controllo dello schermo all'agente
POST	/tasks/:id/computer/teach	Salva una dimostrazione registrata come abilità appresa
POST	/tasks/:id/computer/anchor	Individua l'elemento sotto un clic registrato
POST	/computer/skills/:slug/trace	Aggiunge una riga riuscita/non riuscita a un'abilità appresa
GET	/tasks/:id/files	Elenca una directory dello spazio di lavoro
GET	/tasks/:id/file	Legge un file di testo dello spazio di lavoro
PUT	/tasks/:id/file	Salva un file di testo dello spazio di lavoro
GET	/tasks/:id/git	Legge lo stato e la cronologia Git locali protetti
GET	/tasks/:id/git/diff	Legge un diff locale con dimensioni limitate
POST	/tasks/:id/git/init	Inizializza Git in locale
POST	/tasks/:id/git/stage	Aggiunge allo staging percorsi espliciti dello spazio di lavoro
POST	/tasks/:id/git/commit	Esegue il commit delle modifiche in staging
POST	/tasks/:id/git/branches	Crea un branch locale
POST	/tasks/:id/git/switch	Passa a un branch locale esistente e pulito
POST	/tasks/:id/preview/start	Avvia l'anteprima gestita
POST	/tasks/:id/preview/stop	Arresta l'anteprima gestita

L'ID dell'attività viene sempre verificato rispetto al proprietario autenticato. Lo stato corrente dell'account, il ruolo e i criteri di accesso a Work vengono letti dal database a ogni richiesta, quindi una revoca ha effetto anche se un JWT precedente contiene dichiarazioni di ruolo non più aggiornate.

Lo schema di aggiornamento delle attività conserva nel backend un campo networkEnabled per compatibilità interna. Non viene esposto come controllo indipendente nell'interfaccia di Work. Quando crei l'attività, seleziona un criterio di runtime denominato con l'impostazione di rete predefinita desiderata; non usare il campo grezzo come API di configurazione persistente.

Eliminazione, modifiche dell'account e backup

Eliminazione di un'attività

L'eliminazione di un'attività è intenzionalmente distruttiva:

1. Il backend contrassegna l'attività come in fase di ritiro, impedendo l'avvio di nuove operazioni che potrebbero modificarla.
2. Un'esecuzione attiva viene annullata e la sandbox dell'attività viene arrestata.
3. Libre WebUI convalida le etichette di proprietà dell'attività sulle risorse del runtime.
4. Il contenitore/Pod e il volume/PVC denominato vengono rimossi.
5. L'attività viene eliminata dal database, con eliminazione a cascata delle relative esecuzioni e dei relativi messaggi.
6. Le bozze del browser per quell'attività vengono cancellate dopo il buon esito dell'API.

Se la pulizia del runtime non riesce, Libre WebUI conserva il record dell'attività nel database e restituisce un errore, così l'operatore può riparare il backend Docker o Kubernetes e riprovare. I metadati non vengono eliminati silenziosamente lasciando una sandbox o uno spazio di lavoro non tracciati.

Arrestare un'esecuzione o un'anteprima è diverso dall'eliminazione: interrompe l'esecuzione ma conserva il volume denominato e la conversazione.

Revoca del ruolo di amministratore ed eliminazione degli utenti

Quando a un amministratore viene revocato il ruolo, Libre WebUI salva la revoca prima di dipendere dalla pulizia del runtime. Ogni richiesta successiva a Work verifica il ruolo e la modalità di accesso correnti. Il backend sospende quindi le attività Work dell'utente quando il nuovo ruolo non dispone più dell'accesso e tenta di interrompere le esecuzioni attive e arrestarne le sandbox. Se la pulizia non riesce, l'accesso revocato rimane tale e l'aggiornamento del ruolo segnala l'errore, così un operatore può ripristinare il runtime e riprovare.

L'eliminazione di un altro utente rimuove innanzitutto tutte le risorse Work gestite di quell'utente. Se la pulizia del runtime esterno non riesce, il record dell'utente viene conservato, così un amministratore può riprovare senza perdere i metadati di proprietà necessari per una pulizia sicura.

Backup completo dell'attività

Un backup completo di Work richiede entrambi gli elementi seguenti:

• il database di Libre WebUI, che contiene la proprietà delle attività, i nomi delle risorse Docker o Kubernetes, il routing dei provider, le esecuzioni, i messaggi e le attività; e
• ogni volume Docker o PVC Kubernetes con etichetta ai.libre-webui.managed=true, che contiene i file di Work.

Non è necessario eseguire il backup dei contenitori e dei processi di anteprima temporanei. Per ottenere un backup coerente, impedisci l'avvio di nuove attività Work e arresta il backend prima di acquisire il database e gli spazi di lavoro delle attività. Segui la procedura per gli snapshot dei volumi Docker o del provider di archiviazione Kubernetes relativa al backend in uso.

Ripristina insieme il database e gli spazi di lavoro corrispondenti. Ricrea ogni volume o PVC con il nome esatto registrato nel database e ripristina i relativi metadati di proprietà dell'attività, inclusi ai.libre-webui.task=<task UUID> e ai.libre-webui.managed=true. La copia dei soli file non conserva le etichette Docker o Kubernetes. Il ripristino del solo database produce record di attività privi dei relativi file; il ripristino del solo spazio di archiviazione perde la proprietà delle attività e i nomi delle risorse generate che Libre WebUI usa per individuarlo e convalidarlo.

Se l'installazione usa anche credenziali crittografate dei provider, segui le indicazioni principali per il backup di Libre WebUI relative alla directory dei dati e alla chiave di crittografia.

Localizzazione e scrittura araba da destra a sinistra

L'interfaccia Work completa è tradotta in tutte le 25 lingue supportate: inglese, arabo, bengalese, ceco, danese, tedesco, spagnolo, francese, hindi, indonesiano, islandese, italiano, giapponese, coreano, malese, olandese, polacco, portoghese, russo, svedese, thailandese, turco, ucraino, vietnamita e cinese.

Per l'arabo vengono applicati lang="ar" e dir="rtl" prima del rendering da parte di React. La barra laterale si sposta a destra, Conversazione occupa il lato destro della suddivisione sul desktop, Spazio di lavoro occupa il lato sinistro, le icone direzionali vengono specchiate, la navigazione tramite schede segue l'ordine RTL e il ridimensionamento tramite trascinamento o tastiera usa la semantica visiva RTL.

Il contenuto tecnico resta da sinistra a destra quando la direzione influisce sulla correttezza:

• codice ed evidenziazione della sintassi;
• percorsi del file system;
• identificatori dei modelli;
• comandi e log di anteprima;
• output e metadati degli strumenti; e
• contenuto dei blocchi di codice.

I nomi delle attività, i prompt in linguaggio naturale, gli errori, i nomi dei file e i comandi di anteprima usano automaticamente la direzione del testo appropriata.

Risoluzione dei problemi

Runtime non disponibile quando si usa npx

npx libre-webui esegue il backend sull'host, ma non installa Docker. Esegui docker info con lo stesso utente del sistema operativo che avvia Libre WebUI. Se il comando non è presente o non riesce a raggiungere il daemon, installa o avvia Docker oppure correggi i permessi dell'utente per il daemon, quindi ricarica Work.

Verifica inoltre che Ollama sia integro oppure che almeno un plugin completion/chat attivo disponga di un modello e di credenziali configurati per l'amministratore corrente.

Runtime non disponibile in Docker o Kubernetes

Una distribuzione Compose dal repository non dovrebbe segnalare questo problema: l'immagine include la CLI Docker e il file Compose monta il socket dell'host. Quando accade, il pannello ne indica la causa: una CLI mancante in un'immagine personalizzata, un mount del socket rimosso o assente oppure un gruppo del socket a cui l'utente del contenitore non appartiene. Nell'ultimo caso, imposta DOCKER_GID e ricrea il contenitore. Consulta Eseguire Work quando Libre WebUI si trova a sua volta in Docker.

Su Kubernetes, abilita il runtime nativo con --set work.enabled=true. Libre segnala quindi kubernetes, verifica l'API Kubernetes ed esegue le sandbox come Pod con spazi di lavoro PVC. Non montare il socket del runtime dei contenitori di un nodo; consulta la guida a Kubernetes.

Nessun modello compatibile con Work

Per Ollama, esamina o scegli un modello che dichiari tools. Per un plugin, verifica quanto segue:

• il tipo è completion o chat;
• è attivo;
• il modello esatto appare nella mappa dei modelli configurata;
• l'amministratore corrente dispone di una chiave API utilizzabile; e
• il modello remoto implementa le chiamate agli strumenti per quel provider.

Work non passa mai a un altro provider come fallback.

L'installazione di un pacchetto o un comando Git remoto non riesce

Verifica che il criterio di runtime denominato selezionato per l'attività abiliti l'accesso alla rete. Non esiste alcuna opzione di rete indipendente per singola attività. Controlla quindi la configurazione di DNS, proxy, firewall/NetworkPolicy, registro, certificato, runtime e servizio upstream. Verifica inoltre che l'immagine di runtime selezionata contenga il comando richiamato.

La scheda Git opera solo in locale e non esegue mai operazioni remote. Usa il terminale o l'interfaccia dei comandi del modello solo quando i criteri di rete e delle credenziali dell'attività consentono intenzionalmente Git remoto. Non incollare un token di accesso di lunga durata nello spazio di lavoro di un'attività.

Un'esecuzione si arresta al raggiungimento di un limite dell'agente

Il modello potrebbe aver esaurito il budget configurato di turni o quello di sicurezza derivato per le chiamate agli strumenti. Prima di terminare l'esecuzione, Work richiede un passaggio finale senza strumenti: esamina quindi il lavoro completato e i passaggi rimanenti. L'attività rimane nello stato Input necessario, che è terminale per quell'esecuzione ma, volutamente, non ne dichiara il completamento. Avvia un'esecuzione successiva per continuare nello stesso spazio di lavoro persistente oppure aumenta intenzionalmente WORK_MAX_AGENT_ROUNDS per tutti i provider, se i criteri di costo dell'host e del provider remoto consentono esecuzioni più lunghe.

HTTP 429 all'avvio del lavoro

L'istanza o l'amministratore ha raggiunto un limite di ammissione per i runtime attivi o per le attività persistenti. Attendi l'arresto di un'altra esecuzione o anteprima, elimina le attività obsolete oppure aumenta intenzionalmente la relativa impostazione WORK_MAX_* su un host con risorse sufficienti.

L'anteprima non diventa disponibile

Verifica che il comando rimanga in esecuzione, sia associato a 0.0.0.0 e rimanga in ascolto su WORK_PREVIEW_PORT entro 15 secondi. Se il comando è vuoto, Work rileva automaticamente uno script dev in package.json o un semplice index.html, inclusa una singola app annidata. Se l'errore segnala più app o nessun punto di ingresso supportato, immetti un comando esplicito nel campo facoltativo del comando. I comandi personalizzati vengono avviati in /workspace, quindi usa cd <app-directory> && ... per un'app annidata.

L'anteprima funziona sul server ma non in un browser remoto

Verifica che la distribuzione esegua una build con il proxy firmato per le anteprime Work, quindi riavvia l'anteprima per sostituire eventuali URL di loopback precedenti. Se le pagine normali vengono caricate ma la ricarica a caldo non funziona, verifica che il reverse proxy e il tunnel consentano gli upgrade WebSocket su /api/work/previews/. La porta pubblicata da Docker deve rimanere sul loopback del backend e non richiede l'apertura del firewall.

I file rimangono, ma l'anteprima si è arrestata

È il comportamento previsto dopo un annullamento, il riavvio del backend, l'arresto esplicito dell'anteprima o il mancato superamento dei controlli di disponibilità. Il processo di anteprima è temporaneo; il volume denominato è persistente. Riapri l'attività e riavvia l'anteprima.

Impossibile aprire o salvare un file

L'API integrata per i file accetta file di testo UTF-8 fino a 2 MB. Se durante il salvataggio viene segnalato che il file è cambiato dopo l'apertura, ricaricalo prima di modificarlo nuovamente per evitare di sovrascrivere una modifica apportata da un altro modello o dal browser.

L'evidenziazione della sintassi passa intenzionalmente al testo normale oltre 8,000 caratteri o 400 righe. La formattazione ha un limite distinto di 100,000 caratteri e 4,000 righe e supporta solo le famiglie di file documentate.

Work segnala che sta recuperando le sandbox

Durante l'avvio o lo smantellamento non è stato possibile dimostrare l'arresto di una o più sandbox note. Work rimane in modalità fail-closed e riprova ogni 10 secondi. Ripristina l'accesso al daemon Docker o all'API Kubernetes e controlla il log del backend. Non eliminare le righe delle attività dal database finché le relative risorse di runtime etichettate devono ancora essere riconciliate.

L'eliminazione dell'attività non riesce

Assicurati che il runtime selezionato sia raggiungibile. Una risorsa in conflitto senza l'etichetta ai.libre-webui.task prevista viene intenzionalmente rifiutata anziché rimossa. Risolvi con cautela il conflitto di nome o proprietà, quindi riprova l'eliminazione.

Riepilogo della sicurezza

Prima di abilitare Work per un'installazione, ricorda quanto segue:

• Per impostazione predefinita, Work è riservato agli amministratori; aprirlo a tutti gli utenti rende ogni account attivo un operatore di sandbox, quindi decidi consapevolmente. Gli spazi di lavoro nelle cartelle dell'host restano riservati agli amministratori in ogni modalità.
• Il backend deve controllare il daemon Docker configurato o il namespace delle sandbox Kubernetes.
• I contenitori riducono l'esposizione del file system, ma non sono macchine virtuali.
• Le attività prive di un criterio offline denominato dispongono di traffico di rete in uscita; i criteri denominati ne selezionano l'impostazione predefinita, mentre le restrizioni a livello di destinazione restano una responsabilità dell'operatore.
• I volumi Work non hanno una quota disco indipendente.
• La scheda Git opera solo in locale; le credenziali remote non vengono mai montate né accettate dalla relativa API.
• I criteri del firewall dell'host, l'isolamento del daemon, le restrizioni in uscita e le quote reali dei volumi restano controlli applicati dall'operatore.
• I provider remoti ricevono i risultati richiesti degli strumenti e possono comportare più chiamate per esecuzione.
• Le porte di anteprima rimangono sul loopback del backend e vengono esposte soltanto tramite URL proxy firmati e revocabili.
• Docker Compose standard fornisce il runtime Docker, mentre Kubernetes/Helm fornisce il runtime nativo Pod/PVC quando work.enabled=true.
• Un backup completo richiede sia il database Libre WebUI sia i volumi Work.

Documentazione correlata

• Avvio rapido
• Lavorare con i modelli
• Scorciatoie da tastiera
• Variabili di ambiente
• Docker
• Kubernetes
• Autenticazione
• Risoluzione dei problemi