Work: workspaces isolados

O Work é a interface nativa do Libre WebUI para agentes de programação. Cada tarefa do Work combina uma conversa persistente, uma rota explícita de modelo/provedor e um sistema de arquivos dedicado em /workspace. O modelo selecionado pode inspecionar e editar arquivos, executar comandos em um contêiner Docker ou Pod do Kubernetes específico da tarefa e iniciar uma prévia no navegador.

O Work é implementado diretamente no Libre WebUI. Ele não exige o Libre Claw nem outro daemon de agentes.

Somente usuários confiáveis

Toda API do Work exige uma conta autenticada com acesso ao Work. Por padrão, isso significa somente administradores; um administrador pode liberar o Work para todos os usuários ativos na aba Gerenciamento de Usuários em Configurações (workspaces em pastas do host permanecem exclusivos para administradores em qualquer caso, pois montam caminhos do servidor). O Work permite deliberadamente que um modelo execute comandos arbitrários de shell dentro de um sandbox. As tarefas usam saída para a rede, a menos que a política de ambiente nomeada selecionada a desabilite. Trate todos que receberem acesso ao Work como operadores confiáveis do ambiente de execução, não apenas como usuários do chat.

Destaques da versão

Esta versão apresenta o Work como um fluxo completo de tarefas:

• Ações separadas Work e Chat na barra lateral principal, com o modo ativo claramente selecionado.
• Tarefas do Work na barra lateral comum, em vez de um segundo painel de tarefas. As posições existentes permanecem estáveis durante as atualizações das execuções, e a tarefa selecionada pode ser excluída diretamente.
• Uma identidade de sandbox dedicada e um volume Docker persistente ou PVC do Kubernetes para cada tarefa. Os sandboxes podem ser interrompidos ou recriados sem excluir os arquivos.
• Conversa, estado das execuções, atividade das ferramentas, seleção de modelo e propriedade da tarefa persistentes no banco de dados do Libre WebUI.
• Um fluxo ao vivo e autenticado da execução para texto do assistente, raciocínio exposto pelo provedor, chamadas e resultados de ferramentas, uso, skills do worker e mudanças de estado.
• Skills do worker controladas pelo servidor que ensinam o modelo selecionado a inspecionar, editar, verificar e gerar prévias com eficiência, sem gravar arquivos de controle no projeto.
• Modelos Ollama locais compatíveis com ferramentas, modelos Ollama Cloud e plugins configurados de conclusão ou chat.
• Uma divisão responsiva entre Conversa e Workspace, com tamanho ajustável por arraste e pelo teclado no desktop e um seletor de superfície focada em telas menores.
• Visualizações integradas de Arquivos, Atividade, Git, Terminal, Prévia e Tela — a visualização Tela é o desktop observável e ensinável do Work Computer.
• Realce de sintaxe nos modos claro e escuro, formatação de código no navegador, detecção de conflitos ao salvar e rascunhos temporários não salvos.
• Um aviso dispensável por usuário quando um provedor remoto de modelo é selecionado.
• Traduções completas do Work nos 25 idiomas compatíveis, inclusive o layout árabe nativo da direita para a esquerda, enquanto código, caminhos, identificadores de modelo e saída de comandos permanecem da esquerda para a direita.

A unidade persistente é o workspace da tarefa, não um contêiner em execução contínua. O Libre WebUI inicia, interrompe e pode recriar o contêiner da tarefa conforme necessário, preservando seu volume nomeado.

Arquitetura

O Libre WebUI — não o modelo nem o navegador — escolhe os nomes do sandbox e do workspace, a imagem, a montagem, o usuário, os limites, o modo de rede e a porta da prévia. O modelo recebe somente estas ferramentas:

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

delete_file e move_file têm as mesmas proteções de caminho das outras ferramentas de arquivo: elas se recusam a sair do workspace, nunca atravessam links simbólicos, exigem uma opção recursiva explícita antes de remover um diretório e nunca sobrescrevem o destino de uma movimentação. Como passam pelo auxiliar de arquivos, não pelo shell, elas também funcionam enquanto uma prévia está ativa, quando run_command fica bloqueado.

As solicitações aos modelos são feitas pelo backend do Libre WebUI. Elas não saem do contêiner do Work nem dependem da política de rede desse contêiner.

Requisitos

O Work precisa de um backend de sandbox configurado:

• O backend padrão exige o Docker instalado, com um daemon acessível e permissão para que o processo do backend invoque docker (ou o executável configurado em WORK_DOCKER_COMMAND).
• O backend do Kubernetes precisa de credenciais da API, além de Role, RoleBinding, namespace de sandboxes e NetworkPolicies com escopo de namespace criados pelo chart Helm quando work.enabled=true.

Todo backend também precisa de:

• Um modelo compatível com ferramentas, exposto por:
  • um serviço Ollama íntegro, inclusive modelos acessados pelo Ollama Cloud; ou
  • um plugin ativo de conclusão/chat com modelo exato configurado e credenciais do administrador atual.
• Armazenamento suficiente no ambiente para a imagem, os projetos gerados e as dependências locais de cada projeto.
• Uma conta autenticada com acesso ao Work. O Work é exclusivo para administradores por padrão; um administrador pode liberá-lo para todos os usuários ativos.

O Libre WebUI verifica os recursos anunciados pelo modelo Ollama antes de criar uma execução e rejeita um modelo que não anuncie tools. Modelos fornecidos por plugins precisam aceitar o protocolo de chamada de ferramentas do provedor. Se um modelo remoto selecionado rejeitar ferramentas, a execução falhará; o Work não muda silenciosamente para outro modelo ou provedor.

Iniciar localmente

Para a configuração compatível mais simples do Work, execute o Libre WebUI e o Docker no mesmo computador do navegador:

docker info
npx libre-webui@latest

Abra http://localhost:8080, entre como administrador, selecione Work na barra lateral, escolha um modelo compatível e descreva o projeto ou a alteração.

Se o Docker estiver ausente, interrompido ou inacessível, o Work mostrará Ambiente indisponível com o motivo informado pelo backend e desabilitará o campo de execução. O Libre WebUI nunca recorre à execução de comandos do Work diretamente no host.

A imagem do ambiente é inspecionada no primeiro uso e baixada automaticamente quando ausente. Por isso, a primeira operação pode demorar mais que as seguintes.

Usar a interface do Work

Criar e reabrir tarefas

Selecione Work ao lado de Chat na barra lateral. Digite uma instrução, escolha um modelo e selecione Executar. A primeira mensagem cria a tarefa, sua primeira execução, sua rota de provedor e seu workspace persistente.

Cada tarefa permanece na barra lateral principal. Ao reabri-la, você recupera a conversa recente, a visualização Arquivos, a seleção atual de provedor/modelo e o workspace. Mensagens mais antigas da conversa podem ser carregadas em páginas. Você pode renomear a tarefa pelo título e excluí-la permanentemente pelo menu da tarefa selecionada ou pela barra lateral.

Somente uma execução pode estar ativa em cada tarefa. Uma instrução posterior cria outra execução sobre a mesma conversa e o mesmo sistema de arquivos.

O campo de composição aceita ditado: um botão de microfone usa a API de fala do navegador, quando disponível, ou um modelo configurado de conversão de fala em texto como alternativa e acrescenta a transcrição ao texto já digitado. Na conversa, arquivos criados ou movidos por uma execução aparecem como etiquetas clicáveis abaixo da atividade da ferramenta correspondente — clicar em uma delas abre o arquivo no editor da visualização Arquivos (e muda para a superfície do workspace em telas estreitas). As etiquetas vêm somente de ferramentas que alteram dados; assim, uma execução que leu vinte arquivos e gravou um mostra exatamente esse único artefato.

Contratar um agente

A tela inicial oferece Contratar como agente quando você tem personas: escolha uma, e a tarefa criada se torna um agente nomeado e persistente, em vez de uma tarefa avulsa. O agente preserva a persona entre as execuções — o nome e o prompt do sistema da persona são acrescentados no início do prompt do sistema do Work (o contrato do ambiente de sandbox sempre tem precedência) —, e a barra lateral fixa os agentes em um grupo Agentes acima das tarefas avulsas, cada um com o avatar da persona, um indicador de atividade e uma linha de status. Com a barra lateral compacta, apenas esses avatares de agentes fixados permanecem na faixa; as tarefas avulsas do Work voltam quando a barra lateral é expandida.

A linha de status tem dois níveis. Para agentes contratados, uma solicitação econômica, sem ferramentas, feita ao modelo no fim da execução pede um status de aproximadamente 8 palavras (“Caixa de entrada zerada. 2 respostas prontas.”); a resposta é limitada a uma única linha de 90 caracteres, e qualquer falha ou tempo limite usa o nível determinístico — a primeira linha da mensagem final do assistente. Tarefas avulsas e execuções com falha usam somente o nível determinístico, e WORK_STATUS_BLURB_MODEL=0 desabilita completamente a solicitação ao modelo. Os agentes também têm um indicador de não lidas: abrir a tarefa avança um marcador visto por tarefa (monotônico e sincronizado entre dispositivos), e a barra lateral mostra um ponto quando uma execução atinge um estado final depois desse marcador.

Os agentes também comunicam suas atividades por notificações — no aplicativo e, quando habilitado, por push: work-run-finished quando uma execução é concluída, work-run-attention quando ela aguarda dados ou falha e work-takeover no momento em que o agente pede que uma pessoa assuma sua tela (o banner aparece somente enquanto a aba Tela está aberta; o push é o que chega a você em outro lugar). Cada notificação abre diretamente o agente.

Você pode contratar usando uma persona sua ou compartilhada com você; a visualização compartilhada nunca expõe as memórias da persona do proprietário. Se a persona for excluída depois, o agente continuará funcionando sem ela e um aviso será registrado. A API aceita personaId e isAgent ao criar a tarefa; uma tarefa criada com persona se torna automaticamente um agente.

A aba Agente

O painel de workspace de um agente começa com uma aba extra, Agente — a página própria do agente:

• Identidade: avatar da persona, nome, indicador de atividade e linha de status mais recente.
• Tela: quando a política da tarefa concede o Work Computer, mostra uma miniatura compacta e ao vivo da tela do agente, somente para visualização. É um visualizador real (conta no limite de visualizadores da tarefa); clicar nele abre a aba Tela completa, onde ficam controle, ensino e áudio.
• Rotinas: automações vinculadas à tarefa. Cada disparo é executado dentro do workspace e da conversa do próprio agente, com seu modelo e ambiente — não em uma tarefa nova —; assim, uma rotina de resumo matinal se acumula em um só lugar. As linhas mostram o agendamento em palavras, com um botão de pausa/retomada, e o formulário inline + Rotina já vem vinculado ao agente. Uma ocorrência disparada enquanto o agente está ocupado falha de forma explícita como work-task-busy, em vez de entrar na fila.
• Revisão automática: o botão de aprovações do agente e as regras de "sempre permitir" que ele já acumulou (remover uma regra fecha o escopo dela de novo). Quando a política da tarefa obriga a revisão, o botão fica travado em ligado.
• Skills ensinadas: procedimentos demonstrados no modo de ensino, cada um com um botão de habilitar/desabilitar.

Ferramentas conectadas (servidores MCP e OpenAPI)

