Executor remoti

Dai a un agente un vero computer su cui lavorare — su Linux, macOS o Windows.

Che cos’è un executor remoto

Un agente in Nessie non ha un computer. Può leggere ciò che c’è in Nessie, parlare con le persone e richiamare strumenti collegati attraverso la rete, ma non può aprire un file su un portatile, eseguire un comando o guardare una pagina che esiste solo dietro il login di qualcuno. Un executor remoto è il modo per dargli una macchina su cui lavorare.

Un executor è un piccolo daemon che installi su un computer che controlli. Si associa verso l’esterno con la tua istanza di Nessie, dimostra quale macchina è con una chiave che non lascia mai l’host e poi offre un insieme fisso e con nome di operazioni — niente altro. Il lavoro arriva come singoli comandi firmati; i risultati tornano come ricevute strutturate e di dimensione limitata. La macchina non accetta mai una connessione in entrata da Nessie.

Vale la pena essere precisi su ciò che un executor non è, perché la maggior parte degli strumenti di accesso remoto è una di queste cose, e un executor non lo è di proposito. Non c’è SSH, non c’è una shell remota ambientale, non c’è il collegamento a un multiplexer di terminale che hai già aperto, nessuno standard input dal cloud e nessun proxy generale della rete locale. Non è un server MCP, e non è un container né un ambiente di esecuzione in cloud — Nessie ha già quelli, ed è un’altra cosa. Un executor è un endpoint che porta con sé una capacità, con un elenco chiuso di operazioni, e quell’elenco è l’intera superficie.

A chi appartiene un executor

Ogni executor viene creato con esattamente un ambito, che non può essere cambiato in seguito. L’ambito decide chi può invocare l’executor e chi può amministrarlo.

Un executor privato deve avere sempre almeno un amministratore umano attivo. Rimuovere direttamente l’ultimo fallisce; se una transazione di offboarding ne lascerebbe nessuno, l’executor smette di accettare nuovo lavoro, finisce il lavoro che ha già in corso e si revoca da solo. Un proprietario dell’organizzazione ha un percorso di emergenza che serve solo a revocare: termina un executor che non gestisce altrimenti, senza mostrargli il suo elenco privato, le sue sessioni o i suoi contenuti. L’accesso privato non viene mai trasferito in silenzio a qualcun altro.

Che cosa può fare davvero un agente con un executor

Il vocabolario delle operazioni è fissato nel codice, non configurato per ogni installazione. Si divide in due, e questa divisione decide che cosa devi installare: alcune operazioni il daemon le serve dalla propria directory di lavoro temporanea senza alcuna macchina virtuale, mentre le altre richiedono una VM ospite per sessione sull’host.

Le operazioni che non richiedono una guest formano il pacchetto dell’area di lavoro. Un host che non riesce ad avviare una guest non è un executor guasto: si associa normalmente, segnala il proprio backend sandbox come none e pubblicizza solo il pacchetto dell’area di lavoro, nient’altro. È lo stato in cui finisce un’edizione di Windows senza Hyper-V, o una macchina Linux il cui utente non può usare /dev/kvm, e l’interfaccia lo dichiara invece di fallire in modo oscuro.

Il lavoro sul browser non viene mai avviato da un agente di sua iniziativa. La normale rotta di binding a singola operazione rifiuta browser.open e browser.observe senza eccezioni; un’esecuzione del browser viene avviata da una persona da un canale, come un unico pacchetto di quattro operazioni su un’esecuzione nuova, e non si può aggiungere nessun altro binding in seguito. Le sessioni di coding gestite funzionano allo stesso modo.

Nel codice esistono altri due gruppi, che sono volutamente non disponibili. Le operazioni per pilotare una scheda Chrome in cui sei già connesso hanno un’implementazione locale completa e un’estensione di native messaging, ma il control plane si rifiuta di pubblicizzarle finché il server non può dimostrare che la conversazione di origine era privata e registrare chi ha rivelato che cosa. La base è inerte di proposito, e l’estensione non viene distribuita in nessuno dei due installer. Inoltre diverse operazioni di coding — attach, prompt, interrupt e close — sono nominate nello schema ma non hanno implementazione, quindi non possono essere concesse.

