Executores remotos

Atribuir a um agente um computador real onde trabalhar, em Linux, macOS ou Windows.

O que é um executor remoto

Um agente no Nessie não tem computador. Pode ler o que está no Nessie, falar com as pessoas e chamar ferramentas ligadas através da rede, mas não consegue abrir um ficheiro num portátil, executar um comando nem ver uma página que só existe por trás do início de sessão de alguém. Um executor remoto é a forma de dar a um agente uma máquina onde trabalhar.

Um executor é um pequeno daemon que se instala num computador que se controla. Liga-se por iniciativa própria à instância do Nessie, prova qual é a máquina com uma chave que nunca sai do anfitrião e, depois, oferece um conjunto fixo e com nome de operações — nada mais. O trabalho chega como comandos assinados individuais; os resultados voltam como recibos estruturados e limitados. A máquina nunca aceita uma ligação de entrada vinda do Nessie.

Convém ser preciso quanto ao que um executor não é, porque a maioria das ferramentas de acesso remoto é uma destas coisas, e um executor é deliberadamente nenhuma delas. Não há SSH, nem shell remota ambiente, nem ligação a um multiplexador de terminal que já esteja aberto, nem entrada padrão na cloud, nem proxy geral de rede local. Não é um servidor MCP, nem um contentor, nem um ambiente de execução na cloud — o Nessie já tem esses, e são coisas diferentes. Um executor é um ponto de extremidade com capacidades próprias e uma lista fechada de operações, e essa lista é a superfície inteira.

A quem pertence um executor

Cada executor é criado com exatamente um âmbito, que não pode ser alterado depois. Esse âmbito define quem pode invocar o executor e quem o pode administrar.

Um executor privado tem de ter sempre pelo menos um administrador humano ativo. Remover diretamente o último falha; se uma transação de saída de um colaborador deixar nenhum, o executor deixa de aceitar trabalho novo, esvazia o que tem e revoga-se a si próprio. Um proprietário da organização dispõe de um caminho de revogação de emergência que termina um executor que não gere de outra forma, sem lhe mostrar a lista privada de pessoas, as sessões ou o conteúdo — o acesso privado nunca é transferido em silêncio para outra pessoa.

O que um agente pode realmente fazer com um executor

O vocabulário de operações é fixo no código, não é configurado por instalação. Divide-se em dois grupos, e essa divisão determina o que é preciso instalar: algumas operações o daemon serve a partir do seu próprio diretório temporário, sem qualquer máquina virtual, e as restantes precisam de uma VM convidada por sessão no anfitrião.

As operações que não precisam de convidado formam o pacote de espaço de trabalho. Um anfitrião que não consegue iniciar um convidado não é um executor avariado: emparelha-se normalmente, indica o seu backend de sandbox como none e anuncia apenas o pacote de espaço de trabalho, nada mais. É o estado em que acaba uma edição do Windows sem Hyper-V, ou uma máquina Linux cujo utilizador não pode usar /dev/kvm, e a interface indica-o em vez de falhar de forma obscura.

O trabalho no navegador nunca é algo que um agente inicia por iniciativa própria. A rota normal de vinculação de uma só operação recusa browser.open e browser.observe sem mais; uma execução de navegador é lançada por uma pessoa a partir de um canal, como um pacote de quatro operações numa execução nova, e não se pode acrescentar mais nenhuma vinculação depois. As sessões de programação geridas funcionam da mesma forma.

Existem no código dois outros grupos que estão deliberadamente indisponíveis. As operações para controlar um separador do Chrome em que já tem sessão iniciada têm uma implementação local completa e uma extensão de mensagens nativas, mas o plano de controlo recusa anunciá-las até que o servidor consiga provar que a conversa de origem era privada e registar quem divulgou o quê — a base está inativa de propósito, e a extensão não é distribuída em nenhum dos instaladores. E várias operações de programação — anexar, enviar prompt, interromper e fechar — estão nomeadas no esquema mas não têm implementação, por isso não podem ser concedidas.

Como funciona

A ligação é sempre de saída