Agentes do Work podem chamar os mesmos servidores de ferramentas configurados para o chat — MCP ou OpenAPI, cadastrados por um administrador em Configurações → Ferramentas. As ferramentas aparecem ao agente com seus nomes qualificados (server__tool), e as chamadas partem do backend do Libre WebUI pelo gateway de ferramentas reforçado (saída protegida contra SSRF, credenciais por usuário, limites de tamanho e de tempo) — nunca de dentro do sandbox.

A oferta é honesta sobre o que uma execução autônoma consegue de fato usar:

• Uma tarefa offline não recebe nenhuma: havendo ou não saída pelo backend, uma tarefa sem acesso à rede permanece offline — a mesma razão que vale para web_search.
• Um servidor que exige uma credencial pessoal que o usuário não guardou é filtrado no momento da oferta, porque uma execução autônoma não pode parar para pedi-la. Cadastre a credencial em Configurações → Ferramentas e a próxima execução já oferece o servidor.
• O modo de acesso às ferramentas (somente administradores ou todos os usuários) e a visibilidade por servidor valem exatamente como no chat, e os vínculos de servidor de uma persona estreitam quais servidores o agente contratado enxerga.
• Quando as aprovações estão ativas, as ferramentas conectadas que o servidor classifica como de efeito colateral param para a sua decisão, como qualquer ação sujeita a controle; as somente leitura executam sem perguntar.

Delegação entre agentes (@menções)

Agentes contratados podem passar trabalho uns aos outros. Digite @ no campo de composição do Work para mencionar outro dos seus agentes; o agente atual vê a lista de colegas (nomes e linhas de status) em suas instruções e delega os pedidos correspondentes com a ferramenta message_agent. A delegação é coordenação por mensagens, deliberadamente não por computadores compartilhados: cada agente mantém seu próprio workspace e sandbox isolados, e o destinatário não enxerga a conversa que delegou — o pedido precisa carregar o próprio contexto.

A delegação é assíncrona. A ferramenta retorna de imediato, o agente de destino roda na sua própria tarefa (a conversa dele mostra o pedido marcado como Delegado por quem enviou) e, quando termina — concluído, precisando de dados, com falha ou cancelado —, a resposta final volta para a conversa do agente que delegou como uma mensagem marcada com Relatório de aquele agente. Se quem delegou ainda estiver executando, o relatório chega ao modelo na rodada seguinte; se estiver ocioso, o relatório simplesmente espera na conversa — um relatório nunca inicia uma execução sozinho, então dois agentes não ficam num vaivém. Execuções delegadas não delegam adiante, um destino ocupado faz a tentativa falhar de forma explícita em vez de entrar na fila e, com as aprovações ativas, message_agent para para revisão como qualquer outra ação de efeito colateral (uma regra de "sempre permitir" fica limitada àquele único agente de destino).

Aprovações de ações (Revisão automática)

Ações de efeito colateral podem parar para a sua decisão antes de executar. Quando as aprovações estão ativas para uma tarefa — a política do Work define Exigir aprovação para ações com efeito colateral ou o botão Revisão automática do agente está ligado —, a execução para antes de rodar run_command, computer_act, delete_file, move_file ou message_agent e mostra um cartão de decisão na conversa: Permitir uma vez, Sempre permitir ou Negar.

• Permitir uma vez executa exatamente esta chamada e pergunta de novo na próxima.
• Sempre permitir executa a chamada e grava uma regra na tarefa: para toda a ferramenta, no caso de ações de arquivo e de computador; limitada ao programa do comando (seu primeiro token), no caso de run_command — aprovar npm run build pré-aprova futuros comandos npm, não o shell inteiro — e limitada ao único agente de destino, no caso de message_agent. As regras ficam listadas na seção Revisão automática da aba Agente e podem ser removidas por lá.
• Negar recusa a chamada. O modelo é informado de que o usuário negou a ação e de que não deve repeti-la como está; a execução continua com essa resposta.

Uma aprovação pendente também gera uma notificação (no aplicativo e, quando habilitado, por push web), porque a execução pode já estar há minutos em trabalho não acompanhado quando chega ao controle. Se ninguém decidir em cinco minutos, o pedido expira, a ação não é executada e a execução termina como Precisa de dados, com uma entrega normal em vez de gastar todo o seu orçamento.

As aprovações controlam ações, não visibilidade: write_file e as ferramentas somente leitura continuam livres, e cada decisão vai para o log de auditoria de segurança.

Entender o status da tarefa

A interface converte os estados persistentes do backend em um conjunto menor para o usuário:

Status na interface	Estado no backend	Cor do indicador
Inativa	idle	rgb(255, 255, 255)
Pensando	preparing ou running	rgb(48, 121, 255)
Concluída	completed	rgb(76, 212, 117)
Precisa de dados	needs_input ou cancelled	rgb(255, 204, 0)
Erro	failed	rgb(255, 61, 129)

Interromper uma execução ativa muda seu estado para Precisa de dados e preserva os arquivos. Esgotar o orçamento de segurança de rodadas ou chamadas de ferramentas também termina em Precisa de dados após a mensagem final sem ferramentas, portanto um trabalho incompleto nunca é marcado como Concluído.

Uma execução ativa não bloqueia a conversa: uma mensagem enviada enquanto o agente trabalha entra imediatamente na conversa e chega ao modelo na rodada seguinte; assim, você pode orientar, corrigir ou acrescentar contexto sem interromper a execução — o botão de parar continua disponível ao lado do envio.

Redimensionar o workspace

No breakpoint xl do desktop, Conversa e Workspace compartilham uma divisão ajustável:

• A largura padrão da conversa é 45%.
• O intervalo preferencial é de 30% a 70%, sujeito às larguras mínimas do conteúdo.
• A proporção salva é associada ao usuário conectado naquele navegador.
• As setas movem o separador em 2%; segure Shift para mover 10%.
• Home e End selecionam o mínimo e o máximo disponíveis.
• Enter ou um clique duplo redefine a divisão.

Os controles acompanham a direção ativa da escrita. Em árabe, Conversa fica à direita e Workspace à esquerda, e o redimensionamento pelo ponteiro e pelas setas continua seguindo a direção visual esperada.

Em telas menores, use o controle Conversa/Workspace no cabeçalho da tarefa para alternar entre as superfícies.

Arquivos

A aba Arquivos percorre os filhos diretos de /workspace, abre somente arquivos de texto UTF-8 válidos e salva as alterações no volume da tarefa. Sequências de bytes inválidas são rejeitadas, em vez de substituídas por caracteres provisórios que perderiam dados.

O editor oferece:

• realce de sintaxe nos modos claro e escuro para linguagens comuns de web, sistemas, scripts, dados e marcação;
• Cmd/Ctrl+S para salvar;
• Shift+Alt+F para formatar arquivos compatíveis;
• detecção otimista de conflitos ao salvar, para impedir que uma visualização antiga sobrescreva silenciosamente um arquivo alterado desde sua abertura;
• rascunhos não salvos por tarefa e caminho no armazenamento de sessão do navegador; e
• avisos de navegação enquanto houver uma edição não salva.

O realce ao vivo é pausado acima de 8.000 caracteres ou 400 linhas para manter o editor responsivo. A formatação está disponível até 100.000 caracteres e 4.000 linhas para JavaScript/JSX, TypeScript/TSX, variantes de JSON, CSS/SCSS/Less, HTML, Markdown/MDX e YAML.

Quando o modelo altera um arquivo aberto, a aba Arquivos mostra uma visualização Alterações em vermelho/verde com exatamente o que foi adicionado e removido desde o início do turno, ocultando trechos longos sem alterações. Um botão na barra de ferramentas alterna entre o diff e o editor, e os contadores +added −removed resumem o turno de imediato. A linha de base da comparação é o último conteúdo visto pelo navegador antes do turno, portanto arquivos abertos pela primeira vez depois do turno não mostram diff.

Os rascunhos no navegador são uma conveniência, não um backup. Eles são apagados após um salvamento bem-sucedido ou a exclusão da tarefa e normalmente desaparecem quando a sessão do navegador termina.

Atividade

A aba Atividade mostra chamadas e resultados de ferramentas, operações de arquivo, saída de comandos e erros. Os metadados das ferramentas podem ser expandidos na conversa. A saída de comandos e ferramentas é exibida da esquerda para a direita, mesmo quando a interface ao redor usa a direção oposta.

Enquanto uma execução está ativa, o Libre WebUI abre um fluxo autenticado de eventos enviados pelo servidor e renderiza o progresso à medida que o backend o recebe. O fluxo pode conter:

• um snapshot inicial e alterações posteriores de run_state;
• reasoning_delta quando o provedor selecionado expõe explicitamente o raciocínio;
• texto assistant_delta;
• atividades tool_call e tool_result;
• medições de usage;
• notificações skill_loaded para orientações do worker fornecidas pelo servidor; e
• eventos finais error ou done.

A disponibilidade e a granularidade do raciocínio dependem do modelo e do provedor. O Libre WebUI mostra somente o conteúdo de raciocínio devolvido pelo provedor por sua API; ele não consegue recuperar cadeias de pensamento ocultas, e alguns modelos não fornecem nenhum fluxo de raciocínio. O texto do assistente e a atividade de ferramentas ainda são transmitidos quando têm suporte independente do raciocínio.

A saída é deliberadamente limitada. Um resultado truncado não comprova que um comando não produziu outra saída; peça ao modelo para inspecionar um resultado mais restrito ou executar um comando mais direcionado.

Git

A aba Git oferece operações locais de controle de versão para o /workspace da própria tarefa:

• inicializar um repositório com uma branch main;
• inspecionar o status porcelain, contagens de ahead/behind e até 20 commits recentes;
• inspecionar um diff textual limitado para um caminho alterado;
• preparar até 200 caminhos selecionados explicitamente por vez;
• criar um commit das alterações preparadas com o nome de usuário e o e-mail do administrador conectado ou um endereço no-reply local da instância quando a conta não tiver e-mail;
• criar uma branch local depois do primeiro commit; e
• mudar para uma branch local existente quando a árvore de trabalho estiver limpa.

Essa interface é intencionalmente somente local. Ela não tem controles de clone, fetch, pull, push, gerenciamento de remotos, comandos Git arbitrários, tokens, chaves SSH nem pull requests. Essas operações precisam de um agente confiável de credenciais separado, de preferência um GitHub App ou token de instalação equivalente, com escopo limitado a um repositório e uma operação. Não coloque credenciais Git de longa duração em /workspace, no ambiente do contêiner da tarefa nem na configuração do repositório.

As leituras do Git podem ser executadas quando a tarefa está inativa ou ativa. Gravações do Git são rejeitadas enquanto uma execução do modelo, um terminal interativo ou uma prévia detém o contêiner da tarefa. Além disso, mudar de branch exige uma árvore de trabalho limpa. Isso impede que a interface dispute os mesmos arquivos com o modelo ou um processo de longa duração.

Todo comando Git da interface é um array fixo de argumentos, executado como UID/GID 1000:1000 dentro do contêiner da tarefa; a entrada do usuário nunca é avaliada por um shell. Para essa interface, o ambiente desabilita a configuração do Git no sistema/global, prompts, hooks, auxiliares de credenciais, assinatura de commits, recursão de submódulos, drivers externos de diff, textconv e protocolos de rede. Ele recusa repositórios cuja árvore de trabalho não seja exatamente /workspace ou cujo diretório Git/comum seja resolvido fora de /workspace. Ações de gravação do Git que poderiam processar conteúdo de arquivos também são bloqueadas quando a configuração do repositório define um filtro executável de clean, smudge ou process.