Come funziona

La connessione è sempre in uscita

Il daemon apre connessioni HTTPS e WSS in uscita verso la tua API di Nessie, e basta. Nessie non contatta mai un portatile, non conserva un indirizzo per nessuno e non tratta mai un endpoint del catalogo come un canale verso la macchina. Per questo un executor funziona da una rete domestica, dietro NAT, su una VPN aziendale, senza port forward e senza regola del firewall in entrata. È anche il motivo per cui fermare il daemon significa disconnettersi in modo completo e immediato.

L’origine dell’API deve essere HTTPS. Unica eccezione: un indirizzo loopback per chi usa Nessie sulla propria macchina, tramite una variabile d’ambiente dedicata. Nessun flag ordinario trasforma un’origine di produzione in HTTP semplice.

L’associazione verifica una macchina, e una persona la conferma

L’associazione è una prova a due lati. Una persona autorizzata crea l’executor in Nessie con il suo ambito, e Nessie emette una registrazione: una sfida casuale a 256 bit di cui conserva solo un verificatore SHA-256, valida per dieci minuti e utilizzabile una sola volta.

Sulla macchina il daemon genera una coppia di chiavi Ed25519, la conserva in un archivio protetto dal sistema operativo e accessibile solo al proprietario, e scrive su disco la richiesta firmata esatta prima di fare qualsiasi chiamata di rete. Così una risposta persa può essere ritentata con la stessa chiave già preparata, invece di associarsi in silenzio due volte. Poi invia l’id della registrazione, la sfida, la sua chiave pubblica e una firma di prova. Nessie conserva la chiave pubblica e la sua impronta. Non conserva mai la chiave privata.

Nessie mostra poi quell’impronta a una persona, che la conferma. Fino a quella conferma e a una successiva prova di possesso, l’executor resta offline. L’associazione non può mai essere completata da un testo in chat o dalla trascrizione di un terminale: richiede un’azione umana deliberata nell’interfaccia web o desktop.

Una macchina che perde la propria chiave non può recuperare il proprio record di executor. Viene revocato e registrato di nuovo come nuovo executor. La rotazione della chiave, invece, è un’unica transazione firmata sia dalla vecchia chiave sia dalla nuova.

Il descrittore è l’affermazione firmata della macchina su sé stessa

Un daemon associato pubblica un descrittore: un’affermazione firmata, con revisione monotona, che contiene solo fatti strutturali — quali schemi di operazione supporta, i suoi limiti di risorse e di rete, la sua piattaforma e un digest della sua politica locale. Non contiene percorsi dell’host e non crea alcuna autorità nel cloud.

Una nuova revisione non viene mai attivata appena arriva. Viene conservata in attesa di revisione, e una persona autorizzata deve vederla e confermarla prima che possa influire su ciò che è disponibile. È ciò che impedisce a un aggiornamento delle capacità di concedere in silenzio nuovi poteri: un’operazione appena annunciata parte negata.

Sii chiaro su che cosa prova la firma. Un descrittore firmato dalla chiave di un executor associato prova che quella chiave ha fatto l’affermazione. Non prova che l’host sia integro, e l’interfaccia è tenuta a dirlo.

Invio: candidato, binding, comando, ricevuta

Un agente non sceglie mai un executor. Prima che un’esecuzione possa usarne uno, Nessie risolve l’operazione logica in un candidato di disponibilità opaco e di breve durata. La risposta non contiene alcun id di executor; il database conserva solo un digest dell’handle, insieme a chi e per che cosa è stato risolto. Modelli e client ricevono un handle, non una macchina da scegliere.

La disponibilità è un unico resolver, usato in modo identico da API, worker, interfaccia e 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

