¿Cómo ejecutar un agente IA en un sandbox Linux ligero y rápido? Probando AgentOS

Quemé la mitad de mi presupuesto de sandbox en E2B en solo dos semanas lanzando contenedores para agentes de IA que a menudo se ejecutaban durante apenas ocho segundos.

Había estado integrando agentes de codificación con IA en algunos scripts de automatización. Estos agentes generaban un borrador, ejecutaban un comando, comprobaban la salida y repetían el proceso hasta completar la tarea.

Como no quería que un agente de IA ejecutara comandos shell aleatorios directamente en mi servidor de producción, cada tarea necesitaba su propio entorno aislado. Como mucha gente, empecé con Docker y luego cambié a un servicio de sandbox alojado cuando el tiempo de arranque de Docker se convirtió en un cuello de botella.

Todo funcionó bien al principio, pero eventualmente tanto el costo como el retraso de arranque se hicieron difíciles de ignorar. Un sandbox que tarda entre 400 y 900 milisegundos en iniciarse puede no parecer lento por sí solo. Sin embargo, cuando un agente de IA crea un nuevo sandbox para cada tarea, reintento o paso pequeño, esa demora se acumula rápidamente. Además, estaba pagando por una máquina virtual completa de 1 GiB incluso cuando solo se usaba para ejecutar un simple comando de shell de dos líneas.

Fue entonces cuando descubrí agentOS, un proyecto de código abierto del equipo de Rivet.

Antes de continuar, es importante entender qué es realmente agentOS, porque su nombre puede ser engañoso. No es una herramienta de línea de comandos que se instala con un gestor de paquetes y se usa como eza o bat. En cambio, es una biblioteca de Node.js que te permite ejecutar una máquina virtual aislada similar a Linux directamente dentro de tu aplicación backend. Incluye versiones basadas en WebAssembly de muchas utilidades GNU familiares, como coreutils, grep, sed, gawk, findutils, tar, gzip y más.

Esa diferencia es importante, así que te guiaré exactamente por el proceso de configuración.

¿Qué hace agentOS exactamente?

agentOS es un kernel de sistema operativo en proceso escrito en Rust y distribuido como paquete npm. Cuando llamas a AgentOs.create() en tu aplicación Node.js, crea un entorno virtual similar a Linux dentro de tu proceso existente. Este entorno incluye un sistema de archivos virtual, tabla de procesos, pipes, PTYs (pseudo-terminales) y una pila de red virtual.

Lo importante es que nada se inicia en tu sistema host. No crea un contenedor Docker, no arranca una máquina virtual ni descarga una imagen de contenedor. Todo se ejecuta dentro de tu proceso Node.js, razón por la cual agentOS puede iniciarse en solo unos pocos milisegundos en lugar de los cientos de milisegundos que suelen tardar los contenedores.

Dentro de este entorno virtual, agentOS ejecuta paquetes de software creados como binarios WebAssembly (WASM). Estos paquetes proporcionan comandos Linux que se comportan de manera muy similar a los que ya usas a diario.

El proyecto mantiene un registro de paquetes que incluye herramientas familiares como coreutils, grep, sed, gawk, findutils, diffutils, tar, gzip, curl, jq, ripgrep, fd, tree, file, yq, zip y unzip.

Por defecto, estas herramientas se ejecutan con restricciones de seguridad estrictas. No pueden acceder a los archivos, la red ni los procesos de tu host a menos que lo permitas explícitamente. Esto hace que el entorno sea mucho más seguro para ejecutar comandos generados por IA.

Sobre la máquina virtual, agentOS también incluye tres agentes de codificación integrados: Pi, Claude Code y OpenCode. Estos agentes se comunican utilizando el Agent Communication Protocol (ACP). Tu aplicación Node.js crea una sesión, envía un prompt al agente, y el agente realiza su trabajo completamente dentro del sandbox. Puede leer y escribir archivos, ejecutar comandos Linux usando las utilidades WASM incluidas y completar tareas de codificación sin acceder directamente a tu sistema host.

Si quieres que el agente trabaje con archivos de tu servidor, debes montar explícitamente esos directorios en el entorno virtual.

Comparativa rápida: agentOS vs Docker vs Sandbox alojado

Requisitos previos

Antes de comenzar, asegúrate de tener lo siguiente:

• Un servidor Linux con Ubuntu 22.04 o posterior, Debian 12 o posterior, o RHEL 9/Rocky Linux 9 o posterior, con acceso a terminal.
• Node.js 18 o más reciente, junto con npm.
• Conocimientos básicos de JavaScript, ya que agentOS se usa como una biblioteca de Node.js en lugar de una herramienta de línea de comandos independiente.
• Una clave API de Anthropic si planeas usar los agentes Pi o Claude Code integrados. Puedes crearla desde la Consola de Anthropic. Si solo quieres experimentar con el sandbox y ejecutar comandos Linux usando vm.exec(), no necesitas una clave API.

Paso 1: Instalar Node.js

agentOS requiere Node.js 18 o posterior. Primero, instala Node.js y npm usando el gestor de paquetes de tu distribución.

En Ubuntu/Debian:

sudo apt update
sudo apt install -y nodejs npm

En RHEL/Rocky Linux:

sudo dnf install -y nodejs npm

Después de la instalación, verifica las versiones instaladas:

node -v
npm -v

Ejemplo de salida:

v24.18.0
11.16.0

agentOS requiere Node.js 18 o más reciente para soportar sus APIs. Si tu distribución proporciona una versión anterior, instala una versión más nueva desde el repositorio NodeSource en lugar de usar el paquete predeterminado.

Paso 2: Crear un proyecto e instalar agentOS

A diferencia de Docker u otros servicios del sistema, agentOS se ejecuta completamente dentro de un proyecto Node.js. No hay un paquete para instalar en todo el sistema ni un servicio que iniciar.

Crea un nuevo directorio de proyecto e inicialízalo con npm:

mkdir ~/agentos-demo
cd ~/agentos-demo
npm init -y

Deberías ver una salida similar a:

Wrote to /home/usuario/agentos-demo/package.json:

{
  "name": "agentos-demo",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "type": "commonjs"
}

A continuación, instala la biblioteca principal de agentOS junto con el paquete de software común y el agente de codificación Pi:

npm install @rivet-dev/agentos-core \
            @agentos-software/common \
            @agentos-software/pi

La instalación puede tardar unos minutos, dependiendo de tu conexión a internet. Es posible que veas una salida similar a la siguiente:

npm WARN deprecated @mariozechner/pi-ai@0.60.0: please use @earendil-works/pi-ai instead going forward
npm WARN deprecated @mariozechner/pi-coding-agent@0.60.0: please use @earendil-works/pi-coding-agent instead going forward

added 359 packages, and audited 360 packages in 3m

69 packages are looking for funding
  run `npm fund` for details

8 vulnerabilities (2 low, 5 moderate, 1 high)

To address issues that do not require attention, run:
  npm audit fix

Some issues need review and may require choosing
a different dependency.

Run `npm audit` for details.

No te preocupes si ves advertencias de deprecación o vulnerabilidad durante la instalación. Están relacionadas con algunas de las dependencias del proyecto y son comunes en muchos proyectos Node.js. Los paquetes se instalan correctamente, así que puedes continuar con el siguiente paso. Si planeas usar agentOS en un entorno de producción, es buena idea revisar el informe de npm audit y mantener tus dependencias actualizadas.

Los tres paquetes que instalaste tienen roles diferentes:

• @rivet-dev/agentos-core proporciona el motor principal de agentOS que crea el sistema de archivos virtual, la tabla de procesos, la pila de red y gestiona las sesiones de los agentes.
• @agentos-software/common instala una colección de utilidades Linux basadas en WebAssembly, incluyendo coreutils, grep, sed, gawk, findutils, diffutils, tar y gzip.
• @agentos-software/pi instala Pi, uno de los agentes de codificación integrados disponibles en agentOS, junto con Claude Code y OpenCode.

Paso 3: Ejecutar tu primera sesión de agente

Si quieres usar el agente Pi integrado, primero necesitas proporcionar tu clave API de Anthropic. La forma más fácil es exportarla como variable de entorno en tu sesión de terminal actual, para no tener que codificarla en tu script.

export ANTHROPIC_API_KEY="tu-clave-api-aquí"

Ahora crea un archivo llamado index.mjs con el siguiente código:

cat > index.mjs << 'EOF'
import { AgentOs } from "@rivet-dev/agentos-core";
import common from "@agentos-software/common";
import pi from "@agentos-software/pi";

const vm = await AgentOs.create({
  software: [common, pi]
});

const { sessionId } = await vm.createSession("pi", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY },
});

