terrarium

Echte, wegwerfbare Computer in Sekunden, für dich und deinen KI-Agenten.

Forke eine frische Windows- oder Linux-Maschine, nutze sie, zerstöre sie, setze sie in der Zeit, die du zum Lesen dieses Textes brauchst, wieder auf makellos zurück.

Warum

Container sind der richtige Weg, einen Linux-Dienst auszuliefern, und der falsche Weg, ein ganzes System zu testen: Jeder Container leiht sich den Kernel des Hosts, daher kann ein Build, der in einem Container durchläuft, auf echter Hardware trotzdem scheitern. VMs haben das schon immer gelöst. Was ihnen fehlte, war der Container-Workflow: Image, ausführen, wegwerfen.

terrarium ist dieser Workflow auf Basis der VirtualBox, die du bereits hast. Forke ein Golden Image in einer Zehntelsekunde. Zerstöre den Fork und stelle ihn in Sekunden wieder her. Tue es von der Kommandozeile aus oder gib dieselbe Macht einem KI-Agenten über MCP. Es enthält keinen Virtualisierungscode, kapselt VBoxManage und fasst keine VM an, die es nicht selbst erstellt hat.

Wofür es verwendet wird:

• Ziel setzen, gehen. Gib einem Agenten über MCP eine echte Wegwerf-Maschine und ein Ziel; er baut, scheitert, setzt zurück und versucht es erneut – ganz ohne Aufsicht, bis hin zur vollständigen Installation von etwas – und die Aufgabe kann den Bildschirm betreffen, nicht nur die Kommandozeile.

• Lass einen Agenten eine Installation Ende-zu-Ende testen auf einer echten Maschine, vom ersten Boot bis zu einer funktionierenden App.

• Lass einen Agenten eine Anleitung schreiben oder einen Bug reproduzieren und eine Schritt-für-Schritt-Screenshot-Spur oder ein GIF zurückgeben, genau wie die Aufnahmen in dieser README.

• Isoliert, wegwerfbar, echt. Erledige sensible oder riskante Arbeiten auf einer Maschine, die du wegwerfen kannst, sodass sie niemals deine eigene berührt.

• Tests auf sauberer Maschine. Führe dein Installationsprogramm oder deinen Build auf einer Maschine aus, die deine Entwicklungsumgebung noch nie gesehen hat, und „bei mir funktioniert es“ ist kein Argument mehr.

Related MCP server: wisp

Inhalt

• Funktionen

• Installation

• Schnellstart

• Wie schnell

• Images

• Was es nicht ist

Funktionen

Jede Aufnahme unten ist echt: echte Befehle, echte Screenshots, die aus dem Videospeicher des Gasts gelesen werden, und ein Timer, der echte Wanduhr-Sekunden anzeigt. docs/demo erklärt, wie sie entstehen.

Windows forken: ein Desktop aus dem kalten Zustand in ~40s

Linux forken: SSH antwortet in ~20s

Zerstöre sie, dann setze sie zurück: in 13s wieder sauber

Claude gewinnt Minesweeper auf XP: kein SSH, nichts installiert

Wie es sich vergleicht

Wenn deine Arbeit in einen Container passt, nimm Docker. Wenn es eine echte, vollständige Maschine braucht, die du kaputt machen und wieder reparieren kannst – und die letzten beiden Zeilen sind Preise, die du zahlen kannst – dann ist die erste Spalte der Sinn dieses Projekts. VirtualBox hat absichtlich eine eigene Spalte: terrarium läuft darauf, also ist die grüne Hälfte dieser Spalte die Engine, und die rote Hälfte ist das, was dieses Projekt hinzufügt.

Eine Entwicklungsumgebung pro Projekt

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

terrarium up forkt eine nach dem Projekt benannte Umgebung, teilt den Projektordner unter /work im Gast und fügt sie zu ~/.ssh/config hinzu, sodass ssh <project> funktioniert und VS Code Remote-SSH es einen Klick entfernt sieht. down parkt sie, up holt sie zurück, revert setzt sie zurück.

Dein KI-Agent bekommt echte Computer

$ claude mcp add terrarium -- terrarium mcp

Dieselbe Binärdatei ist ein MCP-Server: jeder Befehl von oben als Werkzeug, plus screenshot, click, scroll, type und keys – Bildschirm, Maus und Tastatur werden über den Hypervisor injiziert, sodass nichts im Gast installiert wird und weder Netzwerk noch Gasterweiterungen nötig sind. So steuert ein Agent ein Installationsprogramm, einen Anmeldebildschirm oder ein Betriebssystem, das für SSH zu alt ist – genau das zeigt die Minesweeper-Aufnahme oben. Beim Verbinden weist der Server den Agenten an, zuerst doctor auszuführen und zu melden, was fehlt, statt planlos zu agieren.