Consumare il candidato crea un binding sotto un lock del database che ricontrolla ognuno di quei controlli una seconda volta e fa avanzare un fence monotono. L’invio li ricontrolla ancora. Ne consegue che un permesso revocato, una politica ristretta o un executor revocato tra due passaggi fermano il lavoro invece di essere notati dopo — e un tentativo non può mai atterrare su una macchina diversa da quella a cui l’esecuzione era associata.

Il comando stesso viaggia sulla normale coda di lavoro di Nessie e sul ciclo di vita delle chiamate di strumento, invece che su una coda propria. Il daemon interroga il lavoro sul proprio canale di controllo autenticato; non viene mai spinto. Un comando attraversa quattro ricevute e nessun’altra:

leased → accepted → started → result-acknowledged

Ogni frame lega l’id del comando, la provenienza dell’esecuzione, il fence del binding, la revisione della capacità, una scadenza, una chiave di idempotenza e i digest sia degli argomenti sia del payload. Il daemon rifiuta una mancata corrispondenza, una politica obsoleta, un replay o un secondo risultato per un comando che ha già completato. Argomenti e risultati finali sono cifrati a riposo con AES-256-GCM; il database conserva cifrature limitate e digest canonici, non il contenuto.

Se una conferma va persa, Nessie non presume il successo. Il comando viene registrato come esito sconosciuto e l’esecuzione segue il normale percorso di recupero. Il daemon, che registra localmente ogni comando consegnato prima di iniziare il lavoro, non ripeterà l’effetto collaterale. Una ricevuta tardiva può ancora risolvere l’ambiguità in modo onesto.

Confine di fiducia

Installare e associare un executor

Installa la CLI per Mac con Homebrew, le app per Mac con i cask di Homebrew, la CLI Linux tramite APT o DNF, oppure l’executor Windows tramite WinGet. Ogni team associato ha permessi separati, memorizzati sul computer. Nessie controlla gli accessi all’interno del team; non può cambiare le risorse locali.

La guida all’installazione e all’associazione contiene i comandi esatti, il flusso a due lati con il codice di otto cifre, le impostazioni locali, l’avvio, gli aggiornamenti e la rimozione.

Fino a che punto ogni piattaforma è stata davvero verificata

Lo stato dei tre sandbox guest è diverso, e la differenza è rilevante. macOS è il backend con un percorso guest funzionante e già testato. Il backend Firecracker su Linux e il backend Hyper-V su Windows sono implementati e coperti da test lato host — la sequenza di avvio, le immagini disco, i trasporti di controllo e di uscita, il protocollo delle bozze — ma nessuna guest è ancora stata avviata su hardware reale nell’integrazione continua di questo progetto, perché serve una macchina con KVM o Hyper-V e i job che lo dimostrerebbero non ne hanno mai avuta una. Il pacchetto dell’area di lavoro, che non richiede alcuna guest, è verificato da cima a fondo su Windows con un vero ciclo di controllo. Considera le operazioni con guest su Linux e Windows come non verificate finché non le hai provate sul tuo hardware. Anche la schermata di associazione in Nessie lo dice con parole sue.

Sicurezza e contenimento

Un’unica radice dell’area di lavoro, e il suo percorso resta sulla macchina

Durante l’associazione viene scelta esattamente una radice canonica dell’area di lavoro: una directory, non un insieme di cartelle, e mai il loro antenato comune più vicino. A Nessie viene comunicato solo il nome base della radice, così una persona può riconoscere il confine nell’interfaccia. Il percorso completo resta nello stato della macchina accessibile solo al proprietario e non viene mai caricato. Cambiare la radice è possibile, ma solo dopo aver rimosso ogni bozza locale e ogni sandbox, e produce una nuova revisione del descrittore che passa per la stessa revisione umana di ogni altra modifica di politica. Non può mai allargarsi in silenzio a una directory superiore.

Le operazioni sui file accettano solo percorsi relativi. Rifiutano l’attraversamento e ogni componente che sia un link simbolico, ricontrollano che la radice configurata sia ancora una directory ordinaria e restituiscono risultati strutturati limitati che non contengono alcun percorso dell’host.

Le scritture vanno su una copia, e solo una persona le applica