Esses controles protegem a API Git do Libre WebUI. Um administrador ainda pode usar o Terminal, e o modelo ainda pode usar run_command, para executar comandos Git comuns dentro do sandbox. Portanto, o sandbox e o limite da implantação continuam sendo os controles de segurança para comandos arbitrários.

Skills integradas do worker

Toda execução recebe um guia do workspace controlado pelo servidor. Ele explica o limite persistente de /workspace, a raiz somente para leitura do contêiner, o estado temporário de processos e de /tmp, a política de rede, os limites de comandos e saída e o ciclo de vida da prévia. As skills integradas orientam o modelo a:

• inspecionar instruções do projeto, manifestos, lockfiles, scripts e o estado atual do repositório antes de editar;
• preservar trabalhos não relacionados e agrupar leituras ou pesquisas independentes;
• avançar até a implementação, em vez de parar depois de um plano;
• executar verificações direcionadas antes das mais amplas;
• diagnosticar uma falha, em vez de repetir uma tentativa sem critério; e
• verificar o aplicativo antes de iniciar a prévia como o processo final de longa duração.

O guia existe somente no contexto do modelo. O Libre WebUI não cria um AGENTS.md, diretório de skills nem outro arquivo de controle no workspace do usuário. Instruções fornecidas pelo projeto continuam sendo orientações do projeto e não podem substituir o limite de segurança do contêiner ou das ferramentas.

Terminal

A aba Terminal conecta um shell interativo ao mesmo contêiner em sandbox usado pelo modelo, para que um administrador possa inspecionar o estado, executar um build manualmente ou depurar o que uma execução deixou para trás sem sair do navegador.

O shell usa exatamente a mesma política aplicada a todas as ferramentas do modelo: usuário sem privilégios 1000:1000, diretório de trabalho /workspace e contêiner já reforçado, sem recursos. Um terminal não concede nenhum privilégio além do que a ferramenta run_command do modelo já tem — é uma interface para humanos sobre o mesmo limite, não uma forma de contorná-lo.

Comportamento operacional:

• Autenticação — o navegador troca seu cabeçalho Authorization normal, por HTTP, por um tíquete de curta duração e uso único, vinculado ao protocolo do terminal do Work e à tarefa exata. Somente o tíquete e o ID da tarefa aparecem na URL de upgrade /ws/work-terminal. Antes de cada entrada no shell, o Libre verifica novamente o status atual da conta, o acesso ao Work, a existência e a propriedade da tarefa. A revogação fecha o shell e libera imediatamente sua locação do ambiente.
• Verificações de origem — quando CORS_ORIGIN ou BASE_URL está configurado, os upgrades do navegador devem corresponder a uma dessas origens. Configure pelo menos uma em implantações remotas. Upgrades sem origem continuam disponíveis para o Electron e clientes que não são navegadores, mas ainda exigem o mesmo tíquete vinculado à tarefa e verificações de autorização ao vivo; use TLS, firewall e política de proxy reverso para controlar esses clientes.
• Admissão — um terminal aberto obtém uma locação do ambiente, como um comando ou uma prévia, e conta em WORK_MAX_ACTIVE_RUNTIMES_*.
• Vida útil do contêiner — um terminal conectado mantém o contêiner em execução e impede que o mecanismo de interrupção por inatividade o remova durante a sessão.
• Simultaneidade — WORK_TERMINAL_MAX_SESSIONS_PER_TASK (padrão 2) limita os shells simultâneos por tarefa.
• Tempo limite de inatividade — WORK_TERMINAL_IDLE_TIMEOUT_MS (padrão 15 minutos) fecha uma sessão sem interação e libera sua locação.
• Durante uma execução ativa — a aba explica que o modelo detém o contêiner e abre o shell assim que o turno termina.

O terminal fala diretamente com a API do Docker Engine, pois uma sessão TTY exige um fluxo bidirecional sequestrado que a CLI do Docker só fornece a um terminal de controle real. Ele usa WORK_DOCKER_SOCKET; caso contrário, DOCKER_HOST — um socket unix:// ou endpoint tcp:// em HTTP simples, como um proxy de socket, cujo encaminhamento compatível com HTTP transporta o fluxo sequestrado por um túnel padrão Connection: Upgrade —; ou, por fim, /var/run/docker.sock. Um DOCKER_HOST incompatível com esse cliente (ssh:// ou tcp:// com DOCKER_TLS_VERIFY definido) torna o terminal indisponível e informa o motivo, em vez de conectá-lo silenciosamente a outro lugar; o restante do Work continua funcionando. No backend do Kubernetes, a mesma sessão usa o sub-recurso exec como um WebSocket TTY pelo servidor de API — inclusive os quadros de redimensionamento —, sem qualquer endpoint Docker.

As sessões do terminal são interativas e não são gravadas. Os comandos digitados ali não aparecem na linha do tempo de Atividade da tarefa.

Prévia

A aba Prévia inicia, interrompe, incorpora e abre o aplicativo web gerado. Quando o campo de comando está vazio, o Libre WebUI inspeciona o workspace e:

• executa um script dev do package.json na raiz, com o host e a porta exigidos;
• serve um index.html na raiz com um servidor estático integrado e sem dependências; ou
• usa as mesmas regras para um único aplicativo em um diretório aninhado.

Aplicativos na raiz têm precedência. Se houver vários aplicativos aninhados com a mesma probabilidade ou nenhum ponto de entrada compatível, o Work devolve um erro prático em vez de tentar um comando npm não relacionado. Para outros layouts de projeto ou servidores, digite um comando personalizado antes de selecionar Iniciar prévia. Comandos personalizados começam em /workspace, portanto inclua o diretório relativo quando necessário, por exemplo cd apps/web && npm run dev -- --host 0.0.0.0 --port 4173. Um processo personalizado deve escutar em 0.0.0.0 e na porta configurada em WORK_PREVIEW_PORT. O Work aguarda até 15 segundos para que a porta fique pronta.

O modelo também pode iniciar a prévia com a ferramenta start_preview. Essa é a única forma compatível de um modelo deixar um processo em execução. Chamadas comuns a run_command encerram os processos descendentes em segundo plano quando o comando termina.

Tela (o Work Computer)

Assista à demonstração completa: uma execução real, sem edições (30x e depois em tempo real), de um agente do Work navegando por conta própria nas galerias de imagens da NASA, escolhendo fotos e, em seguida, criando e testando uma galeria interativa em Three.js — tudo a partir de um único prompt.

Uma tarefa cuja política habilita o Work Computer recebe a aba Tela: uma janela ao vivo para um desktop virtual executado dentro do mesmo sandbox — com gerenciador de janelas, dock e navegador Chromium em uma tela de 1280×800. Você pode observar o agente trabalhar, assumir o mouse e o teclado, escutar o áudio do computador e ensinar tarefas por demonstração. Abrir a aba inicia a sessão gráfica sob demanda (nada é executado até que alguém olhe) e conecta um visualizador VNC sobre WebSocket.

Para habilitá-lo, um administrador precisa de um clique: a tela inicial do Work mostra um cartão Work Computer com o botão Habilitar. Pressioná-lo cria a imagem gráfica integrada no daemon Docker da própria implantação (o primeiro build leva alguns minutos) e cria uma política Work Computer pronta — não é preciso executar docker build manualmente nem preencher campos da política. Atrás de um proxy filtrado da API do Docker, o endpoint de build é deliberadamente negado; nesse caso, baixe a imagem publicada no host Docker (ghcr.io/libre-webui/libre-work-computer, com a tag libre-work-computer:latest) ou crie-a ali a partir de deploy/work-computer/; então, Habilitar pula o build e apenas cria a política. As tarefas sob essa política precisam de acesso à rede — a tela é acessada por uma porta do contêiner publicada em loopback, assim como a prévia.

Modelo de segurança: o servidor VNC dentro do contêiner se vincula a localhost e usa duas senhas por sessão — uma somente para visualização, entregue a todo observador autorizado, e outra de controle total, liberada apenas ao detentor atual da locação de controle; assim, o próprio servidor VNC mantém inativas as entradas das demais pessoas. A ponte WebSocket é a única superfície acessível, publicada no loopback do host Docker e nunca exposta diretamente. Cada visualizador se autentica com um tíquete de uso único, vinculado à sessão e à tarefa — o mesmo mecanismo do Terminal —, e o acesso atual ao Work é verificado novamente em todas as conexões; portanto, revogar o acesso de um usuário encerra imediatamente suas telas. Até quatro visualizadores simultâneos podem observar uma tela, e a observação conta como atividade da tarefa na varredura de inatividade. Observar e executar nunca competem: abrir a tela durante a execução do agente conecta-se ao sandbox da própria execução; uma tela observada não impede o início da próxima execução; e a sessão sobrevive ao término da execução — inclusive em implantações de equipe nas quais as execuções ocorrem em outro processo worker. O perfil do navegador persiste em /workspace/.browser-profile, de modo que os logins feitos dentro do computador sobrevivem a reinicializações do contêiner.

Controle pelo agente: uma tarefa com Work Computer oferece ao modelo mais duas ferramentas. computer_observe devolve uma captura de tela completa do desktop, junto com a posição do cursor, a identidade da janela ativa, a URL atual do navegador, se a página — e não a interface do navegador — está com o foco do teclado, uma descrição compacta do elemento focado e um hash da captura; os sinais semânticos vêm de um endpoint DevTools vinculado ao loopback do contêiner e ficam ausentes em imagens gráficas criadas antes de ele existir. computer_act executa um lote de até 24 ações de mouse e teclado (mover, clicar, clicar duas vezes, clicar com o botão direito, digitar, combinações de teclas, rolar, aguardar) e devolve a captura depois que elas se estabilizam. Três proteções do ambiente mantêm a integridade dos lotes: ações type/key podem incluir uma confirmação de focus e falham de forma segura quando o campo esperado não está com o foco do teclado (para que o texto não vá silenciosamente parar na omnibox); um lote termina antecipadamente quando uma janela aparece, o título muda ou o foco se desloca durante sua execução, pois as coordenadas restantes se referiam à tela anterior; e um lote pode declarar um resultado esperado (título, URL ou região alterada da tela), que o ambiente verifica com um prazo adaptativo — “pendente” significa ainda não observado, nunca um sucesso presumido. Depois de um lote, a tela se estabiliza de forma adaptativa (consultada até parar de mudar), em vez de após um atraso fixo. Todo resultado também contém evidências que o modelo é orientado a ler: cliques em coordenadas explícitas devolvem um recibo informando se os pixels próximos mudaram; scroll_until rola em direção a um texto de destino ou à extremidade da página e informa se ele ficou visível; e cada observação é comparada à anterior, indicando explicitamente quando a tela não mudou. Os lotes podem declarar um subgoal de uma linha, que persiste com o resultado como checkpoint e reaparece nos prompts de recuperação. O ciclo do agente detecta travamentos de referência (três ações idênticas em uma tela inalterada geram um aviso de recuperação; a repetição encerra a execução solicitando dados, em vez de gastar as rodadas restantes) e ambiguidade acumulada (expectativas consecutivas não verificadas geram um aviso para restabelecer a referência). A telemetria do ciclo — rodadas, latência das ferramentas, capturas, proteções e decisões sobre expectativas — é registrada em todas as ferramentas persistidas e resumida quando a execução termina.

