terrarium

Ordenadores reales y desechables en segundos, para ti y tu agente de IA.

Haz un fork de una máquina Windows o Linux recién creada, úsala, rómpela y restablécela impecable en el tiempo que tardas en leer esto.

Por qué

Los contenedores son la forma correcta de distribuir un servicio Linux y la forma incorrecta de probar un sistema completo: cada contenedor toma prestado el kernel del host, así que una compilación que funciona en uno puede fallar en hardware real. Las máquinas virtuales siempre han resuelto eso. Lo que les faltaba era el flujo de trabajo de los contenedores: imagen, ejecutar, tirar.

terrarium es ese flujo de trabajo sobre el VirtualBox que ya tienes. Haz un fork de una imagen golden en una décima de segundo. Destroza el fork y restablécelo en segundos. Hazlo desde la línea de comandos, o dale el mismo poder a un agente de IA a través de MCP. No incluye código de virtualización, envuelve VBoxManage y nunca toca una VM que no haya creado.

Para qué se usa:

• Establece el objetivo y aléjate. Dale a un agente una máquina real desechable a través de MCP y un objetivo; el agente compila, falla, revierte y reintenta por sí solo, sin supervisión, hasta instalar algo de principio a fin. Y la tarea puede implicar la pantalla, no solo la línea de comandos.

• Deja que un agente pruebe una instalación de principio a fin en una máquina real, desde el primer arranque hasta una aplicación funcional.

• Deja que un agente escriba una guía o reproduzca un bug y devuelva un rastro de capturas de pantalla paso a paso o un GIF, exactamente como las grabaciones de este README.

• Aislado, desechable, real. Haz trabajo sensible o arriesgado en una máquina que puedas tirar, para que nunca toque la tuya.

• Pruebas en máquina limpia. Ejecuta tu instalador o tu compilación en una máquina que nunca ha visto tu configuración de desarrollo, y «funciona en mi máquina» deja de ser un argumento.

Related MCP server: wisp

Contenido

• Características

• Instalación

• Inicio rápido

• Velocidad

• Imágenes

• Lo que no es

Características

Cada grabación de abajo es real: comandos reales, capturas de pantalla reales leídas de la memoria de vídeo del invitado, y un cronómetro que muestra segundos de reloj reales. docs/demo explica cómo se hacen.

Fork de Windows: un escritorio en frío en ~40s

Fork de Linux: SSH respondiendo en ~20s

Rómpela y luego revierte: limpia de nuevo en 13s

Claude gana al Buscaminas en XP: sin SSH, sin instalar nada

Comparativa

Si tu trabajo cabe en un contenedor, usa Docker. Cuando necesitas una máquina real y completa que puedas romper y desromper (y las dos últimas filas son precios que puedes pagar), la primera columna es el propósito de este proyecto. VirtualBox tiene su propia columna a propósito: terrarium se ejecuta sobre él, así que la mitad verde de esa columna es el motor, y la mitad roja es lo que este proyecto añade.

Un entorno de desarrollo por proyecto

# terrarium.yaml, committed in your repo
image: ubuntu-24.04
cpus: 4
memory: 4096

terrarium up hace un fork de un entorno con el nombre del proyecto, comparte la carpeta del proyecto en /work dentro del invitado y lo añade a ~/.ssh/config, de modo que ssh <project> funciona y VS Code Remote-SSH lo ve a un clic de distancia. down lo aparca, up lo devuelve, revert lo restablece.

Tu agente de IA consigue ordenadores reales

$ claude mcp add terrarium -- terrarium mcp

El mismo binario es un servidor MCP: cada comando anterior como herramienta, además de screenshot, click, scroll, type y keys: pantalla, ratón y teclado inyectados a través del hipervisor, de modo que no se instala nada en el invitado y no se necesitan red ni Guest Additions. Así es como un agente maneja un instalador, una pantalla de inicio de sesión o un sistema operativo demasiado antiguo para SSH, exactamente lo que muestra la grabación del Buscaminas de arriba. Al conectar, el servidor le dice al agente que ejecute primero doctor y que informe de lo que falta en lugar de hacer intentos a ciegas.

• «Haz un fork de un entorno limpio, compila el proyecto dentro y dime qué se le escapó al README».

• «Instala nuestra aplicación en el entorno de Windows y captura cada paso».