Un agente non scrive mai nei tuoi file. file.write crea un albero copy-on-write limitato nella directory di stato del daemon, legato all’esecuzione; le letture e gli elenchi successivi di quell’esecuzione vedono la bozza. Il lavoro nella guest, comprese le sessioni di coding, usa la stessa area di scratch copy-on-write.

Applicare una bozza all’area di lavoro reale è un’unica operazione — workspace.promote — ed è l’unica scrittura sull’host in tutto il sistema. Non ha affatto uno schema rivolto ai modelli: nessun agente, nessun assistente e nessun percorso fornito dal chiamante può trasformare una bozza in una scrittura sull’host. Invece, una persona apre Le tue bozze verificate, preme Rivedi applicazione e conferma con la password attuale. Il server ricontrolla allora il digest di revisione confermato, il digest del manifest, l’esecuzione di origine, l’utente e l’agente, la revisione dell’autorizzazione, la concessione dell’operazione e la politica locale attiva prima di creare il comando. Sulla macchina il daemon ricostruisce da solo il manifest e rifiuta un digest cambiato, così una modifica fatta dopo la revisione non può passare con l’approvazione della revisione.

L’applicazione vera e propria è basata su descrittori ed è registrata in un journal. Il componente nativo riceve la radice dell’area di lavoro e la bozza come descrittori di directory già aperti, mai come percorsi. Valida ogni componente con operazioni che non seguono i link, rifiuta link simbolici, link fisici, file speciali e attraversamenti di mount, e mantiene un journal tutto-o-ripristino: così un crash o completa il manifest validato o ripristina l’originale prima che venga eseguito qualsiasi altro passaggio.

La guest non ha rete, e l’uscita è forzata

Quando un’operazione richiede davvero una guest, si tratta di una micro-VM Linux per sessione, senza home dell’host, senza socket Docker, senza agente SSH, senza ambiente ereditato e senza mount dell’host diverso dalla condivisione dell’area di lavoro. Il mount eseguibile del runtime è di sola lettura; il mount scrivibile dell’area di lavoro vieta l’esecuzione, quindi tutto ciò che viene eseguito proviene dal payload del runtime verificato e non da qualcosa che un agente ha scritto. La guest passa a un’identità senza privilegi prima di aprire qualunque socket, e una condivisione di proprietà di root fa fallire l’avvio invece di lasciare in esecuzione un carico di lavoro privilegiato.

Soprattutto, la guest non ha alcuna interfaccia di rete. Su Linux la sequenza di avvio di proposito non ne configura una, e non viene creato alcun dispositivo TAP; su Windows l’adattatore di rete virtuale che Hyper-V aggiunge di default viene rimosso durante l’installazione. L’unica via della guest verso l’esterno della macchina è un proxy loopback al suo interno, incanalato su un socket virtuale verso un bridge sull’host, che consegna i byte al gateway del daemon stesso: un listener di socket locale accessibile solo al proprietario, senza listener TCP e senza modalità di inoltro generale. È in quel gateway che vengono applicate le politiche di HTTP, CONNECT, WebSocket, redirect, origine, download e upload, usando il meccanismo di pinned-fetch già esistente di Nessie invece di una seconda implementazione delle stesse regole. Non esistono bridge NAT né resolver DNS diretto: DNS alternativi, TCP grezzo, QUIC e il bypass del proxy sono tutti negati.

La lista di origini che quel gateway applica è configurata sulla macchina dal suo proprietario e, di proposito, non viene mai caricata. L’interfaccia dichiara questa assenza invece di fingere che Nessie sia un editor delle politiche di origine: per sapere che cosa può raggiungere un executor browser, chiedi alla persona che possiede la macchina.

Credenziali

Nessun archivio di credenziali dell’host viene mai montato in una guest. Né il portachiavi, né ~/.codex o ~/.claude, né un token CLI globale, né una variabile d’ambiente che porta una chiave API. L’unico accesso supportato per una sessione di coding gestita è un file di autenticazione privato del proprietario, il cui contenuto viene letto solo dal builder initrd controllato dal proprietario — mai da Nessie, mai dal descrittore, mai da un log o da un argomento di comando — e spostato una sola volta in una home privata dentro la guest, che viene distrutta insieme alla VM. Quella guest può raggiungere esattamente un’origine.