O daemon estabelece ligações HTTPS e WSS de saída para a API do Nessie e para mais nada. O Nessie nunca liga para um portátil, nunca guarda um endereço para um e nunca trata um ponto de extremidade do catálogo como transporte para uma máquina. Por isso, um executor funciona a partir de uma rede doméstica, atrás de NAT, numa VPN empresarial, sem reencaminhamento de portas nem regra de firewall de entrada — e por isso parar o daemon é uma desconexão completa e imediata.

A origem da API tem de ser HTTPS. A única exceção é um endereço de loopback para quem executa o Nessie na própria máquina, através de uma variável de ambiente própria; nenhuma opção normal transforma uma origem de produção em HTTP simples.

O emparelhamento prova a máquina, e uma pessoa confirma-a

O emparelhamento é uma prova de dois lados. Uma pessoa com direitos cria o executor no Nessie com o respetivo âmbito, e o Nessie emite uma inscrição: um desafio aleatório de 256 bits, do qual só guarda um verificador SHA-256, válido durante dez minutos e utilizável uma única vez.

Na máquina, o daemon gera um par de chaves Ed25519, guarda-o num armazenamento protegido pelo sistema operativo e acessível apenas ao proprietário, e escreve em disco o pedido assinado exato antes de fazer qualquer chamada de rede — para que uma resposta perdida possa ser repetida com a mesma chave preparada, em vez de emparelhar outra vez em silêncio. Depois envia o identificador da inscrição, o desafio, a sua chave pública e uma assinatura de prova. O Nessie guarda a chave pública e a respetiva impressão digital. Nunca guarda a chave privada.

O Nessie mostra então essa impressão digital a uma pessoa, que a confirma. Até essa confirmação e a prova de posse subsequente, o executor fica offline. O emparelhamento nunca pode ser concluído a partir de texto de conversa ou de uma transcrição de terminal: exige uma ação humana deliberada na interface web ou no desktop.

Uma máquina que perde a chave não consegue recuperar o registo do seu executor. É revogada e inscrita de novo como um executor novo. A rotação de chaves, pelo contrário, é uma transação única assinada pela chave antiga e pela nova.

O descritor é a declaração assinada da máquina sobre si própria

Um daemon emparelhado publica um descritor: uma declaração assinada, com revisões sempre crescentes, que contém apenas factos estruturais — que esquemas de operações suporta, os seus limites de recursos e de rede, a sua plataforma e um digest da sua política local. Não inclui caminhos do anfitrião e não cria autoridade na cloud.

Uma nova revisão nunca é ativada ao chegar. Fica guardada como pendente de revisão, e uma pessoa com direitos tem de a ver e confirmá-la antes de poder afetar o que está disponível. É isso que impede que uma atualização de capacidades conceda poder novo em silêncio: uma operação recém-anunciada começa negada.

Seja claro quanto ao que a assinatura prova. Um descritor assinado pela chave de um executor emparelhado prova que essa chave fez a declaração. Não prova que o anfitrião está incólume, e a interface tem de o dizer.

Despacho: candidato, vinculação, comando, recibo

Um agente nunca escolhe um executor. Antes de uma execução poder usar um, o Nessie resolve a operação lógica num candidato de disponibilidade opaco e de curta duração. A resposta não contém nenhum identificador de executor; a base de dados guarda apenas um digest do identificador, juntamente com quem e para que foi resolvido. Os modelos e os clientes recebem um identificador, não uma máquina selecionável.

A disponibilidade é feita por um único resolvedor, usado de forma idêntica pela API, pelo worker, pela interface e pelo assistente:

available(operation, human, agent, immutableRunContext) =
  human may discover executor
  ∩ exact executor-agent-operation grant allows operation
  ∩ stable logical tool grant allows operation
  ∩ scope matches immutable run context
  ∩ executor is online and descriptor is approved
  ∩ local policy permits operation

Consumir o candidato cria uma vinculação sob um bloqueio da base de dados, que volta a verificar cada uma dessas barreiras e avança uma barreira monotónica. O despacho volta a verificá-las. Consequentemente, uma concessão retirada, uma política restringida ou um executor revogado entre dois passos interrompem o trabalho, em vez de serem notados depois — e uma nova tentativa nunca pode cair numa máquina diferente da que a execução ficou vinculada.

