Executors remots

Dona a un agent un ordinador de veritat on treballar, amb Linux, macOS o Windows.

Què és un executor remot

Un agent a Nessie no té ordinador. Pot llegir el que hi ha a Nessie, parlar amb la gent i cridar eines connectades per la xarxa, però no pot obrir un fitxer d’un portàtil, executar una ordre ni mirar una pàgina que només existeix darrere del compte d’algú. Un executor remot és la manera de donar-li una màquina on treballar.

Un executor és un petit dimoni que instal·les en un ordinador que controles. Fa un emparellament cap enfora amb la teva instància de Nessie, demostra quina màquina és amb una clau que mai no surt de l’equip i tot seguit ofereix un conjunt fix i amb nom d’operacions, i res més. El treball arriba com a ordres signades individuals; els resultats tornen com a justificants estructurats i acotats. La màquina mai no accepta una connexió entrant des de Nessie.

Val la pena ser precís sobre què no és un executor, perquè la majoria d’eines d’accés remot són una d’aquestes coses i un executor és deliberadament cap d’elles. No hi ha SSH, no hi ha un intèrpret d’ordres remot ambient, no es pot adjuntar a un multiplexor de terminal que ja tinguis obert, no hi ha entrada estàndard des del núvol ni proxy general per a la xarxa local. Tampoc no és un servidor MCP, ni un contenidor ni un entorn d’execució al núvol: Nessie ja en té, i són una altra cosa. Un executor és un endpoint amb capacitats i una llista tancada d’operacions, i aquesta llista és tota la superfície.

A qui pertany un executor

Cada executor es crea amb exactament un àmbit, i aquest àmbit no es pot canviar després. Decideix qui pot invocar l’executor i qui n’administra l’accés.

Un executor privat ha de tenir sempre almenys un administrador humà actiu. Treure’n l’últim directament falla; si una transacció de baixa en deixaria cap, l’executor deixa d’acceptar feina nova, acaba la feina pendent i es revoca a si mateix. Un propietari de l’organització disposa d’una via de revocació d’emergència que posa fi a un executor que no gestiona de manera ordinària, sense mostrar-li’n la llista privada, les sessions ni el contingut. L’accés privat mai no es transfereix en silenci a una altra persona.

Què pot fer realment un agent amb un executor

El vocabulari d’operacions està fixat al codi, no es configura per desplegament. Es divideix en dues parts, i aquesta divisió decideix què cal instal·lar: algunes operacions les serveix el dimoni des del seu propi directori temporal, sense cap màquina virtual, i les altres necessiten una VM convidada per sessió a l’amfitrió.

Les operacions que no necessiten convidada formen el paquet d’espai de treball. Un amfitrió que no pot iniciar una convidada no és un executor trencat: s’empareja amb normalitat, informa que el seu backend de sandbox és none i anuncia només el paquet d’espai de treball, i res més. Aquest és l’estat en què acaba una edició de Windows sense Hyper-V, o una màquina Linux on l’usuari no pot usar /dev/kvm, i la interfície ho indica en lloc de fallar de manera confusa.

Un agent mai no inicia el treball amb navegador per iniciativa pròpia. La ruta de vinculació d’una sola operació ordinària refusa browser.open i browser.observe de manera directa; una execució amb navegador la llança una persona des d’un canal, com un sol paquet de quatre operacions en una execució nova, i després no es pot afegir cap vinculació més. Les sessions de codificació gestionades funcionen de la mateixa manera.

Hi ha dos grups més al codi que deliberadament no estan disponibles. Les operacions per controlar una pestanya de Chrome on ja tens la sessió iniciada tenen una implementació local completa i una extensió de missatgeria nativa, però el pla de control es nega a anunciar-les fins que el servidor pugui demostrar que la conversa d’origen era privada i registrar qui ha revelat què. La base és inerta a propòsit, i l’extensió no s’inclou en cap dels instal·ladors. I diverses operacions de codificació (adjuntar, enviar un prompt, interrompre i tancar) estan anomenades a l’esquema però no tenen implementació, de manera que no es poden concedir.