As capturas de tela chegam ao modelo como conteúdo real de imagem em todas as rotas de provedor — Ollama, Anthropic, Gemini e plugins de chat ou Responses compatíveis com OpenAI —; portanto, o modelo que conduz a tarefa deve ser um modelo de visão. Se o provedor rejeitar a entrada de imagem (um modelo somente de texto), a execução não falha: as capturas são removidas durante o restante da execução, o modelo é orientado a depender das observações textuais e uma nota na transcrição explica a degradação — mas um modelo que não vê a tela verifica muito menos, então prefira um modelo de visão para tarefas no computador. Somente as capturas mais recentes permanecem no contexto ativo do modelo, e as transcrições persistidas da tarefa guardam apenas a observação textual, nunca os bytes da imagem.

O navegador inclui bloqueio de conteúdo integrado — uBlock Origin Lite para anúncios e rastreadores (versão fixada e checksum verificado durante a criação da imagem, com modo de filtragem fixado por política gerenciada) e um dispensador automático de banners de consentimento de cookies —, pois anúncios e avisos de consentimento desperdiçam capturas, tokens e cliques do agente. As solicitações de anúncios são neutralizadas no estilo do uBlock: scripts conhecidos de publicidade são resolvidos como stubs locais inofensivos, para que as páginas continuem funcionando. O agente recebe a instrução de nunca inserir credenciais nem concluir desafios CAPTCHA/2FA; ele informa o impedimento. Para tarefas não confiáveis, combine uma política gráfica com um resolvedor DNS filtrante — um navegador no desktop torna a política de saída da rede ainda mais importante.

Áudio: a tela começa sem som (uma regra do navegador — o áudio exige um clique); o botão de alto-falante no painel Tela transmite ao vivo o som do computador. Dentro do sandbox, o PulseAudio reproduz em um coletor nulo cujo monitor é capturado como PCM bruto e servido por uma segunda ponte WebSocket autenticada e publicada no loopback — com o mesmo tíquete, nova verificação de acesso e limite de visualizadores por tarefa da própria tela. Exige uma imagem gráfica criada a partir de deploy/work-computer/ nesta versão ou posterior.

Controle: o botão Assumir controle no painel Tela fornece o mouse e o teclado — para fazer login, resolver um CAPTCHA ou qualquer etapa que o agente não deva executar —, e Terminei devolve a tela. Uma sessão VNC atende aos dois papéis: o servidor no contêiner mantém uma senha de controle total e outra somente para visualização (geradas por sessão e nunca registradas); observadores recebem apenas a senha de visualização, e a senha de controle é liberada exclusivamente ao detentor atual de uma locação de controle. A locação tem TTL limitado (um controle abandonado expira em até dois minutos), é renovada enquanto a interface de controle permanece aberta e é cooperativa — não pode ser tomada de outro usuário. Uma política pode desabilitar completamente o controle (Permitir controle da tela no editor de políticas): tarefas sob ela ocultam os controles Assumir e Ensinar, o endpoint de controle recusa a ação e a ferramenta request_takeover do agente informa que não há ninguém a quem entregar o controle — a observação continua disponível. Enquanto uma pessoa mantém o controle, computer_observe e computer_act ficam bloqueadas para o agente, que não pode disputar suas entradas nem capturar o que você digita. O agente também pode pedir sua ajuda: sua ferramenta request_takeover publica no painel Tela um banner com o motivo e aguarda até você assumir e devolver o controle. As credenciais inseridas durante o controle vão diretamente do teclado para a página — nunca passam pelo modelo nem pela transcrição da tarefa. O controle exige uma imagem gráfica criada a partir de deploy/work-computer/ nesta versão ou posterior; sessões de imagens antigas continuam observáveis, mas todos têm somente visualização.

Modo de ensino: Ensinar uma tarefa no painel Tela grava uma demonstração — você conduz a tela real (assume o controle como na operação anterior, com um indicador visível de gravação), enquanto as ações de ponteiro, teclado e rolagem são capturadas nas coordenadas da tela. Cada clique também é ancorado: uma sondagem somente para leitura identifica o elemento interativo sob o ponteiro (tag, ID e rótulo visível) e a URL atual da página, para que as etapas do roteiro nomeiem os alvos — “Clique em "button#submit (Place order)"” —, relegando as coordenadas ao lugar em que o controle estava durante a demonstração. Salvar cria um roteiro de forma determinística, sem modelo no ciclo: sequências de teclas viram strings digitadas, clique e arraste são diferenciados por um limite de 8 pixels, pausas viram etapas explícitas de espera, e texto digitado que menciona vocabulário secreto ou parece uma credencial (8+ caracteres combinando três classes de caracteres) é ocultado e substituído por uma instrução para usar request_takeover nessa etapa. O roteiro é um procedimento em linguagem natural — primeiro os alvos ancorados, coordenadas como sugestões, reinterpretadas com computer_observe — com indicações de uso, entradas, etapas, verificação, um escopo permitido derivado dos hosts realmente visitados durante a demonstração (a reprodução deve parar e perguntar antes de sair deles — um procedimento ensinado nunca herda autoridade além do que foi mostrado), limites de aprovação e tratamento de falhas com parada e solicitação de dados. Ele é salvo como uma skill comum (prefixo de slug taught-), portanto aparece na página Skills com versionamento, edição e compartilhamento. Execuções do Work compatíveis com o computador carregam as skills ensinadas habilitadas do proprietário no prompt do sistema e as informam na lista de skills da execução; assim, reproduzir uma tarefa ensinada é apenas uma execução normal cuja solicitação corresponde ao procedimento. Depois de uma execução concluída, as etiquetas da skill oferecem uma avaliação funcionou/falhou com um clique, que acrescenta uma linha datada à seção Histórico da skill (mais recentes primeiro, com limite, cada uma como uma versão comum da skill) — o histórico do procedimento permanece com ele. Não digite senhas reais durante a gravação: demonstre até o login, salve e deixe request_takeover tratar as credenciais na reprodução.

Provedores, roteamento e divulgação de dados

Rotas de provedor compatíveis

Rota	Validação e comportamento
Ollama local	O Ollama deve estar íntegro, e o modelo exato precisa anunciar suporte a ferramentas.
Ollama Cloud	Roteado explicitamente pelo Ollama; modelos com sufixo de nuvem exibem o aviso de provedor remoto.
Plugin de conclusão/chat	O plugin deve estar ativo, listar o modelo exato e ter uma credencial do administrador atual.
Plugin Anthropic	Usa o adaptador de mensagens e uso de ferramentas do Anthropic no Work.
Plugin Gemini	Usa o adaptador de conteúdo e chamadas de função do Gemini no Work.
Outros plugins compatíveis	Usam o formato de solicitação de mensagens, ferramentas e escolha de ferramenta no estilo OpenAI.

O tipo de provedor e o ID do plugin são armazenados tanto na tarefa quanto em cada execução. O nome de um modelo nunca escolhe sozinho a rota. Ativar um plugin com o mesmo nome de modelo que um modelo Ollama não permite interceptar uma tarefa existente.

O que um provedor recebe

Em cada rodada do modelo, o provedor selecionado pode receber:

• o prompt do sistema do Work;
• as skills integradas do worker e os limites atuais do ambiente;
• até as 30 mensagens mais recentes da conversa entre usuário e assistente, com limite de 256 KB;
• as definições das ferramentas do Work;
• o histórico de chamadas de ferramentas do assistente; e
• resultados de ferramentas, que podem incluir listagens de diretório, conteúdo solicitado de arquivos, resultados de pesquisa, saída de comandos e erros.

O volume nomeado não é enviado por inteiro. No entanto, qualquer conteúdo de arquivo ou saída de comando devolvido por uma ferramenta passa a fazer parte da conversa do modelo e é enviado ao provedor selecionado. Analise as políticas de retenção, treinamento, preços e uso dos provedores remotos antes de usar código-fonte confidencial.

As credenciais do provedor permanecem no backend do Libre WebUI, sejam elas configuradas para toda a implantação ou para um usuário. Elas são usadas nas solicitações de modelo do backend e nunca são montadas no contêiner do Work.

A criptografia de credenciais na camada do aplicativo não é uma criptografia da tarefa inteira. Conversas do Work, resultados de ferramentas, saída de comandos e metadados das tarefas são conteúdo comum do banco de dados, enquanto os arquivos e as dependências do workspace são arquivos comuns no volume Docker ou PVC do Kubernetes da tarefa. Use controles de acesso ao host e criptografia de disco quando o modelo de ameaças da implantação exigir criptografia em repouso.

Aviso de provedor remoto

Para fins de aviso, o Work trata modelos de plugins e nomes do Ollama terminados em :cloud ou -cloud como remotos. Selecionar um deles abre um aviso dispensável que explica o fluxo de dados do provedor e a possibilidade de várias chamadas cobradas. A preferência de dispensa é lembrada para cada usuário do Libre WebUI.

Todas as rotas de provedor usam o mesmo orçamento WORK_MAX_AGENT_ROUNDS, com padrão de 48 rodadas. Não há um limite separado de 12 rodadas para plugins. O orçamento de segurança de chamadas de ferramentas é o maior entre 128 chamadas e oito chamadas por rodada configurada. Quando o orçamento de rodadas termina, o Libre WebUI pede ao modelo uma mensagem final sem ferramentas, descrevendo o trabalho concluído, as verificações, os impedimentos e as etapas restantes. Em seguida, registra o estado final da execução como Precisa de dados, em vez de expor uma exceção bruta de limite de rodadas ou marcar o trabalho incompleto como concluído. Uma execução posterior continua no mesmo workspace persistente. Uma única execução do Work ainda pode fazer muitas solicitações cobradas ao provedor.

Workspaces em pastas do host (opcional)

No backend do Docker, o /workspace de uma tarefa normalmente é um volume nomeado existente somente para ela, portanto o modelo não consegue acessar seus arquivos reais. Como alternativa, uma implantação Docker pode permitir que uma tarefa seja vinculada a uma pasta real no host. O Kubernetes rejeita workspaces em pastas do host e usa um PVC pertencente à tarefa.

Defina as duas variáveis e reinicie o backend:

WORK_HOST_WORKSPACES_ENABLED=true
WORK_HOST_WORKSPACE_ROOTS=/Users/you/Projects

WORK_HOST_WORKSPACE_ROOTS é uma lista de raízes separada por :; o padrão é o diretório pessoal do usuário do servidor. Quando o recurso está ativo, a tela inicial do Work recebe um campo opcional Pasta do workspace. Deixe-o vazio para que a tarefa se comporte como antes, com seu próprio volume isolado.

Antes que um caminho seja aceito, ele deve ser absoluto, existir, ser um diretório e ser resolvido — passando por qualquer link simbólico — para um local dentro de uma das raízes configuradas. Diretórios chamados .ssh, .gnupg, .aws, .config, .kube, .docker, .claude, .libre-webui ou node_modules são recusados diretamente. O caminho resolvido é armazenado com a tarefa e mostrado em seu cabeçalho, deixando sempre visível em qual pasta ela trabalha.

Isso reduz o isolamento

Um workspace do host significa que o modelo lê e grava seus arquivos reais, e as outras proteções do contêiner — usuário não root, recursos removidos e limites de recursos — não ficam mais entre ele e esse diretório. Mantenha o recurso desabilitado, a menos que queira usá-lo; limite as raízes ao máximo e prefira diretórios sob controle de versão.

Persistência e ciclo de vida do ambiente