O próprio comando segue a fila normal de tarefas do Nessie e o ciclo de vida das chamadas de ferramentas, em vez de ter uma fila própria. O daemon consulta o trabalho pelo canal de controlo autenticado; nunca recebe dados por iniciativa do servidor. Um comando passa por quatro recibos e por mais nenhum:

leased → accepted → started → result-acknowledged

Cada trama vincula o identificador do comando, a proveniência da execução, a barreira da vinculação, a revisão de capacidades, uma validade, uma chave de idempotência e os digests dos argumentos e da carga. O daemon recusa uma incompatibilidade, uma política desatualizada, uma repetição ou um segundo resultado para um comando que já concluiu. Os argumentos e os resultados finais são cifrados em repouso com AES-256-GCM; a base de dados guarda cifras limitadas e digests canónicos, não o conteúdo.

Se uma confirmação se perder, o Nessie não assume sucesso. O comando fica registado como resultado desconhecido e a execução segue o caminho de recuperação normal; o daemon, que regista localmente cada comando entregue antes de começar a trabalhar, não repetirá o efeito secundário. Um recibo tardio ainda pode resolver a ambiguidade de forma honesta.

Fronteira de confiança

Instalar e emparelhar um executor

Instala-se a CLI para Mac com o Homebrew, as aplicações para Mac com os casks do Homebrew, a CLI para Linux através do APT ou do DNF, ou o executor para Windows através do WinGet. Cada equipa emparelhada tem permissões separadas, guardadas no computador. O Nessie controla o acesso dentro da equipa; não consegue alterar os recursos locais.

O guia de instalação e emparelhamento tem os comandos exatos, o fluxo de código de oito dígitos em dois lados, as definições locais, o arranque, as atualizações e a remoção.

Até onde foi comprovada cada plataforma

O estado das três sandboxes de convidado difere, e a diferença é material. O macOS é o backend com um caminho de convidado funcional e testado. O backend Firecracker no Linux e o backend Hyper-V no Windows estão implementados e cobertos por testes do lado do anfitrião — a sequência de arranque, as imagens de disco, os transportes de controlo e de saída, o protocolo de rascunho —, mas nenhum convidado chegou ainda a arrancar em hardware real na integração contínua deste projeto, porque isso exige uma máquina com KVM ou Hyper-V, e as tarefas que o provariam nunca tiveram uma. O pacote de espaço de trabalho, que não precisa de convidado, é testado de ponta a ponta no Windows contra um ciclo de controlo real. Trate as operações com convidado no Linux e no Windows como não comprovadas até as ter validado no seu próprio hardware. O ecrã de emparelhamento do Nessie diz o mesmo, com as suas próprias palavras.

Segurança e contenção

Uma única raiz do espaço de trabalho, cujo caminho fica na máquina

O emparelhamento seleciona exatamente uma raiz canónica do espaço de trabalho: um diretório, não um conjunto de pastas, e nunca o seu ancestral comum mais próximo. Ao Nessie é indicado o nome base da raiz, para que a pessoa reconheça a fronteira na interface; o caminho completo fica no estado da máquina, acessível apenas ao proprietário, e nunca é carregado. Alterar a raiz é possível, mas só depois de remover todos os rascunhos locais e sandboxes, e produz uma nova revisão do descritor que passa pela mesma revisão humana que qualquer outra alteração de política. Nunca pode alargar-se em silêncio para um diretório pai.

As operações sobre ficheiros aceitam apenas caminhos relativos. Rejeitam a travessia de diretórios e qualquer componente que seja uma ligação simbólica, voltam a verificar que a raiz configurada continua a ser um diretório comum, e devolvem resultados estruturados e limitados que não contêm nenhum caminho do anfitrião.

As escritas vão para uma cópia, e só uma pessoa as promove