• „Forke eine saubere Umgebung, baue das Projekt darin und sag mir, was die README ausgelassen hat.“

• „Installiere unsere App in der Windows-Umgebung und mache von jedem Schritt einen Screenshot.“

Für Windows-Gäste mit SSH öffnet terrarium rdp einen vollständigen Desktop, der bereits angemeldet ist.

Installation

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

Oder, mit Go >= 1.25, go install github.com/chryaner/terrarium/cmd/terrarium@latest, oder go build -o terrarium ./cmd/terrarium aus einem Klon.

Erfordert einen Windows-Host mit VirtualBox 7.x (VBoxManage im PATH). Dann prüfe, ob die Maschine bereit ist:

$ terrarium doctor

Linux-Images laden sich selbst herunter. Windows-Images werden aus einer Installations-ISO erstellt, die du bereitstellst – siehe Images für den Ablageort und den Grund.

Schnellstart

$ 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 und start parken und wecken eine Umgebung, ohne sie zu verlieren. fork --ttl 2h markiert eine Umgebung als ablaufend, und terrarium gc entfernt die abgelaufenen (und alle, deren VM du von Hand gelöscht hast).

Wie schnell

Gemessen auf einem Desktop (i9-14900K, NVMe, VirtualBox 7.2). Deine Zahlen werden abweichen; die Größenordnung nicht. Forks sind verknüpfte Klone: Sie teilen sich die Festplatte des Goldens, weshalb das Klonen eine Zehntelsekunde und Megabyte kostet, nicht Minuten und Gigabyte.

Images

Ein Golden ist das eigene veröffentlichte Image des Anbieters plus ein paar Zeilen YAML, sodass die Bytes immer von der Distribution stammen, die sie pflegt. Ein Image hinzuzufügen ist ein Pull-Request mit einer Datei.

Linux: wird für dich heruntergeladen

terrarium get <name> lädt das offizielle Cloud-Image herunter, versieht es mit einem generierten SSH-Schlüssel, bootet es einmal und erstellt einen Snapshot. Jeweils etwa eine Minute.

Windows: eigene ISO mitbringen

Es gibt kein Windows-Cloud-Image und die Medien von Microsoft dürfen nicht weitergegeben werden, also lädst du die ISO einmal herunter und terrarium führt das echte Installationsprogramm unbeaufsichtigt aus:

1. Lade die Installations-ISO von Microsoft herunter.

2. Speichere sie in %LOCALAPPDATA%\terrarium\isos\, benannt nach dem Rezept: win10.iso, winxp.iso.

3. terrarium get win10. Vollständig unbeaufsichtigt: etwa zehn Minuten für win10, sieben für XP.

win10 und winxp sind heute enthalten. XP stammt aus der Zeit vor OpenSSH, daher werden seine Forks über screenshot, click, type und keys gesteuert statt über exec, und sein Rezept benötigt einen Produktschlüssel, den du in einem lokalen Override angibst. Rezeptdetails, private Spiegel und die Interna der unbeaufsichtigten Installation findest du in docs/DESIGN.md.

Eigene Ebene erstellen

Ein Rezept kann auf einem anderen Image aufbauen statt auf Medien: from benennt die Basis, setup führt Befehle in einem Fork davon aus, und das Ergebnis wird zu einem neuen Golden zusammengeführt. Die YAML-Datei ist das teilbare Artefakt – ein Teammitglied mit derselben Datei baut aus seiner eigenen Basis eine äquivalente Maschine, sodass nie ein Festplatten-Image (und keine Windows-Lizenz) den Besitzer wechselt.

# %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 baut es in Sekunden auf einer vorhandenen Basis auf. Für Zustände, die du von Hand statt per Skript erstellt hast, macht terrarium promote <env> <name> aus einer konfigurierten Umgebung direkt ein Golden. terrarium rm --golden <name> entfernt ein Image, das du nicht mehr brauchst.

Was es nicht ist

• Noch nicht plattformübergreifend. Der Host muss Windows mit VirtualBox sein. Jeder Hypervisor-Aufruf steckt absichtlich hinter einem einzigen Paket, daher ist ein QEMU- oder Hyper-V-Treiber eine geplante Tür, kein Versprechen.

• Nicht für die Produktion. Forks sind Wegwerf-Ressourcen für Entwicklung und Tests.

• Kein Geheimnisverwalter. Das Passwort eines Windows-Goldens wird lokal im Klartext gespeichert und ist während der Installation kurzzeitig in der VBoxManage-Befehlszeile sichtbar. Verwende ein Wegwerf-Passwort.

Lizenz

Apache-2.0. Rezepte, Issues und Feldberichte sind willkommen; der nützlichste Beitrag ist ein Rezept für ein Image, das Menschen tatsächlich nutzen.