O Libre WebUI separa o estado persistente do estado de execução:

Estado	Armazenamento	Duração
Propriedade, título, provedor e status da tarefa	Banco de dados do Libre WebUI	Até a tarefa ou o usuário proprietário ser excluído
Execuções, erros, mensagens e atividade de ferramentas	Banco de dados do Libre WebUI	Até a tarefa ser excluída
Arquivos do workspace	Volume Docker ou PVC K8s da tarefa	Sobrevivem a cancelamento, parada da prévia e reinícios do sandbox e app
Sistema de arquivos raiz e arquivos temporários	Contêiner ou Pod da tarefa	Descartáveis; podem ser interrompidos ou recriados
Processo da prévia	Sandbox da tarefa em execução	Efêmero; preservado somente enquanto sua integridade é verificada
Rascunho não salvo no editor	Armazenamento de sessão do navegador	Estado temporário e conveniente da sessão do navegador

Toda tarefa recebe um UUID gerado pelo servidor. Os nomes do sandbox e do workspace são derivados no backend e nunca são aceitos de uma solicitação do navegador. O Libre WebUI cria os recursos do ambiente com rótulos de gerenciamento e propriedade da tarefa. Antes de reutilizá-los ou excluí-los, verifica o rótulo de propriedade e recusa um recurso cujo rótulo pertença a outra tarefa.

Os sandboxes são preparados sob demanda. Operações do auxiliar de arquivos interrompem um sandbox que estaria inativo; comandos interrompem o sandbox ao terminar; e uma prévia verificada pode mantê-lo em execução para que o usuário inspecione o aplicativo. O workspace persistente é montado de novo quando o sandbox da mesma tarefa é reiniciado ou recriado.

Administradores podem definir políticas de ambiente nomeadas na aba Gerenciamento de Usuários em Configurações: predefinições que combinam uma imagem do ambiente, limites de memória/CPU/PID, tamanho do workspace (Kubernetes), tempo limite de inatividade, padrão de rede e dois recursos — Work Computer (interface gráfica + navegador), que fornece às tarefas da política um desktop virtual e a aba Tela, e Permitir controle da tela, que decide se uma pessoa pode assumir essas telas (e, como o ensino grava por meio de uma tomada de controle, se o modo de ensino fica disponível). Uma tarefa criada sob uma política usa essa configuração; todo campo deixado vazio herda os valores globais da implantação, e excluir uma política faz suas tarefas voltarem a esses valores na próxima recriação do contêiner. As políticas ajustam apenas recursos e esses dois recursos funcionais — o perfil de reforço (usuário não root, raiz somente para leitura, recursos removidos e isolamento da rede) não é um campo da política e não pode ser enfraquecido individualmente.

WORK_RUNTIME_IDLE_TIMEOUT_MS limita a duração desse período de tolerância da prévia: quando definido, uma varredura interrompe qualquer sandbox que não registre atividade — conclusão de comando, terminal conectado ou solicitação de prévia pelo proxy assinado — por essa quantidade de milissegundos, liberando sua vaga de admissão. Interromper é barato e o workspace persiste, portanto uma prévia inativa simplesmente reinicia no próximo uso. O padrão (0) mantém o comportamento atual: a prévia continua em execução até ser interrompida explicitamente.

Ao iniciar o backend, execuções ativas são marcadas como falhas e o estado das prévias é limpo — o ciclo do agente e o proxy de prévia morreram com o processo e não podem ser retomados. O driver selecionado lista seus contêineres ou Pods gerenciados em uma única consulta por rótulo. Sandboxes em execução e pertencentes a tarefas conhecidas são interrompidos, pois um comando interrompido ainda pode estar ativo sem supervisão; sandboxes já parados não mudam; e sandboxes gerenciados cuja linha de tarefa deixou de existir são removidos. A propriedade vem do rótulo da tarefa, nunca do nome do recurso. A remoção de órfãos pressupõe que uma única instância do Libre WebUI seja proprietária de um namespace do ambiente ou daemon Docker. Não aponte duas instâncias para os mesmos recursos do Work. Se o driver não conseguir comprovar a limpeza, o Work permanece fechado em segurança, tenta novamente a cada 10 segundos e bloqueia novas operações mutáveis até que o acesso ao ambiente seja restaurado.

Comportamento da rede

Verifique a política de rede selecionada

Tarefas sem uma política nomeada de ambiente começam com a rede habilitada. Um administrador pode definir uma política nomeada cujo padrão de rede é desativado, e quem cria a tarefa pode selecionar essa política. Não há um controle de rede independente por tarefa, e alterar a política depois exige recriar o sandbox para que a nova configuração entre em vigor.

No backend do Docker, tarefas com rede conectam-se a uma rede bridge gerenciada e dedicada (libre-webui-work por padrão, WORK_NETWORK_NAME), criada com a comunicação entre contêineres desabilitada (com.docker.network.bridge.enable_icc=false). Isso tem duas consequências:

• um sandbox do Work não consegue abrir conexões para outro sandbox; e
• um sandbox do Work não consegue acessar os próprios contêineres da implantação na bridge padrão compartilhada do Docker, inclusive um banco de dados ou contêiner Ollama no mesmo host que não tenha sido publicado deliberadamente.

O Libre WebUI se recusa a iniciar uma tarefa com rede se já existir uma rede com o nome configurado que não seja a rede gerenciada, em vez de conectar silenciosamente os sandboxes à rede de um operador.

No Kubernetes, o Pod do sandbox recebe o mesmo rótulo de rede habilitada. O chart Helm instala uma NetworkPolicy com negação por padrão, entrada somente para prévia e saída para a internet apenas para Pods com rede, excluindo os work.networkPolicy.blockedEgressCidrs configurados. A NetworkPolicy funciona somente quando o CNI do cluster a aplica; consulte o guia do Kubernetes.

A saída para o mundo externo continua permitida, pois downloads de pacotes, operações Git remotas e APIs externas tornam o Work útil. Isso não é um firewall de saída. O código gerado ainda pode acessar:

• serviços no host Docker;
• sistemas na rede local do host;
• serviços da internet; e
• endpoints de metadados da infraestrutura, dependendo da implantação.

Pontos de integração da política de saída

Para obter um limite mais rigoroso, combine:

• WORK_RUNTIME_DNS (Docker) — endereços IPv4/IPv6 de resolvedores, separados por vírgula, impostos a todo sandbox com rede (--dns). Apontá-lo para um resolvedor filtrante oferece listas de permissão/negação por nome sem modificar o Libre WebUI. Entradas que não são endereços são rejeitadas e registradas, portanto o valor nunca pode injetar outras opções do Docker.
• Regras de firewall no host ou upstream (Docker) para a sub-rede da bridge gerenciada, que é estável porque a rede é nomeada e gerenciada.
• WORK_NETWORK_NAME (Docker) apontando para uma rede criada previamente com suas próprias opções de driver — o Libre WebUI verifica se ela contém o rótulo gerenciado e a opção de ICC desabilitada; portanto, crie-a com ambos.

A filtragem DNS limita a resolução de nomes, não a saída por IP bruto. Uma implantação que precise garantir a ausência de saída direta por IP também requer regras de firewall no host, cluster ou upstream.

Não presuma que colocar código no Work impede a transmissão de dados. Conceda acesso ao Work somente a usuários confiáveis. Use uma política nomeada com rede desabilitada quando uma tarefa precisar começar offline; não há uma variável de ambiente de toda a implantação que altere a política padrão.

O acesso à rede não adiciona credenciais. O Libre WebUI não monta chaves SSH, credenciais de nuvem, perfis do navegador, o diretório pessoal do host nem o socket do Docker nos contêineres das tarefas. Mesmo assim, o código pode transmitir credenciais ou segredos que um usuário ou modelo gravar em /workspace.

Esse tráfego do sandbox é separado do tráfego de modelos. Solicitações ao Ollama e aos plugins são sempre enviadas pelo backend do Libre WebUI à rota de provedor selecionada explicitamente.

Limite de segurança do sandbox

Um contêiner Docker do Work:

• é executado como UID/GID não root 1000:1000;
• usa /workspace como diretório de trabalho;
• monta somente o volume nomeado da tarefa selecionada em /workspace;
• usa um sistema de arquivos raiz somente para leitura e um sistema temporário /tmp limitado;
• remove todos os recursos do Linux;
• habilita no-new-privileges;
• não tem privilégios e usa um processo init;
• aplica limites de CPU, memória, processos, duração de comandos e saída;
• fixa o swap no limite de memória (--memory-swap é igual a --memory), impedindo que o limite seja contornado por swap;
• conecta-se à rede gerenciada do sandbox com comunicação entre contêineres desabilitada ou fica sem rede; e
• publica somente a porta de prévia configurada em uma porta do host atribuída pelo Docker no loopback.

Cada uma dessas propriedades é verificada novamente em docker inspect antes de reutilizar um contêiner, e o conjunto completo é condensado no rótulo de contêiner ai.libre-webui.policy. Um contêiner cuja política seja anterior a uma atualização do Libre WebUI é destruído e recriado, em vez de reutilizado, para que as mudanças de reforço cheguem automaticamente às tarefas existentes.

O driver do Kubernetes aplica o contexto de segurança equivalente no Pod: UID/GID não root, sistema de arquivos raiz somente para leitura, seccomp RuntimeDefault, sem escalonamento de privilégios, todos os recursos removidos, armazenamento efêmero limitado, limites de recursos, sem token de ServiceAccount e um PVC pertencente à tarefa em /workspace. Ele verifica os rótulos da tarefa e a impressão digital da política antes de reutilizar ou excluir um Pod ou PVC.

A validação de caminhos rejeita caminhos absolutos, segmentos de travessia, barras invertidas, caracteres NUL e caminhos longos demais. Os auxiliares de arquivos resolvem caminhos reais e rejeitam escapes por links simbólicos. As gravações usam um arquivo temporário e uma renomeação atômica.

Esses controles reduzem a exposição acidental do host; não transformam o Work em uma máquina virtual nem em um ambiente seguro para análise de malware. Os contêineres compartilham o kernel do host do ambiente. Uma vulnerabilidade no Docker, Kubernetes, ambiente, imagem, dependência ou kernel pode atravessar o limite pretendido.

Volumes nomeados do Docker não têm cota de disco independente. Um projeto gerado ou instalação de pacote pode esgotar o armazenamento do Docker; monitore o crescimento dos volumes e aplique limites de armazenamento no host. O Kubernetes solicita um tamanho de PVC; a aplicação real da cota depende do provisionador de armazenamento selecionado.

Lista de reforço do Docker em produção

Esta lista é específica para o backend do Docker. Operadores do Kubernetes também devem validar o RBAC com escopo de namespace, o contexto de segurança dos Pods, a classe de armazenamento e a aplicação da NetworkPolicy pelo CNI do chart, conforme descrito no guia do Kubernetes.

O aplicativo consegue definir opções dos contêineres, validar caminhos do workspace e proteger sua própria API. Ele não pode aplicar a política de firewall do host, cotas do driver de armazenamento nem o nível de privilégio do daemon Docker recebido. Trate esses itens como trabalho explícito de implantação para uma instância privada do cliente.

1. Isolar o controle do Docker

O contêiner principal do Libre WebUI precisa controlar o daemon para criar e inspecionar contêineres do Work. Um socket do Docker montado é, portanto, uma credencial do plano de controle, não uma montagem de dados comum: comprometer o aplicativo web pode comprometer o host Docker.