Um agente nunca escreve nos seus ficheiros. file.write cria uma árvore limitada, com cópia na escrita, no diretório de estado do próprio daemon, associada à execução; as leituras e listagens posteriores dessa execução veem o rascunho. O trabalho em convidados, incluindo as sessões de programação, usa o mesmo espaço temporário de cópia na escrita.

Aplicar um rascunho ao espaço de trabalho real é uma única operação — workspace.promote — e é a única escrita no anfitrião em todo o sistema. Não tem qualquer esquema voltado para modelos: nenhum agente, nenhum assistente e nenhum caminho fornecido pelo chamador pode transformar um rascunho numa escrita no anfitrião. Em vez disso, uma pessoa abre Os seus rascunhos revistos, carrega em Rever promoção e confirma com a sua palavra-passe atual. O servidor volta então a verificar o digest de revisão confirmado, o digest do manifesto, a execução, o utilizador e o agente de origem, a revisão de autorização, a concessão da operação e a política local ativa, antes de criar o comando. Na máquina, o daemon reconstrói ele próprio o manifesto e recusa um digest que tenha mudado — assim, uma edição feita depois da revisão não pode entrar com a aprovação dessa revisão.

A aplicação em si baseia-se em descritores e fica registada num diário. O auxiliar nativo recebe a raiz do espaço de trabalho e o rascunho já como descritores de diretório abertos, nunca como caminhos; valida cada componente com operações que não seguem ligações, recusa ligações simbólicas, ligações físicas, ficheiros especiais e atravessamentos de pontos de montagem, e mantém um diário de tudo-ou-recuperar, de modo que uma falha a meio conclua o manifesto validado ou restaure o original antes de executar qualquer outra coisa.

O convidado não tem rede, e a saída é forçada

Quando uma operação precisa mesmo de um convidado, este é uma micro-VM Linux por sessão, sem pasta pessoal do anfitrião, sem socket do Docker, sem agente SSH, sem ambiente herdado e sem montagem do anfitrião além da partilha do espaço de trabalho. A montagem do runtime executável é só de leitura; a montagem gravável do espaço de trabalho proíbe a execução, por isso tudo o que corre vem do payload de runtime verificado e não de algo que um agente tenha escrito. O convidado passa a uma identidade sem privilégios antes de abrir qualquer socket, e uma partilha pertencente ao root faz falhar o arranque, em vez de deixar uma carga com privilégios em execução.

Mais importante, o convidado não tem interface de rede. No Linux, a sequência de arranque deliberadamente nunca a configura e não é criado nenhum dispositivo TAP; no Windows, o adaptador de rede virtual que o Hyper-V adiciona por predefinição é removido durante a instalação. A única rota do convidado para fora da máquina é um proxy de loopback dentro dele, encaminhado por um socket virtual até uma ponte no anfitrião, que entrega os bytes ao próprio gateway do daemon — um ouvinte de socket local, acessível apenas ao proprietário, sem ouvinte TCP e sem modo de reencaminhamento geral. É nesse gateway que se aplicam as políticas de HTTP, CONNECT, WebSocket, redirecionamento, origem, transferência e envio, usando a maquinaria de pinned-fetch já existente no Nessie, em vez de uma segunda implementação das mesmas regras. Não há ponte NAT nem resolvedor DNS direto: DNS alternativo, TCP em bruto, QUIC e contorno de proxy são todos negados.

A lista de origens que esse gateway aplica é configurada na máquina pelo seu proprietário, e é deliberadamente nunca carregada. A interface reconhece essa ausência em vez de fingir que o Nessie é um editor de políticas de origem: para saber o que um executor de navegador pode alcançar, é preciso perguntar à pessoa que é dona da máquina.

Credenciais

Nenhum armazenamento de credenciais do anfitrião é alguma vez montado num convidado. Nem o chaveiro, nem ~/.codex ou ~/.claude, nem um token global de CLI, nem uma variável de ambiente com uma chave de API. O único início de sessão suportado para uma sessão de programação gerida é um ficheiro de autenticação privado do proprietário, cujo conteúdo só é lido pelo construtor de initrd controlado pelo proprietário — nunca pelo Nessie, nunca pelo descritor, nunca por um registo ou um argumento de comando — e movido uma única vez para uma pasta pessoal privada dentro do convidado, que é destruída com a VM. Esse convidado só consegue alcançar uma origem.