Com funciona

La connexió és sempre cap enfora

El dimoni fa connexions HTTPS i WSS de sortida a la teva API de Nessie i a res més. Nessie mai no truca a un ordinador portàtil, no en guarda cap adreça i mai no tracta cap endpoint del catàleg com a transport de màquina. Per això un executor funciona des d’una xarxa domèstica, darrere de NAT, en una VPN corporativa, sense redireccionament de ports ni regla de tallafocs entrant. I per això aturar el dimoni és una desconnexió completa i immediata.

L’origen de l’API ha de ser HTTPS. L’única excepció és una adreça de loopback per a qui executa Nessie a la seva pròpia màquina, amb la seva pròpia variable d’entorn; cap marca habitual no converteix un origen de producció en HTTP sense xifrar.

L’emparellament demostra una màquina, i una persona la confirma

L’emparellament és una prova de dues bandes. Una persona amb dret crea l’executor a Nessie amb el seu àmbit, i Nessie emet una inscripció: un repte aleatori de 256 bits del qual només guarda un verificador SHA-256, vàlid durant deu minuts i utilitzable una sola vegada.

A la màquina, el dimoni genera un parell de claus Ed25519, les guarda en un emmagatzematge protegit pel sistema operatiu i només accessible pel propietari, i escriu al disc la petició signada exacta abans de fer cap crida de xarxa. Així, una resposta perduda es pot reintentar amb la mateixa clau preparada, en lloc d’emparellar-se dues vegades en silenci. Després envia l’identificador de la inscripció, el repte, la clau pública i una signatura de prova. Nessie guarda la clau pública i la seva empremta. Mai no guarda la clau privada.

Nessie mostra després aquesta empremta a una persona, que la confirma. Fins a aquesta confirmació i a una prova posterior de possessió, l’executor es queda fora de línia. L’emparellament mai no es pot completar des d’un text de xat ni d’una transcripció de terminal: requereix una acció humana deliberada a la interfície web o d’escriptori.

Una màquina que perd la clau no pot recuperar el seu registre d’executor. Es revoca i es torna a inscriure com a executor nou. La rotació de claus, en canvi, és una sola transacció signada per la clau antiga i la nova.

El descriptor és la declaració signada de la màquina sobre si mateixa

Un dimoni emparellat publica un descriptor: una declaració signada i amb revisió monòtona només de fets estructurals, com quines operacions admet, els seus límits de recursos i de xarxa, la plataforma i un resum de la seva política local. No porta rutes de l’amfitrió i no crea cap autoritat al núvol.

Una revisió nova mai no s’activa en arribar. S’emmagatzema pendent de revisió, i una persona amb dret l’ha de veure i confirmar abans que pugui afectar què està disponible. Això evita que una actualització de capacitats concedeixi potència nova en silenci: una operació anunciada de nou comença denegada.

Sigues clar sobre el que prova la signatura. Un descriptor signat per una clau d’executor emparellada prova que aquella clau va fer la declaració. No prova que l’amfitrió no estigui compromès, i la interfície ho ha de dir.

Enviament: candidat, vinculació, ordre, justificant

Un agent mai no nomena un executor. Abans que una execució en pugui usar un, Nessie resol l’operació lògica en un candidat de disponibilitat opac i de vida curta. La resposta no conté cap identificador d’executor; la base de dades només guarda un resum del manejador, juntament amb qui i per a què es va resoldre. Els models i els clients reben un manejador, no una màquina seleccionable.

La disponibilitat és un únic resolutor, usat de manera idèntica per l’API, el worker, la interfície i l’assistent:

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 el candidat crea una vinculació sota un bloqueig de base de dades que torna a comprovar cadascuna d’aquestes barreres una segona vegada i avança una barrera monòtona. L’enviament les torna a comprovar. La conseqüència és que una concessió retirada, una política restringida o un executor revocat entre dos passos aturen el treball en lloc de notar-se després. Un reintent mai no pot anar a parar a una altra màquina que la que l’execució tenia vinculada.