A primeira mitigação está incluída neste repositório: docker-compose.socket-proxy.yml mantém o socket completamente fora do contêiner do Libre WebUI. Um proxy de socket detém /var/run/docker.sock em uma rede interna e encaminha somente as seções da API usadas pelo Work — contêineres, imagens, volumes, redes, exec e informações —, enquanto endpoints de swarm, segredos, configs, build, commit e sistema são negados antes de chegar ao daemon. O Libre WebUI aponta para ele com DOCKER_HOST=tcp://docker-socket-proxy:2375 e não precisa montar o socket nem pertencer ao grupo correspondente; a CLI, o terminal interativo e os diagnósticos do Docker também seguem esse endpoint. O proxy reduz a superfície da API, não o impacto potencial dos endpoints encaminhados: quem pode criar contêineres ainda pode montar caminhos do host; portanto, o limite abaixo continua importante.

Para um limite de produção mais forte, execute o Libre WebUI e seu daemon do Work em uma VM dedicada, sem cargas não relacionadas. Para um limite ainda mais forte, forneça ao Work um daemon Docker rootless dedicado ou outro host de ambiente e exponha somente esse daemon ao Libre WebUI. Verifique a propriedade dos arquivos, o roteamento de prévias, a limpeza e o suporte ao terminal com esse daemon antes da implantação. Apenas montar o mesmo socket do host rootful como somente leitura não transforma a API do Docker em somente leitura.

2. Bloquear o acesso do sandbox ao gerenciamento do host

Desabilitar a comunicação entre contêineres impede que sandboxes do Work acessem uns aos outros; não os impede de acessar serviços vinculados ao host Docker. Inspecione a bridge e a sub-rede gerenciadas reais, em vez de presumir um endereço:

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

Use o gerenciador persistente de firewall do host para rejeitar o tráfego que chega dessa bridge aos serviços de gerenciamento do host, principalmente SSH, API do Docker, bancos de dados e portas de monitoramento/administração. Teste a regra a partir de um contêiner descartável conectado a libre-webui-work, teste downloads permitidos de pacotes e, então, torne a regra persistente. A cadeia DOCKER-USER do Docker controla o tráfego encaminhado; o tráfego destinado ao próprio host Docker pode precisar também de uma regra INPUT/gancho de entrada na interface da bridge.

3. Restringir destinos de saída

Bloqueie endpoints de metadados de nuvem, intervalos da infraestrutura privada e intervalos da LAN do cliente para a sub-rede do Work, a menos que um projeto precise deles explicitamente. Combine um resolvedor filtrante por WORK_RUNTIME_DNS com regras de firewall no host ou upstream. A filtragem DNS pode ser contornada por um endereço IP literal. Um proxy HTTP isolado também é insuficiente enquanto comandos arbitrários puderem abrir conexões diretas de rede; aplique a política de roteamento fora do contêiner.

Mantenha políticas nomeadas de ambiente separadas quando os clientes precisarem de comportamentos diferentes, por exemplo, um ambiente offline/sem rede, outro limitado ao registro de pacotes e outro com saída aberta. A política nomeada controla se o Libre conecta a rede do sandbox; regras externas de firewall e proxy continuam aplicando as restrições de destino para uma política com rede.

4. Aplicar cotas reais de armazenamento

Limites de CPU, memória, swap e PID não limitam o volume nomeado. Antes de atender vários clientes, escolha um backend de armazenamento com cotas aplicáveis por workspace: por exemplo, cotas de projeto XFS, volumes lógicos com cota ou um driver de volume/PVC com limite de tamanho. O driver local padrão do Docker em um sistema de arquivos ext4 comum não ganha uma cota confiável por volume apenas porque um valor de tamanho foi documentado.

Monitore cada volume com ai.libre-webui.managed=true e a raiz de dados do Docker, gere alertas antes que o sistema de arquivos fique cheio e teste a falha. Um contador na interface ou verificação periódica por du pode avisar, mas não é um limite aplicável, pois um contêiner pode consumir o disco restante entre as verificações.

5. Verificar a política implantada

Depois de toda mudança na imagem ou na política do daemon, crie uma tarefa descartável do Work e verifique o estado efetivo com docker inspect: UID não root, raiz somente para leitura, todos os recursos removidos, no-new-privileges, limites de memória/swap/CPU/PID, somente o volume da tarefa montado e a rede esperada. Verifique também se o contêiner principal do Libre WebUI tem apenas as montagens pretendidas e se a entrada pública chega ao aplicativo pelo proxy reverso ou túnel autenticado — não por uma porta Docker ou de prévia publicada acidentalmente.

Segurança e acessibilidade da prévia

Para uma tarefa Docker, o driver publica a porta configurada da prévia em uma porta atribuída dinamicamente no loopback do backend. No Kubernetes, o backend dentro do cluster aponta diretamente para o IP do Pod do sandbox. O modelo e o navegador não podem escolher um upstream arbitrário. O Libre WebUI assina uma URL de recurso para a tarefa e o endpoint exatos, verifica em todas as solicitações se a prévia continua em execução e faz proxy do tráfego HTTP e WebSocket por /api/work/previews. Interromper ou reiniciar a prévia revoga a URL antiga.

As respostas da prévia removem credenciais do Libre WebUI e cookies do upstream. O HTML é restringido tanto por um iframe em sandbox quanto por uma CSP de resposta que permite scripts, formulários, modais e downloads sem conceder acesso à mesma origem. A CSP também protege a prévia aberta em outra aba. O código do aplicativo gerado continua sendo não confiável e pode usar a saída de rede para transmitir qualquer dado lido do próprio workspace ou das entradas do navegador. Trate uma URL ativa de prévia como um segredo de curta duração e não a compartilhe.

Como o navegador carrega o proxy na própria origem pública do Libre WebUI, navegadores remotos e proxies reversos HTTPS funcionam sem expor portas do Docker ou IPs de Pods e sem provocar bloqueio de conteúdo misto. Proxies reversos precisam preservar upgrades de WebSocket em /api/work/previews/; a configuração fornecida do Nginx faz isso.

O aplicativo principal permite somente sua própria origem e o Cloudflare Turnstile como origens de frames. As respostas da prévia não passam pela política Helmet principal, permitindo que transmitam corpos de solicitação e apliquem a política de sandbox mais restrita descrita acima. A política de incorporação entre origens permanece desabilitada porque servidores de desenvolvimento gerados normalmente não enviam cabeçalhos de recurso compatíveis.

Matriz de implantação

A disponibilidade do Work acompanha a máquina e o processo que executam o backend do Libre WebUI, não apenas o navegador ou a interface para desktop.

Implantação	Execuções e arquivos do Work	Prévia incorporada
npx libre-webui em um computador local	Compatível quando o Docker está instalado, em execução e acessível pelo usuário do backend.	Compatível pelo proxy assinado na origem do aplicativo.
Desenvolvimento a partir do código-fonte em computador local	Compatível sob os mesmos requisitos de Docker e provedor.	Compatível pela origem da API de desenvolvimento na porta 3001.
Cliente Electron para desktop	Condicional. O Electron usa um backend externo do Libre WebUI e não fornece outro ambiente do Work.	Compatível pela URL de proxy assinada desse backend.
Backend bare metal ou VM em host remoto	Execuções, arquivos e chamadas ao provedor funcionam quando o Docker está disponível no host.	Compatível quando o proxy reverso público preserva o tráfego HTTP e WebSocket.
Docker Compose padrão do repositório	Compatível por padrão no Docker Desktop: a imagem inclui a CLI do Docker, o Compose monta o socket do host e as portas do Work passam por host.docker.internal. O Docker Engine nativo ainda precisa de um WORK_PREVIEW_BIND não público e alcançável.	Compatível pela mesma origem pública do Libre WebUI.
Implantação atual do Kubernetes/Helm	Compatível com --set work.enabled=true: sandboxes são executados como Pods com workspaces em PVC (execuções, arquivos, comandos, Git, terminais interativos e tela e áudio do Work Computer no IP do Pod), sob uma Role com escopo de namespace e NetworkPolicies com negação por padrão — sem socket Docker. Consulte o guia do Kubernetes.	Compatível quando o backend roda no cluster: o proxy assinado aponta diretamente para o IP do Pod.

Executar o Work quando o próprio Libre WebUI está no Docker

Todo arquivo Compose do repositório habilita o Work: a imagem inclui a CLI do Docker, e o arquivo Compose monta /var/run/docker.sock. O Docker Desktop funciona com os padrões de roteamento já incluídos. O Docker Engine nativo precisa, além disso, de WORK_PREVIEW_BIND apontando para uma interface de host não pública e alcançável a partir de contêineres irmãos, como descrito adiante.

O Work controla o daemon do host por esse socket, portanto os contêineres das tarefas são irmãos do contêiner do Libre WebUI, não filhos. Eles aparecem em docker ps no host e são limpos pelas mesmas regras de ciclo de vida de uma instalação nativa.

Montar o socket do Docker em um aplicativo web dá ao contêiner controle sobre o host Docker equivalente ao do root. O Work não funciona sem ele, portanto o Libre WebUI o habilita em vez de fornecer um recurso que silenciosamente não faz nada. A consequência é explícita: todo administrador do Libre WebUI é, na prática, administrador do host Docker. Os operadores são responsáveis pelas consequências para a segurança do daemon, a rede, o ciclo de vida, o backup e o controle de acesso. Exclua a linha /var/run/docker.sock do arquivo Compose para desabilitar o Work; nada mais depende dela.

Para manter o Work sem entregar o socket ao aplicativo web, implante com docker-compose.socket-proxy.yml: um proxy em uma rede interna detém o socket e encaminha somente as seções da API usadas pelo Work, e o Libre WebUI o acessa por DOCKER_HOST. Consulte Isolar o controle do Docker para entender o que esse limite cobre ou não.

Três condições precisam ser atendidas, e o painel do Work informa qual falhou:

1. A CLI do Docker deve existir na imagem. Ela está incluída na imagem oficial; uma imagem personalizada precisa de docker-cli ou de WORK_DOCKER_COMMAND apontando para um executável. Caso contrário: The "docker" CLI is not installed….
2. O socket deve estar montado. Caso contrário: No Docker daemon is reachable….
3. O usuário do backend deve pertencer ao grupo do socket. A imagem é executada como nodejs (uid 1001), e o socket normalmente pertence a root ou docker; assim, o Compose fornece group_add: ['${DOCKER_GID:-0}']. O padrão funciona no Docker Desktop; um host Linux precisa do próprio ID de grupo. Caso contrário: 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

As portas das prévias das tarefas permanecem vinculadas ao loopback do host Docker. O Libre WebUI expõe cada prévia em execução por uma URL de proxy assinada e na mesma origem, inclusive ativos HTTP e upgrades de WebSocket. Isso funciona atrás de HTTPS e túneis remotos sem abrir para a rede as portas efêmeras do Docker. Os documentos da prévia recebem uma política restritiva de sandbox no navegador, e interromper ou reiniciar a prévia revoga sua URL anterior.