L’executor browser è ancora più rigido: ogni sessione ottiene un profilo browser privato nuovo e rifiuta uno preparato dall’area di lavoro, quindi parte senza cookie, senza estensioni e senza alcuno stato di accesso ambientale.

Dati locali grezzi possono raggiungere un fornitore di modelli solo all’interno di un’esecuzione esplicita e limitata. Ciò che Nessie conserva sono manifest redatti, digest di argomenti e politiche, digest dei risultati e stato strutturato. Contenuti di file, output di terminale, DOM del browser, credenziali e fattori di autenticazione sono vietati nei record del database, nelle voci di audit, nei log, negli eventi in tempo reale e nei report di errore.

Che cosa concede un operatore, e come lo revoca

Il permesso di usare un executor non è un interruttore unico. Un agente può invocare un’operazione solo se possiede una concessione per quell’esatto executor e per quella esatta operazione, e la normale politica logica dello strumento lo consente, e l’ambito dell’esecuzione corrisponde, e la politica locale della macchina lo permette. Concedere un’operazione a un executor, quindi, non autorizza nulla su un altro, e un aggiornamento delle capacità non può allargare nulla, perché le nuove operazioni arrivano negate.

L’accesso degli agenti e la condivisione hanno effetto subito nella pagina stessa, senza una continuazione di approvazione, una richiesta di password o un passaggio di riautenticazione. Nella scheda Agenti dell’executor un responsabile attiva o disattiva direttamente l’accesso alla macchina per un agente; nella scheda Condivisione concede a una persona Può usare o Admin, oppure estende l’uso a un progetto o a tutti nel team corrente, nello stesso modo. Solo nella tua conversazione con l’assistente personale — mai in un canale condiviso, in un job programmato o nell’esecuzione di un altro agente — l’assistente può invece preparare una modifica di accesso di un agente o un’assegnazione, che pubblica una scheda di conferma in quella conversazione. Non cambia nulla finché non premi Consenti accesso su di essa, e il testo della chat non è mai una conferma.

Tre modifiche richiedono ancora che tu reinserisca la password attuale al momento della conferma: attivare una revisione del descrittore; un’assegnazione preparata dall’assistente che dà la macchina a una persona, non a un agente; e una politica permanente che permette ai colleghi di avviare comandi su di essa a nome del proprietario, la politica di lavoro sui ticket senza sorveglianza. Disconnettere o eliminare una macchina non richiede di proposito né l’una né l’altra cosa, perché un interruttore di emergenza non deve mai essere più difficile da raggiungere di ciò che ferma. L’applicazione di una bozza verificata richiede sempre la password. Il registro di audit registra separatamente la persona che agisce e il coinvolgimento dell’assistente.

Un executor passa attraverso un piccolo insieme esplicito di stati:

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

Il menu Computer nell’intestazione è dove un responsabile prepara ogni cambio di ciclo di vita: metterlo in pausa, riprenderlo una volta in pausa, disconnetterlo o eliminarlo. La pausa lascia l’executor online ma gli impedisce di accettare comandi. La disconnessione invalida i suoi certificati client e ogni candidato in sospeso, e non può essere annullata: un executor disconnesso va associato di nuovo come nuovo executor. Elimina fa lo stesso e in più rimuove l’executor dall’elenco. A differenza della disconnessione, è offerta qualunque sia lo stato dell’executor, anche se l’associazione è in attesa o se è già disconnesso, perché è l’unico modo per uscire dall’elenco. Lo svuotamento, cioè completare il lavoro che ha già prima di smettere di accettarne altro, è un terzo stato reale nel protocollo, e l’interfaccia può mostrare una macchina in quello stato. Nulla qui lo avvia, però: solo una chiamata diretta all’API. Ogni modifica di accesso, revisione del descrittore e transizione del ciclo di vita confermata, compreso lo svuotamento, fa avanzare anche l’epoca di connessione del daemon. Così il suo prossimo controllo di stato, al massimo un secondo dopo, fallisce in modo sicuro e ferma ogni guest attiva prima che possa riconnettersi. La revoca non è una richiesta che la macchina possa ignorare.