Para invitados Windows con SSH, terrarium rdp abre un escritorio completo con la sesión ya iniciada.

Instalación

$ scoop bucket add terrarium https://github.com/chryaner/terrarium
$ scoop install terrarium

O, con Go >= 1.25, go install github.com/chryaner/terrarium/cmd/terrarium@latest, o go build -o terrarium ./cmd/terrarium desde un clon.

Requiere un host Windows con VirtualBox 7.x (VBoxManage en PATH). Luego comprueba que la máquina está lista:

$ terrarium doctor

Las imágenes Linux se descargan solas. Las imágenes Windows se crean a partir de un ISO de instalación que tú proporcionas: consulta Imágenes para saber dónde colocarlo y por qué.

Inicio rápido

$ terrarium get debian-12          # build a golden: download, boot, snapshot (~40s)
$ terrarium fork debian-12 t1      # a throwaway machine, SSH-ready in ~20s
$ terrarium exec t1 -- uname -a
$ terrarium ssh t1
$ terrarium revert t1              # back to clean in seconds
$ terrarium rm t1

down y start aparcan y despiertan un entorno sin perderlo. fork --ttl 2h marca un entorno para que expire, y terrarium gc elimina los expirados (y cualquier VM que hayas borrado a mano).

Velocidad

Medido en un sobremesa (i9-14900K, NVMe, VirtualBox 7.2). Tus números variarán; la forma no. Los forks son clones enlazados: comparten el disco de la golden, por eso clonar cuesta una décima de segundo y megabytes, no minutos y gigabytes.

Imágenes

Una golden es la imagen publicada por el propio proveedor más unas pocas líneas de YAML, por lo que los bytes siempre proceden de la distribución que los mantiene. Añadir una imagen es una pull request con un solo archivo.

Linux: se descarga por ti

terrarium get <name> descarga la imagen cloud oficial, la inicializa con una clave SSH generada, la arranca una vez y le hace una instantánea. Aproximadamente un minuto cada una.

Windows: trae tu propio ISO

No hay una imagen cloud de Windows y los medios de Microsoft no se pueden redistribuir, así que descargas el ISO una vez y terrarium ejecuta el instalador real de forma desatendida:

1. Descarga el ISO de instalación desde Microsoft.

2. Guárdalo en %LOCALAPPDATA%\terrarium\isos\, con el nombre de la receta: win10.iso, winxp.iso.

3. terrarium get win10. Totalmente desatendido: unos diez minutos para win10, siete para XP.

win10 y winxp se incluyen hoy. XP es anterior a OpenSSH, por lo que sus forks se manejan mediante screenshot, click, type y keys en lugar de exec, y su receta necesita una clave de producto que tú proporcionas en una anulación local. Los detalles de las recetas, los espejos privados y los entresijos de la instalación desatendida están en docs/DESIGN.md.

Crea tu propia capa

Una receta puede construirse sobre otra imagen en lugar de sobre un medio: from define la base, setup ejecuta comandos en un fork de esa base, y el resultado se aplana en una nueva golden. El archivo YAML es el artefacto compartible: un compañero con el mismo archivo construye una máquina equivalente desde su propia base, de modo que ninguna imagen de disco (ni ninguna licencia de Windows) cambia de manos.

# %LOCALAPPDATA%\terrarium\recipes\team-dev.yaml
name: team-dev
from: debian-12
setup:
  - sudo apt-get update
  - sudo apt-get install -y git build-essential

terrarium get team-dev la construye en segundos sobre una base existente. Para un estado que hayas creado a mano en lugar de con un script, terrarium promote <env> <name> aplana directamente un entorno configurado en una golden. terrarium rm --golden <name> elimina una imagen con la que ya has terminado.

Lo que no es

• Todavía no es multiplataforma. El host debe ser Windows con VirtualBox. Cada llamada al hipervisor está encapsulada en un único paquete por diseño, así que un controlador QEMU o Hyper-V es una puerta planificada, no una promesa.

• No es para producción. Los forks son ganado para desarrollo y pruebas.

• No es un gestor de secretos. La contraseña de una golden de Windows se almacena en texto plano localmente y es brevemente visible en la línea de comandos de VBoxManage durante la instalación. Usa una contraseña desechable.

Licencia

Apache-2.0. Recetas, incidencias e informes de campo son bienvenidos; la contribución más útil es una receta para una imagen que la gente use de verdad.