Quando o próprio backend roda no Docker, a publicação e a conexão podem usar endereços diferentes. Mantenha WORK_PREVIEW_BIND=127.0.0.1 para não expor as portas efêmeras e defina WORK_DOCKER_PUBLISHED_HOST como o endereço do host Docker acessível pelo contêiner do backend (host.docker.internal no Docker Desktop). Os perfis Compose incluídos definem os dois valores e mapeiam esse nome de host. Implantações nativas do Linux precisam substituir WORK_PREVIEW_BIND pelo gateway da bridge do Docker (ou outra interface de host explicitamente acessível e não pública); mapear apenas host.docker.internal não torna acessível um listener no loopback do host. Nunca vincule essas portas efêmeras brutas a 0.0.0.0.

A simultaneidade é limitada separadamente: WORK_MAX_ACTIVE_RUNTIMES_PER_USER tem padrão 2, e WORK_MAX_ACTIVE_RUNTIMES_GLOBAL, 3; assim, um administrador pode executar uma segunda tarefa enquanto a primeira está ocupada. A resposta de recursos informa ambos os limites e a ocupação atual. Aumente-os se o host tiver memória e CPU disponíveis.

No Kubernetes, instale o chart com work.enabled=true, em vez de expor o socket de ambiente de um nó. O chart cria o RBAC com escopo, o namespace dos sandboxes, as políticas de rede e a configuração de Pod/PVC descritos no guia do Kubernetes.

Configuração do ambiente

O Work lê estas variáveis no processo do backend:

Variável	Padrão	Finalidade
WORK_RUNTIME_BACKEND	docker	Driver do sandbox: docker ou kubernetes
WORK_RUNTIME_IMAGE	node:22.22-bookworm@sha256:2d178f2785b96dfbf62a416ca2e40f50e30150b4ff3320d706f0d96e90600eb3	Imagem usada nos sandboxes das tarefas
WORK_DOCKER_COMMAND	docker	Executável da CLI do backend Docker
WORK_COMMAND_TIMEOUT_MS	120000	Tempo limite padrão dos comandos
WORK_MAX_OUTPUT_CHARS	50000	Máximo capturado da saída de comandos/pesquisa
WORK_MAX_AGENT_ROUNDS	48	Orçamento de rodadas modelo/ferramenta por execução, independente do provedor
WORK_MEMORY_LIMIT	2g	Limite de memória por contêiner
WORK_CPU_LIMIT	2	Limite de CPU por contêiner
WORK_PIDS_LIMIT	256	Limite de processos por contêiner
WORK_PREVIEW_PORT	4173	Porta que o aplicativo deve escutar dentro do contêiner
WORK_PREVIEW_BIND	127.0.0.1	Interface do host na qual a porta da prévia é publicada
WORK_DOCKER_PUBLISHED_HOST	igual a WORK_PREVIEW_BIND	Host/IP que o backend usa para portas do Work publicadas pelo Docker
WORK_COMPUTER_SCREEN_PORT	6080	Porta WebSocket no contêiner para a ponte da tela
WORK_COMPUTER_AUDIO_PORT	6081	Porta WebSocket no contêiner para a ponte de áudio
WORK_RUN_LEASE_WAIT_MS	60000	Tempo que uma execução aguarda um detentor transitório da locação
WORK_MAX_ACTIVE_RUNTIMES_GLOBAL	3	Tarefas simultâneas em contêiner por instância do Libre WebUI
WORK_MAX_ACTIVE_RUNTIMES_PER_USER	2	Tarefas simultâneas em contêiner por administrador
WORK_MAX_TASKS_GLOBAL	500	Limite de tarefas persistidas do Work por instância
WORK_MAX_TASKS_PER_USER	100	Limite de tarefas persistidas do Work por administrador
WORK_NETWORK_NAME	libre-webui-work	Rede bridge gerenciada do sandbox para tarefas com rede
WORK_RUNTIME_DNS	não definido	IPs de resolvedores separados por vírgula, impostos a tarefas com rede
WORK_DOCKER_SOCKET	DOCKER_HOST se unix:// ou tcp://; caso contrário, /var/run/docker.sock	Endpoint do Docker Engine usado por terminais interativos
WORK_TERMINAL_MAX_SESSIONS_PER_TASK	2	Terminais interativos simultâneos por tarefa
WORK_TERMINAL_IDLE_TIMEOUT_MS	900000	Inatividade antes que uma sessão de terminal seja fechada
WORK_RUNTIME_IDLE_TIMEOUT_MS	0 (desabilitado)	Interrompe um sandbox após esse período inativo (inclusive prévias)
WORK_K8S_NAMESPACE	libre-webui-work	Namespace de Pods/PVCs do sandbox no Kubernetes
WORK_K8S_STORAGE_CLASS	padrão do cluster	StorageClass dos PVCs de workspace no Kubernetes
WORK_K8S_WORKSPACE_SIZE	5Gi	Tamanho padrão do PVC por tarefa no Kubernetes
WORK_K8S_POD_READY_TIMEOUT_MS	900000	Espera máxima para que um Pod do sandbox fique pronto
WORK_K8S_POD_GONE_TIMEOUT_MS	60000	Espera máxima para que um Pod excluído desapareça

Use uma versão ou digest fixo da imagem em produção. Uma tag mutável pode alterar tanto as ferramentas de linha de comando disponíveis quanto o limite de segurança sem mudar o Libre WebUI.

Operações de execução, prévia, auxiliar de arquivos, comando e recriação do sandbox compartilham a mesma contabilização de capacidade no processo. Uma operação aninhada em uma tarefa já contabilizada não conta como outra tarefa. Solicitações acima de um limite de admissão da tarefa ou do ambiente devolvem HTTP 429.

Limites fixos do protocolo e da interface

Item	Limite
Mensagem de nova tarefa ou execução	65.536 caracteres e bytes UTF-8
Identificador do modelo na criação/atualização da tarefa	500 caracteres e bytes UTF-8
ID do provedor de plugin	200 caracteres
Execuções ativas por tarefa	1
Texto de comando	20.000 caracteres
Tempo limite de comando solicitado por ferramenta	1 a 600 segundos
Prontidão da prévia	15 segundos
Leitura/gravação de arquivo	2.000.000 bytes de texto UTF-8
Listagem direta de diretório	Primeiras 1.000 entradas
Página de mensagens	Até 200 mensagens e 1.000.000 bytes
Mensagem individual persistida	100 KB
Contexto da conversa enviado ao modelo	Últimas 30 mensagens de usuário/assistente, até 256 KB
Saída persistida de ferramenta	Cerca de 20.000 caracteres-fonte mais um marcador
Realce ao vivo no editor	8.000 caracteres e 400 linhas
Formatação no navegador	100.000 caracteres e 4.000 linhas
Saída do status do Git	2.000.000 caracteres capturados
Saída de diff do Git	600.000 caracteres capturados
Histórico do Git	20 commits locais
Caminhos em uma solicitação de stage do Git	200
Mensagem de commit do Git	4.000 caracteres
Ciclo do agente, todas as rotas de provedor	48 rodadas por padrão, configuradas por WORK_MAX_AGENT_ROUNDS
Orçamento de segurança de chamadas de ferramentas	max(128, configured rounds × 8) chamadas

O acesso a arquivos se destina a texto UTF-8. O editor integrado não é um editor de arquivos binários, e um arquivo com mais de 2 MB não pode ser aberto pela API de arquivos do Work.

Resumo da API

Todos os endpoints ficam sob /api/work e exigem autenticação, além do acesso atual ao Work definido no banco de dados. O Work é exclusivo para administradores por padrão; um administrador pode liberar operações comuns das tarefas para usuários ativos. A seleção de pastas do host e os endpoints administrativos de políticas/acesso permanecem exclusivos para administradores.

Método	Caminho	Finalidade
GET	/capabilities	Disponibilidade e limites do ambiente/provedor selecionado
GET	/tasks	Lista as tarefas do administrador atual
POST	/tasks	Cria uma tarefa e sua primeira execução assíncrona
GET	/tasks/:id	Carrega o estado da tarefa e mensagens recentes
GET	/tasks/:id/messages	Pagina mensagens mais antigas
PATCH	/tasks/:id	Renomeia ou altera a rota explícita do modelo
DELETE	/tasks/:id	Remove a tarefa e o workspace persistente
POST	/tasks/:id/runs	Inicia uma execução posterior
POST	/tasks/:id/messages	Envia uma mensagem ao agente durante uma execução ativa
GET	/tasks/:taskId/runs/:runId/events	Transmite eventos autenticados da execução ao vivo por SSE
POST	/tasks/:id/cancel	Cancela a execução ativa
GET	/tasks/:id/approvals	Aprovações pendentes e a Revisão automática da tarefa
PUT	/tasks/:id/approvals	Alterna a adesão às aprovações na tarefa
POST	/tasks/:id/approvals/:approvalId	Decide uma aprovação pendente (permitir uma vez/sempre, negar)
DELETE	/tasks/:id/approval-rules/:ruleId	Remove uma regra de "sempre permitir"
GET	/computer/setup	Status da configuração do Work Computer (admin)
POST	/computer/setup	Cria a imagem gráfica e a política (admin)
POST	/tasks/:id/computer/start	Inicia a sessão do Work Computer da tarefa
GET	/tasks/:id/computer/control	Quem controla a tela; solicitação de controle do agente
POST	/tasks/:id/computer/control	Assume (ou renova o controle de) a tela
DELETE	/tasks/:id/computer/control	Devolve a tela ao agente
POST	/tasks/:id/computer/teach	Salva uma demonstração gravada como skill ensinada
POST	/tasks/:id/computer/anchor	Identifica o elemento sob um clique gravado
POST	/computer/skills/:slug/trace	Acrescenta uma linha funcionou/falhou a uma skill ensinada
GET	/tasks/:id/files	Lista um diretório do workspace
GET	/tasks/:id/file	Lê um arquivo de texto do workspace
PUT	/tasks/:id/file	Salva um arquivo de texto do workspace
GET	/tasks/:id/git	Lê status e histórico locais protegidos do Git
GET	/tasks/:id/git/diff	Lê um diff local limitado
POST	/tasks/:id/git/init	Inicializa o Git local
POST	/tasks/:id/git/stage	Prepara caminhos explícitos do workspace
POST	/tasks/:id/git/commit	Cria commit das alterações preparadas
POST	/tasks/:id/git/branches	Cria uma branch local
POST	/tasks/:id/git/switch	Muda para uma branch local existente e limpa
POST	/tasks/:id/preview/start	Inicia a prévia gerenciada
POST	/tasks/:id/preview/stop	Interrompe a prévia gerenciada

O ID da tarefa é sempre verificado em relação ao proprietário autenticado. O status atual da conta, a função e a política de acesso ao Work são lidos do banco de dados em cada solicitação, portanto uma revogação entra em vigor mesmo se um JWT mais antigo contiver declarações de função desatualizadas.

O esquema de atualização de tarefas mantém no backend um campo networkEnabled para compatibilidade interna. Ele não aparece como controle independente na interface do Work. Selecione uma política nomeada de ambiente com o padrão de rede pretendido ao criar a tarefa; não use o campo bruto como uma API de configuração persistente.

Exclusão, mudanças de conta e backup

Exclusão de tarefas

A exclusão de uma tarefa é intencionalmente destrutiva:

1. O backend marca a tarefa como em retirada para impedir novas operações mutáveis.
2. Uma execução ativa é cancelada, e o sandbox da tarefa é interrompido.
3. O Libre WebUI valida os rótulos de propriedade nos recursos do ambiente.
4. O contêiner/Pod e o volume nomeado/PVC são removidos.
5. A tarefa é excluída do banco de dados, propagando a exclusão para execuções e mensagens.
6. Os rascunhos dessa tarefa no navegador são limpos depois que a API conclui com sucesso.