L’ordre en si viatja per la cua habitual de treballs de Nessie i pel cicle de vida de les crides d’eina, en lloc d’una segona cua pròpia. El dimoni consulta si hi ha feina pel seu canal de control autenticat; mai no se li envia res de manera activa. Una ordre passa per quatre justificants i per cap altre:

leased → accepted → started → result-acknowledged

Cada trama vincula l’identificador de l’ordre, la procedència de l’execució, la barrera de vinculació, la revisió de la capacitat, una caducitat, una clau d’idempotència i els resums dels arguments i del contingut. El dimoni refusa una discrepància, una política obsoleta, una repetició o un segon resultat per a una ordre que ja ha completat. Els arguments i els resultats finals es xifren amb AES-256-GCM en repòs; la base de dades guarda xifrats acotats i resums canònics, no contingut.

Si es perd una confirmació, Nessie no dóna l’èxit per fet. L’ordre es registra com a resultat desconegut i l’execució segueix el camí de recuperació habitual. El dimoni, que registra localment cada ordre lliurada abans de començar el treball, no repetirà l’efecte secundari. Un justificant tardà encara pot resoldre l’ambigüitat de manera honesta.

Frontera de confiança

Instal·lar i emparellar un executor

Instal·la la CLI de Mac amb Homebrew, les aplicacions de Mac amb casks d’Homebrew, la CLI de Linux amb APT o DNF, o l’executor de Windows amb WinGet. Cada equip emparellat té permisos separats que s’emmagatzemen a l’ordinador. Nessie controla l’accés dins de l’equip; no pot canviar els recursos locals.

La guia d’instal·lació i d’emparellament conté les ordres exactes, el flux de codi de vuit dígits en dues bandes, la configuració local, l’arrencada, les actualitzacions i l’eliminació.

Fins on s’ha provat realment cada plataforma

L’estat dels tres sandboxes de convidada és diferent, i la diferència importa. macOS és el backend amb un camí de convidada en funcionament i exercitat. El backend Firecracker a Linux i el backend Hyper-V a Windows estan implementats i coberts per proves de l’amfitrió (la seqüència d’arrencada, les imatges de disc, els transports de control i de sortida, el protocol d’esborranys), però cap convidada no ha arrencat encara en maquinari real dins la integració contínua d’aquest projecte, perquè això necessita una màquina amb KVM o Hyper-V i les tasques que ho demostrarien mai no n’han tingut cap. El paquet d’espai de treball, que no necessita convidada, s’exercita de cap a cap a Windows contra un bucle de control real. Tracta les operacions amb convidada a Linux i Windows com a no provades fins que les hagis provat al teu propi maquinari. La pantalla d’emparellament de Nessie diu el mateix amb les seves pròpies paraules.

Seguretat i contenció

Una sola arrel d’espai de treball, i el seu camí es queda a la màquina

L’emparellament selecciona exactament una arrel d’espai de treball canònica: un directori, no un conjunt de carpetes, i mai el seu pare comú més proper. Nessie coneix el nom base de l’arrel, perquè una persona pugui reconèixer el límit a la interfície. El camí complet es queda a l’estat de la màquina, només accessible pel propietari, i mai no es puja. Es pot canviar l’arrel, però només després d’haver eliminat tots els esborranys i sandboxes locals, i això produeix una revisió nova del descriptor que passa per la mateixa revisió humana que qualsevol altre canvi de política. Mai no pot ampliar-se en silenci fins a un directori pare.

Les operacions de fitxers accepten només rutes relatives. Rebutgen els recorreguts i tots els components d’enllaç simbòlic, tornen a comprovar que l’arrel configurada encara és un directori ordinari i retornen resultats estructurats i acotats que no contenen cap camí de l’amfitrió.

Les escriptures van a una còpia, i només una persona les aplica