O executor de navegador é ainda mais restrito: cada sessão recebe um perfil de navegador privado e novo, e recusa um perfil preparado pelo espaço de trabalho, por isso começa sem cookies, sem extensões e sem sessões iniciadas herdadas do ambiente.

Dados locais em bruto só podem chegar a um fornecedor de modelos dentro de uma execução explícita e limitada. O que o Nessie persiste são manifestos redigidos, digests de argumentos e de política, digests de resultados e estado estruturado. Conteúdos de ficheiros, saídas de terminal, DOM do navegador, credenciais e fatores de autenticação são proibidos nos registos da base de dados, na auditoria, nos registos de sistema, nos eventos em tempo real e nos relatórios de erro.

O que um operador concede e como o retira

A permissão para usar um executor não é um único interruptor. Um agente só pode invocar uma operação quando tem uma concessão para esse executor exato e para essa operação exata, e a política lógica normal da ferramenta a permite, e o âmbito da execução corresponde, e a própria política local da máquina a permite. Conceder a um executor uma operação não autoriza, por isso, nada noutro, e uma atualização de capacidades não consegue alargar nada, porque as novas operações chegam negadas.

O acesso dos agentes e a partilha produzem efeito imediato na própria página, sem continuação de aprovação, pedido de palavra-passe ou nova autenticação. No separador Agentes do executor, um gestor liga ou desliga diretamente o acesso de um agente à máquina; em Partilha, concede a uma pessoa Pode utilizar ou Administrador, ou estende o uso a um projeto ou a todos na equipa atual, da mesma forma. Apenas na conversa própria com o assistente — nunca num canal partilhado, numa tarefa agendada ou na execução de outro agente —, o assistente pode preparar uma alteração de acesso de agente ou de atribuição, que publica um cartão de confirmação nessa conversa; nada muda até se carregar em Permitir acesso nesse cartão, e o texto de conversa nunca é confirmação.

Três alterações continuam a exigir que se volte a introduzir a palavra-passe atual no momento da confirmação: ativar uma revisão do descritor; uma atribuição preparada pelo assistente que dá a uma pessoa, e não a um agente, a máquina; e uma política permanente que permite aos colegas iniciar comandos nela como proprietário, a política de trabalho de tarefas sem supervisão. Desligar ou eliminar uma máquina não pede deliberadamente nenhuma das duas, porque um interruptor de emergência nunca deve ser mais difícil de alcançar do que aquilo que trava. A promoção de um rascunho revisto exige sempre. O registo de auditoria regista separadamente a pessoa que atuou e a participação do assistente.

Um executor passa por um conjunto pequeno e explícito de estados:

pending_pairing → online ↔ offline
        │             ↓
        └──────────→ draining → revoked
                         ↓
                       error

O menu Computador do cabeçalho é onde um gestor prepara cada alteração do ciclo de vida: pausar, retomar depois de pausado, desligar ou eliminar. Pausar deixa o executor online, mas para de aceitar comandos. Desligar invalida os seus certificados de cliente e todos os identificadores de candidatos pendentes, e não pode ser desfeito — um executor desligado é emparelhado de novo como um executor novo. Eliminar faz o mesmo e também remove o executor da lista; ao contrário de desligar, é oferecido qualquer que seja o estado do executor, incluindo emparelhamentos pendentes e já desligados, porque é a única forma de sair da lista. Esvaziar — terminar o trabalho que já tem antes de deixar de aceitar mais — é um terceiro estado real no protocolo, e a interface pode mostrar um computador nesse estado, mas nada aqui o inicia: só uma chamada direta à API o faz. Cada alteração de acesso confirmada, revisão de descritor e transição de ciclo de vida, incluindo um esvaziamento, também avança a época de ligação do daemon; por isso, o seu próximo pedido de controlo — no máximo um segundo depois — falha de forma fechada e para cada convidado ativo antes de poder voltar a ligar-se. A revogação não é um pedido que a máquina possa ignorar.

