Ejecutores remotos

Dale a un agente un ordenador real en el que trabajar: en Linux, macOS o Windows.

Qué es un ejecutor remoto

Un agente de Nessie no tiene ordenador. Puede leer lo que hay en Nessie, hablar con personas y llamar a herramientas conectadas a través de la red, pero no puede abrir un archivo de un portátil, ejecutar un comando ni ver una página que solo existe detrás de la sesión iniciada de alguien. Un ejecutor remoto es la forma de darle una máquina con la que trabajar.

Un ejecutor es un pequeño daemon que instalas en un ordenador que controlas. Se empareja hacia fuera con tu instancia de Nessie, demuestra qué máquina es con una clave que nunca sale del equipo y, a partir de ahí, ofrece un conjunto fijo y con nombre de operaciones, y nada más. El trabajo llega como comandos firmados individuales; los resultados vuelven como justificantes estructurados y acotados. La máquina nunca acepta una conexión entrante desde Nessie.

Conviene ser preciso sobre lo que un ejecutor no es, porque la mayoría de las herramientas de acceso remoto son una de estas cosas, y un ejecutor deliberadamente no lo es. No hay SSH, ni shell remota de entorno, ni conexión a un multiplexor de terminal que ya tengas abierto, ni entrada estándar desde la nube ni proxy general de la red local. No es un servidor MCP, ni un contenedor ni un entorno de ejecución en la nube: Nessie ya tiene eso, y es otra cosa. Un ejecutor es un punto de conexión con capacidades y una lista cerrada de operaciones, y esa lista es toda la superficie.

A quién pertenece un ejecutor

Cada ejecutor se crea con exactamente un ámbito, que no se puede cambiar después. El ámbito decide quién puede invocar el ejecutor y quién puede administrarlo.

Un ejecutor privado debe tener siempre al menos un administrador humano activo. Eliminar directamente al último falla; si una transacción de baja dejaría a ninguno, el ejecutor deja de aceptar trabajo nuevo, termina el que tiene y se revoca a sí mismo. Un propietario de la organización dispone de una vía de emergencia, solo para revocar, que pone fin a un ejecutor que no gestiona de otro modo, sin mostrarle su lista privada de personas, sus sesiones ni su contenido: el acceso privado nunca se transfiere en silencio a otra persona.

Qué puede hacer un agente con uno

El vocabulario de operaciones está fijado en el código, no se configura por despliegue. Se divide en dos, y esa división decide qué tienes que instalar: algunas operaciones el daemon las sirve desde su propio directorio de trabajo temporal, sin ninguna máquina virtual, y el resto necesitan una máquina virtual invitada por sesión en el host.

Las operaciones que no necesitan máquina invitada forman el paquete del espacio de trabajo. Un host que no puede arrancar una máquina invitada no es un ejecutor roto: se empareja con normalidad, informa de que su backend de sandbox es none y anuncia el paquete del espacio de trabajo y nada más. Así acaban una edición de Windows sin Hyper-V o una máquina Linux cuyo usuario no puede usar /dev/kvm, y la interfaz lo indica en lugar de fallar de forma confusa.

Un agente nunca inicia trabajo de navegador por iniciativa propia. La ruta normal de vinculación de una sola operación rechaza browser.open y browser.observe sin más; una ejecución de navegador la lanza una persona desde un canal, como un paquete de cuatro operaciones en una ejecución nueva, y después no se puede añadir ninguna vinculación más. Las sesiones de programación gestionadas funcionan igual.

Existen otros dos grupos en el código que están deliberadamente no disponibles. Las operaciones para manejar una pestaña de Chrome en la que ya tienes la sesión iniciada tienen una implementación local completa y una extensión de mensajería nativa, pero el plano de control se niega a anunciarlas hasta que el servidor pueda demostrar que la conversación de origen era privada y registrar quién divulgó qué. La base está inactiva a propósito, y la extensión no se incluye en ninguno de los instaladores. Y varias operaciones de programación —adjuntar, enviar instrucciones, interrumpir y cerrar— están nombradas en el esquema pero no tienen implementación, así que no se pueden conceder.