Se a limpeza do ambiente falhar, o Libre WebUI mantém o registro da tarefa no banco de dados e devolve um erro, para que o operador possa corrigir o backend do Docker ou Kubernetes e tentar novamente. Ele não exclui silenciosamente os metadados deixando para trás um sandbox ou workspace sem rastreamento.

Interromper uma execução ou prévia é diferente de excluir: isso para a execução, mas preserva o volume nomeado e a conversa.

Rebaixamento de administrador e exclusão de usuário

Quando um administrador é rebaixado, o Libre WebUI persiste a revogação da função antes de depender da limpeza do ambiente. Toda solicitação posterior ao Work verifica a função e o modo de acesso atuais. Em seguida, o backend suspende as tarefas do usuário quando a nova função não tem mais acesso e tenta interromper execuções ativas e seus sandboxes. Se a limpeza falhar, o acesso continua revogado, e a atualização da função informa a falha para que um operador restaure o ambiente e tente novamente.

Excluir outro usuário remove primeiro todos os recursos gerenciados do Work pertencentes a ele. Se a limpeza do ambiente externo falhar, o registro do usuário é mantido para que o administrador tente novamente, em vez de perder os metadados de propriedade necessários para uma limpeza segura.

Fazer backup da tarefa completa

Um backup completo do Work precisa de:

• o banco de dados do Libre WebUI, que contém a propriedade da tarefa, os nomes dos recursos do Docker ou Kubernetes, o roteamento de provedores, as execuções, mensagens e atividade; e
• todo volume Docker ou PVC do Kubernetes rotulado com ai.libre-webui.managed=true, que contém os arquivos do Work.

Os contêineres descartáveis e processos de prévia não precisam de backup. Para obter um backup consistente, interrompa novas atividades do Work e o backend antes de capturar o banco de dados e os workspaces das tarefas. Siga o procedimento de snapshot de volumes do Docker ou do provedor de armazenamento do Kubernetes usado pelo backend.

Restaure em conjunto o banco de dados e seus workspaces correspondentes. Recrie cada volume ou PVC com o nome exato registrado no banco de dados e restaure seus metadados de propriedade, inclusive ai.libre-webui.task=<task UUID> e ai.libre-webui.managed=true. Copiar apenas os arquivos não preserva os rótulos do Docker ou Kubernetes. Restaurar somente o banco de dados produz registros de tarefas sem arquivos; restaurar somente o armazenamento perde a propriedade das tarefas e os nomes de recursos gerados que o Libre WebUI usa para localizá-los e validá-los.

Se a instalação também usa credenciais de provedores criptografadas, siga a orientação geral de backup do Libre WebUI para o diretório de dados e a chave de criptografia.

Localização e árabe RTL

A interface completa do Work está traduzida nos 25 idiomas compatíveis: inglês, árabe, bengali, tcheco, dinamarquês, alemão, espanhol, francês, hindi, indonésio, islandês, italiano, japonês, coreano, malaio, neerlandês, polonês, português, russo, sueco, tailandês, turco, ucraniano, vietnamita e chinês.

O árabe aplica lang="ar" e dir="rtl" antes da renderização do React. A barra lateral passa para a direita, Conversa ocupa o lado direito da divisão no desktop, Workspace ocupa o esquerdo, os ícones direcionais são espelhados, a navegação por abas segue a ordem RTL e o redimensionamento por arraste/teclado usa a semântica visual RTL.

O conteúdo técnico permanece da esquerda para a direita quando a direção afeta sua exatidão:

• código e realce de sintaxe;
• caminhos do sistema de arquivos;
• identificadores de modelo;
• comandos e logs de prévia;
• saída e metadados de ferramentas; e
• conteúdo de blocos de código.

Nomes de tarefas, prompts em linguagem natural, erros, nomes de arquivos e comandos de prévia usam a direção automática do texto quando apropriado.

Solução de problemas

Ambiente indisponível ao usar npx

npx libre-webui executa o backend no host, mas não instala o Docker. Execute docker info como o mesmo usuário do sistema operacional que inicia o Libre WebUI. Se o comando não existir ou não conseguir acessar o daemon, instale/inicie o Docker ou corrija as permissões desse usuário no daemon e recarregue o Work.

Confirme também que o Ollama está íntegro ou que pelo menos um plugin ativo de conclusão/chat tem um modelo e uma credencial configurados para o administrador atual.

Ambiente indisponível no Docker ou Kubernetes

Uma implantação pelo Compose do repositório não deve informar esse erro: a imagem inclui a CLI do Docker, e o arquivo Compose monta o socket do host. Quando isso acontece, o painel identifica a causa — CLI ausente em uma imagem personalizada, montagem do socket removida ou ausente ou usuário do contêiner fora do grupo do socket. Para o último caso, defina DOCKER_GID e recrie o contêiner. Consulte Executar o Work quando o próprio Libre WebUI está no Docker.

No Kubernetes, habilite o ambiente nativo com --set work.enabled=true. O Libre então informa kubernetes, testa a API do Kubernetes e executa sandboxes como Pods com workspaces em PVC. Não monte o socket do ambiente de contêineres de um nó; consulte o guia do Kubernetes.

Nenhum modelo compatível com o Work

Para o Ollama, inspecione ou escolha um modelo que anuncie tools. Para um plugin, confirme que:

• o tipo é conclusão ou chat;
• ele está ativo;
• o modelo exato aparece no mapa de modelos configurado;
• o administrador atual tem uma chave de API utilizável; e
• o modelo remoto implementa chamadas de ferramentas para o provedor.

O Work nunca roteia para outro provedor como alternativa.

Falha ao instalar um pacote ou executar um comando Git remoto

Confirme que a política nomeada de ambiente selecionada para a tarefa habilita o acesso à rede. Não há um botão de rede independente por tarefa. Depois, inspecione a configuração de DNS, proxy, firewall/NetworkPolicy, registro, certificado, ambiente e serviço upstream. Confirme também que a imagem selecionada do ambiente contém o comando executado.

A aba Git é somente local e nunca executa uma operação remota. Use o Terminal ou a superfície de comandos do modelo apenas quando a política de rede e credenciais da tarefa permitir deliberadamente o Git remoto. Não cole um token de acesso de longa duração no workspace de uma tarefa.

Uma execução para no limite do agente

O modelo pode ter esgotado o orçamento configurado de rodadas ou o orçamento derivado de segurança para chamadas de ferramentas. O Work solicita uma mensagem final sem ferramentas antes de encerrar a execução; portanto, revise o trabalho concluído e as etapas restantes. A tarefa permanece em Precisa de dados, que é o estado final dessa execução, mas deliberadamente não a declara concluída. Inicie outra execução para continuar no mesmo workspace persistente ou aumente deliberadamente WORK_MAX_AGENT_ROUNDS para todos os provedores se o host e a política de custos do provedor remoto permitirem execuções mais longas.

HTTP 429 ao iniciar o trabalho

A instância ou o administrador atingiu um limite de admissão de ambientes ativos ou tarefas persistidas. Aguarde outra execução ou prévia parar, exclua tarefas obsoletas ou aumente deliberadamente a configuração WORK_MAX_* correspondente em um host com recursos suficientes.

A prévia não fica pronta

Confirme que o comando permanece em execução, vincula-se a 0.0.0.0 e escuta em WORK_PREVIEW_PORT em até 15 segundos. Com um comando vazio, o Work detecta automaticamente um script dev no package.json ou um index.html simples, inclusive em um único aplicativo aninhado. Se o erro informar vários aplicativos ou nenhum ponto de entrada compatível, forneça um comando explícito no campo opcional. Comandos personalizados começam em /workspace; portanto, use cd <app-directory> && ... para um aplicativo aninhado.

A prévia funciona no servidor, mas não em um navegador remoto

Confirme que a implantação executa um build com o proxy assinado de prévia do Work e reinicie a prévia para substituir qualquer URL de loopback antiga. Se as páginas comuns carregarem, mas a atualização em tempo real não, confirme que o proxy reverso e o túnel permitem upgrades de WebSocket em /api/work/previews/. A porta publicada pelo Docker deve permanecer no loopback do backend e não precisa ser liberada no firewall.

Os arquivos permanecem, mas a prévia parou

Isso é esperado após um cancelamento, reinício do backend, interrupção explícita da prévia ou falha nas verificações de prontidão. O processo da prévia é efêmero; o volume nomeado é persistente. Reabra a tarefa e inicie a prévia novamente.

Não é possível abrir ou salvar um arquivo

A API integrada de arquivos aceita texto UTF-8 de até 2 MB. Se o salvamento informar que o arquivo mudou desde sua abertura, recarregue-o antes de editar novamente para não sobrescrever uma alteração de outro modelo ou navegador.

O realce de sintaxe muda intencionalmente para texto simples acima de 8.000 caracteres ou 400 linhas. A formatação tem limites separados de 100.000 caracteres e 4.000 linhas e aceita somente as famílias de arquivos documentadas.

O Work informa que está recuperando sandboxes

A inicialização ou o encerramento não conseguiu comprovar que um ou mais sandboxes conhecidos foram interrompidos. O Work permanece fechado em segurança e tenta novamente a cada 10 segundos. Restaure o acesso ao daemon Docker ou à API do Kubernetes e inspecione o log do backend. Não exclua linhas de tarefas do banco de dados enquanto os recursos rotulados do ambiente ainda precisarem ser reconciliados.

A exclusão da tarefa falha

Confirme que o ambiente selecionado está acessível. Um recurso conflitante sem o rótulo esperado ai.libre-webui.task é rejeitado intencionalmente, em vez de removido. Resolva com cuidado o conflito de nome/propriedade e tente excluir novamente.

Resumo de segurança

Antes de habilitar o Work em uma instalação, lembre-se:

• O Work é exclusivo para administradores por padrão; liberá-lo para todos os usuários transforma cada conta ativa em operador de sandbox, portanto tome essa decisão de forma deliberada. Workspaces em pastas do host permanecem exclusivos para administradores em todos os modos.
• O backend deve controlar o daemon Docker configurado ou o namespace de sandboxes no Kubernetes.
• Contêineres reduzem a exposição do sistema de arquivos, mas não são máquinas virtuais.
• Tarefas sem uma política nomeada offline têm saída de rede; as políticas nomeadas escolhem o padrão, enquanto as restrições por destino continuam sendo responsabilidade do operador.
• Volumes do Work não têm cota de disco independente.
• A aba Git é somente local; credenciais remotas nunca são montadas nem aceitas por sua API.
• A política de firewall do host, o isolamento do daemon, as restrições de saída e as cotas reais de volume continuam sendo controles aplicados pelo operador.
• Provedores remotos recebem os resultados solicitados das ferramentas e podem gerar várias chamadas por execução.
• Portas de prévia permanecem no loopback do backend e são expostas somente por URLs de proxy assinadas e revogáveis.
• O Docker Compose padrão fornece o ambiente Docker, e o Kubernetes/Helm fornece o ambiente nativo de Pod/PVC quando work.enabled=true.
• Um backup completo exige o banco de dados do Libre WebUI e os volumes do Work.

Documentação relacionada

• Início rápido
• Trabalhar com modelos
• Atalhos de teclado
• Variáveis de ambiente
• Docker
• Kubernetes
• Autenticação
• Solução de problemas