vm.onSessionEvent(sessionId, (event) => {
  console.log(event);
});

await vm.prompt(sessionId, "Write a hello world script to /home/agentos/hello.js");

const content = await vm.readFile("/home/agentos/hello.js");
console.log(new TextDecoder().decode(content));

vm.closeSession(sessionId);
await vm.dispose();
EOF

Este script realiza las siguientes tareas:

• Crea una nueva máquina virtual agentOS.
• Carga las utilidades Linux comunes y el agente de codificación Pi.
• Inicia una nueva sesión de agente Pi.
• Pasa tu clave API de Anthropic al agente.
• Pide al agente que cree un programa simple de JavaScript “Hello World”.
• Lee el archivo generado desde el sistema de archivos virtual e imprime su contenido.
• Cierra la sesión y elimina la máquina virtual.

Ejecuta el script con:

node index.mjs

Si todo funciona correctamente, verás una salida similar a esta:

{ type: 'session_start', sessionId: 'sess_8f2a1c' }
{ type: 'agent_message', text: 'Writing hello.js now.' }
{ type: 'tool_call', name: 'write_file', path: '/home/agentos/hello.js' }
{ type: 'session_end', sessionId: 'sess_8f2a1c' }

console.log("Hello, World!");

La última línea es el contenido del archivo hello.js que el agente creó. El script lee el archivo del sistema de archivos virtual usando vm.readFile() y lo imprime en tu terminal.

Observa que el archivo existe solo dentro del entorno virtual de agentOS. No se escribe en el sistema de archivos real de tu servidor. Una vez que el script llama a vm.dispose(), la máquina virtual se destruye junto con todo lo almacenado dentro de ella. Si quieres que los archivos persistan, necesitas montar explícitamente un directorio de tu sistema host en el entorno virtual.

Paso 4: Ejecutar comandos Linux sin un agente de IA

Una de las cosas buenas de agentOS es que no necesitas usar un agente de IA. Puedes usarlo como un sandbox ligero para ejecutar comandos Linux llamando a vm.exec() directamente.

Crea un nuevo archivo llamado shell-test.mjs:

cat > shell-test.mjs << 'EOF'
import { AgentOs } from "@rivet-dev/agentos-core";
import common from "@agentos-software/common";

const vm = await AgentOs.create({ software: [common] });

const result = await vm.exec("echo 'tecmint rocks' | grep -i tecmint");

console.log(result);

await vm.dispose();
EOF

Ahora ejecuta el script:

node shell-test.mjs

Si el comando se ejecuta correctamente, verás una salida similar a esta:

{
  stdout: 'tecmint rocks\n',
  stderr: '',
  exitCode: 0
}

Esto es lo que sucede entre bastidores:

• echo 'tecmint rocks' imprime el texto dentro del entorno virtual.
• La tubería (|) envía esa salida directamente al siguiente comando, tal como lo haría en un shell Linux normal.
• grep -i tecmint busca la palabra "tecmint" sin considerar mayúsculas y devuelve la línea coincidente.

Aunque los comandos parecen comandos Linux normales, en realidad son versiones WebAssembly que se ejecutan dentro del entorno virtual de agentOS. No se ejecutan en tu sistema host ni interactúan con tu shell real.

También probé qué sucede cuando intentas ejecutar un comando que no está disponible u olvidas cargar el paquete de software requerido. En lugar de fallar, agentOS devuelve un error estructurado con un código de salida no cero. Esto hace que sea mucho más fácil detectar fallos y manejarlos en tu aplicación, especialmente cuando los comandos son generados por un agente de IA.

Paso 5: Por qué importan los tiempos de arranque rápidos

Una de las mayores ventajas de agentOS es la rapidez con la que inicia un nuevo entorno virtual.

Según los benchmarks publicados por el proyecto, una instancia típica de agentOS arranca en aproximadamente 5 milisegundos, mientras que un sandbox alojado tradicional puede tardar alrededor de 440 milisegundos en iniciarse. La diferencia se vuelve aún mayor bajo cargas de trabajo más pesadas.

El uso de memoria también es mucho menor. Una sesión de codificación típica en agentOS usa alrededor de 130 MB de memoria, mientras que muchos servicios de sandbox alojados asignan una máquina virtual de 1 GB para cada sesión porque tienen que arrancar un sistema operativo completo.