Un agent mai no escriu als teus fitxers. file.write crea un arbre acotat en còpia en escriure sota el directori d’estat propi del dimoni, lligat a l’execució, i les lectures i els llistats posteriors d’aquella execució veuen l’esborrany. El treball a la convidada, incloses les sessions de codificació, usa la mateixa zona temporal de còpia en escriure.

Aplicar un esborrany a l’espai de treball real és una sola operació, workspace.promote, i és l’única escriptura a l’amfitrió del sistema. No té cap esquema orientat al model: cap agent, cap assistent i cap ruta proporcionada per qui truca no poden convertir un esborrany en una escriptura a l’amfitrió. En canvi, una persona obre Els teus esborranys revisats, prem Revisa la promoció i confirma amb la seva contrasenya actual. El servidor després torna a comprovar el resum de revisió reconegut, el resum del manifest, l’execució, l’usuari i l’agent d’origen, la revisió d’autorització, la concessió d’operació i la política local activa, abans de crear l’ordre. A la màquina, el dimoni reconstrueix el manifest per si mateix i refusa un resum que hagi canviat. Així, una edició feta després de la revisió no pot colar-se amb l’aprovació de la revisió.

L’aplicació en si és basada en descriptors i té diari. L’ajudant natiu rep l’arrel de l’espai de treball i l’esborrany com a descriptors de directori ja oberts, mai com a rutes; valida cada component amb operacions sense seguiment d’enllaços, refusa enllaços simbòlics, enllaços durs, fitxers especials i creuaments de muntatge, i manté un diari de tot o res amb recuperació. Així, una caiguda o bé acaba el manifest validat o bé restaura l’original abans que res més no s’executi.

La convidada no té xarxa, i la sortida es força

Quan una operació necessita una convidada, és una micro-VM Linux per sessió, sense directori personal de l’amfitrió, sense socket de Docker, sense agent SSH, sense entorn heretat i sense cap muntatge de l’amfitrió excepte la compartició de l’espai de treball. El muntatge de l’entorn d’execució és de només lectura; el muntatge escrivible de l’espai de treball prohibeix l’execució, de manera que tot el que s’executa ve de la càrrega d’execució verificada i no d’alguna cosa que un agent hagi escrit. La convidada baixa a una identitat sense privilegis abans d’obrir cap socket, i una compartició amb propietari root fa fallar l’arrencada en lloc de deixar en marxa una càrrega privilegiada.

Sobretot, la convidada no té cap interfície de xarxa. A Linux, la seqüència d’arrencada deliberadament mai no n’hi configura cap i no es crea cap dispositiu TAP; a Windows, l’adaptador de xarxa virtual que Hyper-V afegeix per defecte s’elimina durant la instal·lació. L’única ruta de la convidada cap a fora de la màquina és un proxy de loopback dins d’ella, que va per un socket virtual fins a un pont a l’amfitrió, i que lliura els bytes a la passarel·la pròpia del dimoni: un receptor de socket local només accessible pel propietari, sense receptor TCP i sense mode de reenviament general. Aquesta passarel·la és on s’aplica la política de HTTP, CONNECT, WebSocket, redireccions, origen, descàrrega i pujada, usant la maquinària de pinned-fetch que Nessie ja té, en lloc d’una segona implementació de les mateixes regles. No hi ha pont NAT ni resolutor DNS directe: el DNS alternatiu, el TCP en brut, QUIC i el salt de proxy estan tots denegats.

La llista d’orígens que aplica la passarel·la es configura a la màquina, pel seu propietari, i deliberadament mai no es puja. La interfície ho indica en lloc de fingir que Nessie és un editor de polítiques d’orígens: per saber què pot arribar a usar un executor de navegador, pregunta a la persona que és propietària de la màquina.

Credencials