Operar um executor

Verificar se está saudável

A resposta do próprio Nessie é a vivacidade. Um daemon assina um heartbeat, e um executor cuja última atividade autenticada seja mais antiga do que sessenta segundos é marcado de forma durável como offline, antes de poder ser listado, selecionado ou receber despachos. Um executor que aparece como online provou-se a si próprio no último minuto.

Não existe um ponto de extremidade de verificação de estado na máquina — o daemon não escuta em nenhuma porta de operador, por desenho. No macOS e no Linux, pergunte diretamente à CLI:

nessie-executor status                # every paired executor, plus linger state
nessie-executor status <executorId>
systemctl --user status nessie-executor@<executorId>

No macOS, o estado indica o agente launchd de cada equipa. O comando systemctl é exclusivo do Linux. No Windows, o ícone na área de notificação é a resposta imediata, o seu menu indica o motivo, e o registo do serviço contém o detalhe. Em qualquer das plataformas, o separador Visão geral do executor no Nessie mostra os perfis aprovados, o limite de dados, a última vez que foi visto e qualquer proposta de política local pendente à espera de revisão.

Registos

Todas as recusas que uma pessoa pode resolver ficam ali registadas: um runtime não assinado ou adulterado, um diretório de estado que não consegue ficar seguro, um executor que não arrancou com o sistema. O que nunca fica ali registado é um desafio de emparelhamento, uma chave ou a saída de um processo filho. Não há nenhuma definição de nível de registo para aumentar, porque não existe nada mais detalhado para ativar.

A CLI para Mac grava o registo de serviço de cada equipa em ~/Library/Logs/NessieExecutor/<executorId>.log.

Atualizar

Atualiza-se a CLI através do Homebrew, do APT ou do DNF, e depois reinicia-se o serviço de cada equipa com disable seguido de enable. O WinGet atualiza o executor do Windows. Os instaladores diretos do Nessie Desktop oferecem atualizações assinadas dentro da aplicação; as instalações MSI e Debian usam o respetivo gestor de pacotes. Os emparelhamentos e as permissões locais sobrevivem às atualizações.

Parar e remover

Parar é um caminho gracioso que o próprio daemon gere, não um kill. O daemon recebe um sinal de terminação, para todas as sessões de convidado, liberta a sua concessão e termina. No Linux, a unidade espera quinze segundos por um orçamento de desmontagem de dez segundos e nunca escala para um kill impossível de intercetar — porque um daemon morto a meio da desmontagem deixa uma micro-VM e uma sobreposição de espaço de trabalho sem nenhum processo que as limpe. Uma paragem que fica bloqueada é, por isso, visível em systemctl --user status em vez de silenciosa, e escalar é uma decisão humana explícita.

Para remover o pacote Linux:

nessie-executor disable <executorId>   # stops and disables the service
sudo apt remove nessie-executor
loginctl disable-linger                # only if your user manager should stop running at boot too

No Windows, msiexec /x para e remove o serviço, as suas entradas de registo e a entrada de arranque do ícone na área de notificação. Em ambas as plataformas, o estado emparelhado é deliberadamente mantido — ~/.local/state/nessie-executor/ no Linux e %ProgramData%\Nessie Executor no Windows. Um emparelhamento é uma chave da máquina e uma revisão de política assinada, e desinstalar um programa não é um pedido para as destruir; ao reinstalar, o emparelhamento é encontrado onde estava. Para esquecer um emparelhamento, elimina-se o diretório manualmente, e revoga-se o executor no Nessie para o terminar do outro lado.

A área de notificação do Windows e a aplicação auxiliar de desktop oferecem ambas Esquecer o emparelhamento neste computador como ação de primeira classe: para o daemon local, remove a chave da máquina e a seleção de pasta, e elimina de forma permanente as cópias locais dos rascunhos depois de uma confirmação nativa — deixando o executor do lado do servidor e o seu histórico de auditoria para que um proprietário os mantenha ou revogue.

Falhas comuns