Gestire un executor

Verificare che funzioni

La risposta di Nessie è la vitalità. Un daemon firma un heartbeat, e un executor la cui ultima attività autenticata è più vecchia di sessanta secondi viene segnato offline in modo durevole prima di poter essere elencato, selezionato o ricevere invii. Un executor che appare online ha dimostrato di esserlo nell’ultimo minuto.

Sulla macchina non c’è alcun endpoint di controllo dello stato: il daemon non ascolta su alcuna porta rivolta all’operatore, per scelta progettuale. Su macOS e Linux, chiedi direttamente alla CLI:

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

Su macOS lo stato riporta il launchd agent di ogni team. Il comando systemctl vale solo per Linux. Su Windows l’icona nell’area di notifica è la risposta a colpo d’occhio, il suo menu indica il motivo e il log del servizio riporta i dettagli. In entrambi i casi la scheda Panoramica dell’executor in Nessie mostra i suoi profili approvati, il suo confine dei dati, quando è stato visto l’ultima volta e qualunque proposta di politica locale in attesa di revisione.

Log

Lì finisce ogni rifiuto su cui una persona può agire: un runtime non firmato o alterato, una directory di stato che non si riesce a proteggere, un executor che non si è avviato all’accensione. Lì non finisce mai una sfida di associazione, una chiave o l’output di un processo figlio. Non esiste un livello di log da alzare, perché non c’è nulla di più dettagliato da attivare.

La CLI per Mac scrive il log del servizio di ogni team in ~/Library/Logs/NessieExecutor/<executorId>.log.

Aggiornare

Aggiorna la CLI tramite Homebrew, APT o DNF, poi riavvia il servizio di ogni team con disable seguito da enable. WinGet aggiorna l’executor Windows. Gli installer diretti di Nessie Desktop offrono aggiornamenti firmati all’interno dell’app; le installazioni MSI e Debian usano il loro gestore di pacchetti. Associazioni e permessi locali sopravvivono agli aggiornamenti.

Arrestare e rimuovere

L’arresto è un percorso ordinato gestito dal daemon, non un kill. Il daemon riceve un segnale di terminazione, ferma ogni sessione guest, rilascia il proprio lease ed esce. Su Linux l’unità attende quindici secondi per un budget di smontaggio di dieci secondi e non ricorre mai a un kill non intercettabile, perché un daemon ucciso a metà smontaggio lascia una micro-VM e un overlay dell’area di lavoro senza più alcun processo che li ripulisca. Un arresto che si blocca è quindi visibile in systemctl --user status invece di restare silenzioso, e ricorrere al kill è una decisione umana esplicita.

Per rimuovere il pacchetto 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

Su Windows, msiexec /x ferma e rimuove il servizio, le sue voci di registro e la voce di avvio dell’icona nell’area di notifica. Su entrambe le piattaforme lo stato associato viene lasciato di proposito dov’è: ~/.local/state/nessie-executor/ su Linux e %ProgramData%\Nessie Executor su Windows. Un’associazione è una chiave della macchina e una revisione di politica firmata, e disinstallare un programma non è una richiesta di distruggerle; reinstallando, le ritrova dove erano. Elimina la directory a mano per dimenticare un’associazione, e revoca l’executor in Nessie per chiuderla anche dall’altro lato.

L’icona nell’area di notifica di Windows e il companion desktop offrono entrambi Dimentica l’associazione su questo computer come azione di primo livello: ferma il daemon locale, rimuove la chiave della macchina e la selezione della cartella, ed elimina in modo permanente le copie locali delle bozze dopo una conferma nativa. Lascia però l’executor lato server e la sua cronologia di audit a un proprietario che decida se conservarli o revocarli.

Errori comuni