Cap magatzem de credencials de l’amfitrió no es munta mai en una convidada. Ni el clauer, ni ~/.codex ni ~/.claude, ni un token de CLI global, ni una variable d’entorn que porti una clau d’API. L’única manera d’iniciar sessió que s’admet per a una sessió de codificació gestionada és un fitxer d’autenticació privat del propietari, el contingut del qual només llegeix el constructor de initrd controlat pel propietari (mai Nessie, mai el descriptor, mai un registre ni un argument d’ordre), i que es mou una vegada a un directori personal privat dins de la convidada, destruït amb la VM. Aquesta convidada només pot arribar a exactament un origen.

L’executor de navegador és encara més estricte: cada sessió obté un perfil de navegador privat nou i refusa un que hagi preparat l’espai de treball, de manera que comença sense galetes, sense extensions i sense cap estat d’inici de sessió ambient.

Les dades locals en brut només poden arribar a un proveïdor de models dins d’una execució explícita i acotada. Nessie persisteix manifestos redactats, resums d’arguments i de política, resums de resultats i estat estructurat. El contingut de fitxers, la sortida de terminal, el DOM del navegador, les credencials i els factors d’autenticació estan prohibits als registres de la base de dades, a les entrades d’auditoria, als registres de sistema, als esdeveniments en temps real i als informes d’error.

Què concedeix un operador i com ho revoca

El permís per usar un executor no és un únic interruptor. Un agent només pot invocar una operació quan té una concessió per a aquell executor exacte i aquella operació exacta, i la política lògica ordinària de l’eina la permet, i l’àmbit de l’execució coincideix, i la política local de la màquina ho permet. Concedir una operació a un executor, doncs, no autoritza res en un altre, i una actualització de capacitats no pot ampliar res, perquè les operacions noves arriben denegades.

L’accés dels agents i la compartició fan efecte tot seguit a la mateixa pàgina, sense cap continuació d’aprovació, cap sol·licitud de contrasenya ni cap pas d’autenticació nova. A la pestanya Agents de l’executor, un gestor activa o desactiva directament l’accés d’un agent a la màquina; a Compartició concedeix a una persona Pot usar o Administrador, o estén l’ús a un projecte o a tothom de l’equip actual, de la mateixa manera. A la teva pròpia conversa amb l’assistent (només allà, mai en un canal compartit, una tasca programada o l’execució d’un altre agent) l’assistent pot preparar un canvi d’accés d’agent o d’assignació, que publica una targeta de confirmació en aquella conversa. No canvia res fins que premis Permet l’accés a la targeta, i el text del xat mai no és una confirmació.

Tres canvis encara et demanen tornar a introduir la teva contrasenya actual en el moment de la confirmació: activar una revisió del descriptor; una assignació preparada per l’assistent que dona la màquina a una persona, en lloc d’un agent; i una política permanent que permet als companys iniciar ordres a la màquina com a propietari, la política de treball desatès de tiquets. Desconnectar o eliminar una màquina deliberadament no demana cap de les dues coses, perquè un interruptor d’aturada mai no ha de ser més difícil d’arribar que allò que atura. L’aplicació d’un esborrany revisat sempre les demana. El registre d’auditoria registra per separat la persona que actua i la participació de l’assistent.

Un executor passa per un conjunt petit i explícit d’estats:

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

El menú Ordinador de la capçalera és on un gestor prepara cada canvi del cicle de vida: posar-lo en pausa, reprendre’l quan està en pausa, desconnectar-lo o eliminar-lo. Posar en pausa deixa un executor en línia però l’atura perquè no accepti ordres. Desconnectar invalida els seus certificats de client i tots els manejadors de candidats pendents, i no es pot desfer: un executor desconnectat es torna a emparellar com un de nou. Eliminar fa el mateix i a més treu l’executor de la llista. A diferència de desconnectar, s’ofereix independentment de l’estat de l’executor, inclosos l’emparellament pendent i els ja desconnectats, perquè és l’única manera que en surt de la llista. El buidatge (acabar la feina que ja té abans d’aturar-se i no acceptar-ne més) és un tercer estat real del protocol, i la interfície pot mostrar una màquina en aquest estat, però res del que hi ha aquí no el posa en marxa: només ho fa una crida directa a l’API. Cada canvi d’accés confirmat, revisió de descriptor i transició del cicle de vida, inclòs un buidatge, també fa avançar l’època de connexió del dimoni. Així, el seu següent sondeig de control (com a molt un segon més tard) falla en tancar-se i atura totes les convidades vives abans que pugui reconnectar-se. La revocació no és una petició que la màquina pugui ignorar.