Cómo funciona

La conexión siempre es saliente

El daemon hace conexiones HTTPS y WSS salientes a tu API de Nessie, y a nada más. Nessie nunca llama a un portátil, nunca guarda una dirección para uno y nunca trata ningún endpoint del catálogo como transporte hacia una máquina. Por eso un ejecutor funciona desde una red doméstica, detrás de NAT, en una VPN corporativa, sin redirección de puertos ni regla de cortafuegos de entrada, y por eso detener el daemon es una desconexión completa e inmediata.

El origen de la API debe ser HTTPS. La única excepción es una dirección de bucle local (loopback), para quien ejecuta Nessie en su propia máquina, configurada con su propia variable de entorno; ningún indicador normal convierte un origen de producción en HTTP en texto plano.

El emparejamiento demuestra la máquina, y una persona lo confirma

El emparejamiento es una prueba en dos sentidos. Una persona con derecho crea el ejecutor en Nessie con su ámbito, y Nessie emite una solicitud de enrolamiento: un desafío aleatorio de 256 bits del que solo guarda un verificador SHA-256, válido durante diez minutos y utilizable una sola vez.

En la máquina, el daemon genera un par de claves Ed25519, lo guarda en un almacenamiento solo accesible por su propietario y protegido por el sistema operativo, y escribe en disco la solicitud firmada exacta antes de hacer ninguna llamada de red, para que una respuesta perdida pueda reintentarse con la misma clave preparada y no se empareje dos veces en silencio. Después envía el id de la solicitud, el desafío, su clave pública y una firma de prueba. Nessie guarda la clave pública y su huella. Nunca guarda la clave privada.

Nessie muestra entonces esa huella a una persona, que la confirma. Hasta esa confirmación y una posterior prueba de posesión, el ejecutor permanece desconectado. El emparejamiento nunca se puede completar desde el texto de un chat ni desde la transcripción de una terminal: exige una acción humana deliberada en la interfaz web o de escritorio.

Una máquina que pierde su clave no puede recuperar su registro de ejecutor. Se revoca y se vuelve a enrolar como un ejecutor nuevo. La rotación de claves, en cambio, es una sola transacción firmada tanto por la clave antigua como por la nueva.

El descriptor es la declaración firmada de la máquina sobre sí misma

Un daemon emparejado publica un descriptor: una declaración firmada, con revisiones que solo avanzan, de hechos estructurales únicamente. Dice qué esquemas de operación soporta, cuáles son sus límites de recursos y de red, cuál es su plataforma y un digest de su política local. No incluye rutas del host y no crea autoridad en la nube.

Una nueva revisión nunca se activa al llegar. Se guarda como pendiente de revisión, y una persona con derecho debe verla y confirmarla antes de que pueda afectar a lo que está disponible. Eso evita que una actualización de capacidades conceda poder en silencio: una operación recién anunciada empieza denegada.

Sé claro sobre lo que demuestra la firma. Un descriptor firmado por la clave de un ejecutor emparejado demuestra que esa clave hizo la declaración. No demuestra que el host no esté comprometido, y la interfaz debe decirlo.

Envío: candidato, vinculación, comando, justificante

Un agente nunca nombra un ejecutor. Antes de que una ejecución pueda usar uno, Nessie resuelve la operación lógica en un candidato de disponibilidad opaco y de vida corta. La respuesta no contiene ningún id de ejecutor; la base de datos solo guarda un digest del identificador junto con quién y para qué se resolvió. Los modelos y los clientes reciben un identificador, no una máquina seleccionable.

La disponibilidad es un único resolutor, que usan por igual la API, el worker, la interfaz y el asistente:

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 candidato crea una vinculación bajo un bloqueo de base de datos que vuelve a comprobar cada uno de esos controles y avanza un contador monótono (fence). El envío los vuelve a comprobar. La consecuencia es que un permiso retirado, una política restringida o un ejecutor revocado entre dos pasos detienen el trabajo en lugar de notarse después, y un reintento nunca puede caer en una máquina distinta de la que tenía vinculada la ejecución.