Para aplicaciones que crean muchas sesiones de agente de corta duración, estas diferencias pueden tener un impacto significativo. Tiempos de arranque más rápidos reducen la espera, y un menor uso de memoria significa que puedes ejecutar más sesiones de agente en el mismo servidor.

Dicho esto, agentOS no está diseñado para reemplazar todos los tipos de sandbox. Si tu carga de trabajo necesita lanzar un navegador web, compilar aplicaciones nativas o ejecutar software que no está disponible como paquete WebAssembly, seguirás necesitando una máquina virtual o contenedor completo. En esas situaciones, agentOS puede trabajar junto con proveedores de sandbox externos conectándose a un sandbox real solo cuando sea realmente necesario.

Mantener agentOS actualizado

Como la mayoría de los paquetes npm, agentOS se actualiza regularmente. Puedes comprobar si hay una versión más reciente disponible ejecutando:

npm outdated @rivet-dev/agentos-core

Ejemplo de salida:

Package                   Current  Wanted  Latest  Location
@rivet-dev/agentos-core     0.2.5   0.2.7   0.2.7  agentos-demo

Si hay actualizaciones disponibles, instálalas con:

npm update @rivet-dev/agentos-core \
           @agentos-software/common \
           @agentos-software/pi

También es buena idea estar atento a los releases del proyecto en GitHub. Las nuevas versiones de la biblioteca principal y los paquetes de software a menudo se lanzan de forma independiente, por lo que puedes ver nuevas utilidades Linux basadas en WebAssembly añadidas incluso cuando el paquete principal no ha cambiado.

Si usas agentOS en producción, considera fijar las versiones de los paquetes en tu package.json y probar nuevas versiones antes de desplegarlas en tus servidores.

Solución de problemas comunes

El script falla con "Cannot find package"

Asegúrate de haber instalado todos los paquetes necesarios con npm install. Si usas módulos ES (.mjs), verifica que las rutas de importación sean correctas.

Error de autenticación con Anthropic

Verifica que la variable de entorno ANTHROPIC_API_KEY esté correctamente exportada en tu sesión de terminal. Puedes comprobarla con echo $ANTHROPIC_API_KEY.

Comandos Linux no disponibles

Si intentas ejecutar un comando que no está incluido en el paquete @agentos-software/common, obtendrás un error estructurado. Asegúrate de cargar el paquete de software correcto o instala paquetes adicionales si están disponibles.

Advertencias de vulnerabilidades npm

Las advertencias de seguridad durante la instalación son comunes. Ejecuta npm audit para ver los detalles y npm audit fix si deseas aplicar correcciones automáticas. Para producción, revisa cada vulnerabilidad individualmente.

Conclusión

Ahora tienes un proyecto agentOS funcional que crea un entorno aislado similar a Linux, ejecuta comandos Linux familiares usando herramientas basadas en WebAssembly y puede entregar ese entorno de forma segura a un agente de codificación con IA. Como agentOS ejecuta todo dentro de un entorno virtual ligero, no hay necesidad de iniciar un contenedor o máquina virtual para cada tarea.

Lo que hace diferente a agentOS es su enfoque. En lugar de reemplazar a los proveedores de sandbox tradicionales, ofrece un entorno rápido y ligero para ejecutar tareas de agente de corta duración y comandos Linux. Para muchos flujos de trabajo de automatización, eso puede significar tiempos de arranque más bajos, menor uso de memoria y menores costos de infraestructura.

Antes de añadir un agente de IA a tu aplicación, dedica tiempo a usar vm.exec() por sí solo. Prueba a ejecutar algunos comandos Linux comunes, construye pipelines simples y ejecuta intencionadamente un comando inválido para ver cómo agentOS informa de los errores. Esto te ayudará a entender qué pueden hacer las herramientas WebAssembly integradas y dónde están sus limitaciones.

Si tu aplicación eventualmente necesita funciones como ejecutar un navegador, compilar código nativo o ejecutar software fuera de los paquetes WASM disponibles, siempre puedes combinar agentOS con una solución de sandbox tradicional para esas cargas de trabajo específicas.

A medida que el proyecto continúa evolucionando, vale la pena experimentar con cargas de trabajo del mundo real para ver dónde encaja mejor en tu propio pipeline de automatización. El diseño ligero lo convierte en una opción interesante para la automatización Linux impulsada por IA, especialmente cuando los tiempos de arranque rápidos y el uso eficiente de recursos son importantes.