Operar un executor

Comprovar que funciona bé

La resposta de Nessie és la vitalitat. Un dimoni signa un senyal de vida, i un executor l’última activitat autenticada del qual és més antiga de seixanta segons queda marcat com a fora de línia de manera duradora abans que es pugui llistar, seleccionar o enviar-li res. Un executor que apareix en línia s’ha demostrat a si mateix durant l’últim minut.

A la màquina no hi ha cap endpoint de comprovació de l’estat: el dimoni no escolta cap port visible per a l’operador, per disseny. A macOS i Linux, pregunta directament a la CLI:

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

A macOS, l’estat informa de l’agent launchd de cada equip. L’ordre systemctl és només de Linux. A Windows, la icona de la safata és la resposta d’un cop d’ull, el seu menú indica el motiu i el registre del servei conté el detall. En qualsevol de les dues plataformes, la pestanya Resum de l’executor a Nessie mostra els seus perfils aprovats, el seu límit de dades, quan es va veure per darrera vegada i qualsevol proposta de política local pendent de revisió.

Registres

Allà va a parar cada refús que una persona pot resoldre: un temps d’execució sense signar o manipulat, un directori d’estat que no es podria assegurar, un executor que no ha arrencat amb l’ordinador. Allà mai no va a parar un repte d’emparellament, una clau ni la sortida d’un procés fill. No hi ha cap configuració de nivell de registre per pujar, perquè no hi ha res més detallat per activar.

La CLI de Mac escriu el registre del servei de cada equip a ~/Library/Logs/NessieExecutor/<executorId>.log.

Actualitzar

Actualitza la CLI amb Homebrew, APT o DNF, i després reinicia el servei de cada equip amb disable seguit de enable. WinGet actualitza l’executor de Windows. Els instal·ladors directes de Nessie Desktop ofereixen actualitzacions signades dins de l’aplicació; les instal·lacions MSI i Debian usen el seu gestor de paquets. Els emparellaments i els permisos locals sobreviuen a les actualitzacions.

Aturar i eliminar

Aturar és un camí ordenat que el dimoni controla, no una aturada forçada. Rep un senyal de terminació, atura totes les sessions de convidada, allibera el seu arrendament i surt. A Linux, la unitat espera quinze segons per a un pressupost de desmuntatge de deu segons i deliberadament mai no escala a una aturada no capturable, perquè un dimoni matat a mig desmuntatge deixa una micro-VM i una superposició d’espai de treball sense cap procés que les pugui netejar. Una aturada que es penja és, per tant, visible a systemctl --user status en lloc de silenciosa, i escalar-la és una decisió humana explícita.

Per eliminar el paquet de 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

A Windows, msiexec /x atura i elimina el servei, les seves entrades de registre i l’entrada d’inici de la safata. En totes dues plataformes l’estat emparellat es deixa deliberadament enrere: ~/.local/state/nessie-executor/ a Linux i %ProgramData%\Nessie Executor a Windows. Un emparellament és una clau de màquina i una revisió de política signada, i desinstal·lar un programa no és una petició per destruir-les; en reinstal·lar, es tornen a trobar on eren. Esborra el directori a mà per oblidar un emparellament, i revoca l’executor a Nessie per acabar-lo des de l’altre costat.

La safata de Windows i el companion d’escriptori ofereixen tots dos Oblida l’emparellament en aquest ordinador com a acció de primera classe: atura el dimoni local, elimina la clau de la màquina i la selecció de carpeta, i esborra definitivament les còpies locals dels esborranys després d’una única confirmació nativa. Deixa al servidor l’executor i el seu historial d’auditoria perquè un propietari els conservi o els revoqui.

Errors habituals