El propio comando viaja por la cola normal de trabajos de Nessie y por el ciclo de vida de las llamadas a herramientas, en lugar de por una cola propia adicional. El daemon consulta si hay trabajo a través de su canal de control autenticado; nunca se le envía nada de forma activa. Un comando pasa por cuatro justificantes y ningún otro:

leased → accepted → started → result-acknowledged

Cada trama vincula el id del comando, la procedencia de la ejecución, el contador de vinculación, la revisión de la capacidad, una caducidad, una clave de idempotencia y los digests de los argumentos y del contenido. El daemon rechaza una discrepancia, una política obsoleta, una repetición o un segundo resultado para un comando que ya ha completado. Los argumentos y los resultados finales se cifran en reposo con AES-256-GCM; la base de datos guarda texto cifrado acotado y digests canónicos, no el contenido.

Si se pierde un acuse de recibo, Nessie no asume que todo salió bien. El comando se registra como resultado desconocido y la ejecución sigue la ruta normal de recuperación; el daemon, que registra localmente cada comando entregado antes de empezar a trabajar, no repetirá el efecto secundario. Un justificante tardío aún puede resolver la ambigüedad con honestidad.

Límite de confianza

Instalar y emparejar un ejecutor

Instala la CLI de Mac con Homebrew, las aplicaciones de Mac con casks de Homebrew, la CLI de Linux mediante APT o DNF, o el ejecutor de Windows mediante WinGet. Cada equipo emparejado tiene sus propios permisos, guardados en el ordenador. Nessie controla el acceso dentro del equipo; no puede cambiar los recursos locales.

La guía de instalación y emparejamiento tiene los comandos exactos, el flujo del código de ocho dígitos en ambos sentidos, los ajustes locales, el arranque, las actualizaciones y la desinstalación.

Hasta dónde ha quedado probada cada plataforma

El estado de los tres sandboxes invitados es distinto, y la diferencia importa. macOS es el backend con una ruta de invitado funcional y probada. El backend Firecracker en Linux y el backend Hyper-V en Windows están implementados y cubiertos por pruebas en el host —la secuencia de arranque, las imágenes de disco, los transportes de control y de salida, el protocolo de borradores—, pero ningún invitado ha arrancado todavía en hardware real en la integración continua de este proyecto, porque eso necesita una máquina con KVM o Hyper-V, y los trabajos que lo probarían nunca han dispuesto de una. El paquete del espacio de trabajo, que no necesita invitado, se ha probado de extremo a extremo en Windows con un bucle de control real. Trata las operaciones con invitado en Linux y Windows como no probadas hasta que las pruebes en tu propio hardware. La pantalla de emparejamiento de Nessie dice lo mismo con sus propias palabras.

Seguridad y contención

Una sola raíz del espacio de trabajo, y su ruta se queda en la máquina

Al emparejar se selecciona exactamente una raíz canónica del espacio de trabajo: un directorio, no un conjunto de carpetas, y nunca su ancestro común más cercano. A Nessie se le comunica el nombre base de la raíz, para que la persona pueda reconocer el límite en la interfaz; la ruta completa se queda en el estado de la máquina, accesible solo para su propietario, y nunca se sube. Cambiar la raíz es posible, pero solo después de eliminar todos los borradores y sandboxes locales, y genera una nueva revisión del descriptor que pasa por la misma revisión humana que cualquier otro cambio de política. Nunca puede ampliarse en silencio a un directorio padre.

Las operaciones de archivo aceptan solo rutas relativas. Rechazan los recorridos de ruta (traversal) y cualquier componente de enlace simbólico, vuelven a comprobar que la raíz configurada sigue siendo un directorio normal y devuelven resultados estructurados y acotados que no contienen ninguna ruta del host.

Las escrituras van a una copia, y solo una persona las promueve

Un agente nunca escribe en tus archivos. file.write crea un árbol acotado de copia en escritura diferida bajo el directorio de estado del propio daemon, asociado a la ejecución, y las lecturas y listados posteriores de esa ejecución ven el borrador. El trabajo en la máquina invitada, incluidas las sesiones de programación, usa el mismo espacio temporal de copia en escritura diferida.

Aplicar un borrador al espacio de trabajo real es una sola operación —workspace.promote— y es la única escritura en el host de todo el sistema. No tiene ningún esquema accesible para los modelos: ningún agente, ningún asistente y ninguna ruta aportada por quien llama puede convertir un borrador en una escritura en el host. En su lugar, una persona abre Tus borradores revisados, pulsa Revisar promoción y confirma con su contraseña actual. El servidor entonces vuelve a comprobar el digest de revisión confirmado, el digest del manifiesto, la ejecución de origen, el usuario y el agente, la revisión de autorización, el permiso de la operación y la política local activa antes de crear el comando. En la máquina, el daemon reconstruye él mismo el manifiesto y rechaza un digest que haya cambiado, de modo que una edición hecha después de la revisión no pueda colarse con la aprobación de esta.

La aplicación en sí se basa en descriptores y queda registrada en un diario. El helper nativo recibe la raíz del espacio de trabajo y el borrador como descriptores de directorio ya abiertos, nunca como rutas; valida cada componente con operaciones que no siguen enlaces, rechaza enlaces simbólicos, enlaces duros, archivos especiales y cruces de montaje, y mantiene un diario de todo o nada con recuperación: si se produce un fallo a mitad, se completa el manifiesto validado o se restaura el original antes de que se ejecute nada más.

La máquina invitada no tiene red, y la salida se fuerza

Cuando una operación necesita una máquina invitada, se trata de una micro-VM Linux por sesión, sin directorio personal del host, sin socket de Docker, sin agente SSH, sin entorno heredado y sin más montaje del host que el recurso compartido del espacio de trabajo. El montaje del entorno ejecutable es de solo lectura; el montaje escribible del espacio de trabajo prohíbe la ejecución, así que lo que se ejecuta procede del payload de runtime verificado y no de algo que un agente haya escrito. La máquina invitada baja a una identidad sin privilegios antes de abrir cualquier socket, y un recurso compartido propiedad de root hace fallar el arranque en lugar de dejar una carga de trabajo privilegiada en marcha.

Lo más importante es que la máquina invitada no tiene interfaz de red. En Linux, la secuencia de lanzamiento deliberadamente nunca la configura y no se crea ningún dispositivo TAP; en Windows, el adaptador de red virtual que Hyper-V añade por defecto se elimina durante la instalación. La única salida de la máquina invitada hacia fuera es un proxy de bucle local dentro de ella, tunelizado sobre un socket virtual hasta un puente en el host, que entrega los bytes a la propia pasarela del daemon: un listener de socket local de solo propietario, sin listener TCP y sin modo de reenvío general. Esa pasarela es donde se aplican las políticas de HTTP, CONNECT, WebSocket, redirecciones, origen, descargas y subidas, usando la maquinaria de peticiones con IP fijada que ya tiene Nessie, en lugar de una segunda implementación de las mismas reglas. No hay puente NAT ni resolutor DNS directo: el DNS alternativo, el TCP en bruto, QUIC y el rodeo del proxy están todos denegados.

La lista de orígenes que aplica esa pasarela la configura en la máquina su propietario, y deliberadamente nunca se sube. La interfaz señala esa ausencia en lugar de fingir que Nessie es un editor de políticas de origen: para saber a qué puede acceder un ejecutor de navegador, pregunta a la persona que es dueña de la máquina.

Credenciales

Ningún almacén de credenciales del host se monta nunca en una máquina invitada. Ni el llavero (Keychain), ni ~/.codex o ~/.claude, ni un token global de la CLI, ni una variable de entorno con una clave de API. El único inicio de sesión admitido para una sesión de programación gestionada es un archivo de autenticación privado del propietario, cuyo contenido solo lee el constructor de initrd controlado por el propietario —nunca Nessie, nunca el descriptor, nunca un registro ni un argumento de comando—, y que se traslada una vez a un directorio personal privado dentro de la invitada, que se destruye junto con la VM. Esa máquina invitada solo puede llegar a un origen.

El ejecutor de navegador es todavía más estricto: cada sesión recibe un perfil de navegador privado nuevo y rechaza uno preparado por el espacio de trabajo, así que empieza sin cookies, sin extensiones y sin ningún estado de sesión iniciada ambiental.

Los datos locales en bruto solo pueden llegar a un proveedor de modelos dentro de una ejecución explícita y acotada. Lo que Nessie guarda de forma persistente son manifiestos redactados, digests de argumentos y de política, digests de resultados y estado estructurado. El contenido de archivos, la salida de terminal, el DOM del navegador, las credenciales y los factores de autenticación están prohibidos en los registros de la base de datos, las entradas de auditoría, los registros, los eventos en tiempo real y los informes de error.

Qué concede un operador y cómo lo retira

Permitir usar un ejecutor no es un interruptor único. Un agente puede invocar una operación solo cuando tiene un permiso para ese ejecutor exacto y esa operación exacta, y la política lógica ordinaria de la herramienta lo permite, y el ámbito de la ejecución coincide, y la política local de la máquina lo permite. Conceder a un ejecutor una operación, por tanto, no autoriza nada en otro, y una actualización de capacidades no puede ampliar nada, porque las operaciones nuevas llegan denegadas.

El acceso de los agentes y el compartir surten efecto de inmediato en la propia página, sin continuación de aprobación, sin petición de contraseña ni paso de nueva autenticación. En la pestaña Agentes del ejecutor, un gestor activa o desactiva directamente el acceso de un agente a la máquina; en Compartir concede a una persona Puede usar o Admin, o extiende el uso a un proyecto o a todos los miembros del equipo actual, de la misma forma. En tu propia conversación con el asistente —solo allí, nunca en un canal compartido, en un trabajo programado o en la ejecución de otro agente—, el asistente puede preparar en su lugar un cambio de acceso de agente o de asignación, lo que publica una tarjeta de confirmación en esa conversación. Nada cambia hasta que pulsas Permitir acceso en ella, y el texto del chat nunca es una confirmación.

Tres cambios siguen exigiendo que vuelvas a introducir tu contraseña actual en el momento de confirmar: activar una revisión de descriptor; una asignación preparada por el asistente que da a una persona, y no a un agente, la máquina; y una política permanente que permite a los compañeros iniciar comandos en ella como su propietario, la política de trabajo desatendido en tickets. Desconectar o eliminar una máquina deliberadamente no pide ninguna de las dos cosas, porque un interruptor de emergencia nunca debe ser más difícil de alcanzar que aquello que detiene. La promoción de un borrador revisado siempre lo pide. El registro de auditoría recoge por separado a la persona que actúa y la intervención del asistente.

Un ejecutor pasa por un conjunto pequeño y explícito de estados:

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

El menú Ordenador del encabezado es donde un gestor prepara cada cambio de ciclo de vida: pausarlo, reanudarlo una vez pausado, desconectarlo o eliminarlo. Pausar deja el ejecutor en línea, pero deja de aceptar comandos. Desconectar invalida sus certificados de cliente y todos los identificadores de candidato pendientes, y no se puede deshacer: un ejecutor desconectado se vuelve a emparejar como uno nuevo. Eliminar hace lo mismo y además quita el ejecutor de la lista; a diferencia de desconectar, se ofrece sea cual sea el estado del ejecutor, incluidos el emparejamiento pendiente y el ya desconectado, porque es la única forma de salir de la lista. El drenaje —terminar el trabajo que ya tiene antes de dejar de aceptar más— es un tercer estado real en el protocolo, y la interfaz puede mostrar un ordenador en ese estado, pero aquí nada lo inicia: solo lo hace una llamada directa a la API. Cada cambio de acceso confirmado, cada revisión de descriptor y cada transición de ciclo de vida, también un drenaje, avanza además la época de conexión del daemon, así que su siguiente consulta de control —como máximo un segundo después— falla en cerrado y detiene todas las máquinas invitadas en marcha antes de que puedan reconectarse. La revocación no es una petición que la máquina pueda ignorar.

Operar un ejecutor

Comprobar que funciona bien

La respuesta de Nessie es la comprobación de actividad. Un daemon firma un latido, y un ejecutor cuya última actividad autenticada tiene más de sesenta segundos se marca en la base de datos como desconectado antes de que pueda listarse, seleccionarse o recibir envíos. Un ejecutor que aparece en línea ha demostrado su actividad en el último minuto.

No hay endpoint de salud en la máquina: el daemon no escucha en ningún puerto orientado al operador, por diseño. En macOS y Linux, consulta la CLI directamente:

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

En macOS, el estado informa del agente launchd de cada equipo. El comando systemctl es solo para Linux. En Windows, el icono de la bandeja del sistema es la respuesta de un vistazo, su menú indica el motivo y el registro del servicio contiene el detalle. En cualquier plataforma, la pestaña Resumen del ejecutor en Nessie muestra sus perfiles aprobados, su límite de datos, cuándo se vio por última vez y cualquier propuesta de política local pendiente de revisión.

Registros

Ahí aparece cada rechazo que una persona puede resolver: un runtime sin firmar o alterado, un directorio de estado que no se puede asegurar, un ejecutor que no arrancó al iniciar el sistema. Lo que nunca aparece ahí es un desafío de emparejamiento, una clave ni la salida de un proceso hijo. No hay ningún nivel de registro que subir, porque no hay nada más detallado que activar.

La CLI de Mac escribe el registro de servicio de cada equipo en ~/Library/Logs/NessieExecutor/<executorId>.log.

Actualizar

Actualiza la CLI con Homebrew, APT o DNF, y después reinicia el servicio de cada equipo con disable seguido de enable. WinGet actualiza el ejecutor de Windows. Los instaladores directos de Nessie Desktop ofrecen actualizaciones firmadas dentro de la aplicación; las instalaciones MSI y Debian usan su gestor de paquetes. Los emparejamientos y los permisos locales sobreviven a las actualizaciones.

Detener y eliminar

Detener es una vía ordenada que gestiona el propio daemon, no una terminación forzada. Recibe una señal de terminación, detiene todas las sesiones invitadas, libera su concesión (lease) y sale. En Linux, la unidad espera quince segundos para un presupuesto de desmontaje de diez segundos y nunca escala a una terminación forzada que no se pueda capturar, porque un daemon matado a mitad del desmontaje dejaría huérfana una micro-VM y una capa superpuesta del espacio de trabajo sin ningún proceso que las limpie. Una parada que se cuelga es, por tanto, visible en systemctl --user status en lugar de silenciosa, y escalar es una decisión humana explícita.

Para eliminar el paquete 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

En Windows, msiexec /x detiene y elimina el servicio, sus entradas del registro y la entrada de inicio de la bandeja. En ambas plataformas, el estado emparejado se deja deliberadamente en su sitio —~/.local/state/nessie-executor/ en Linux y %ProgramData%\Nessie Executor en Windows. Un emparejamiento es una clave de máquina y una revisión de política firmada, y desinstalar un programa no es una petición para destruirlas; al reinstalar, se encuentran donde estaban. Borra el directorio a mano para olvidar un emparejamiento, y revoca el ejecutor en Nessie para terminarlo desde el otro lado.

La bandeja del sistema de Windows y la aplicación de escritorio complementaria ofrecen ambas Olvidar el emparejamiento en este ordenador como acción de primera clase: detiene el daemon local, elimina la clave de la máquina y la selección de carpeta, y borra de forma permanente las copias locales de los borradores tras una confirmación nativa, dejando en el servidor el ejecutor y su historial de auditoría para que un propietario los conserve o los revoque.

Fallos habituales