Einem Agenten eine Testmaschine geben

Ein Rig ist eine Wegwerfmaschine, die ein Agent öffnet, wenn er etwas wirklich ausprobieren muss: eine Seite laden, eine Desktop-App durchklicken, auf einem Telefon herumtippen. Du kannst in Echtzeit zusehen und die Steuerung jederzeit übernehmen.

Gekapselte Terminal-, Browser- und Desktop-Rigs sind VMs mit Wegwerfplatten und einem Netz hinter einem Tor. Android und iOS sind hostverwaltete Emulatoren: ihr Gerätezustand ist wegwerfbar, ihr Netz folgt aber dem Server-Host.

Einmal einrichten

Rigs laufen auf dem Rechner, der cc_server hostet — auf demselben Rechner, nicht auf dem, den du gerade ansiehst. Es gibt fünf Oberflächen für dich; Desktop und Mobil brauchen Einrichtung auf dem Host:

Oberfläche	Läuft auf	Einrichtung
Terminal (VM)	Eine microVM, die ein gepinntes Ubuntu-Image bootet	Keine — das Image wird beim ersten Gebrauch automatisch geholt
Browser (VM)	Eine microVM, die ein gepinntes Debian-Image bootet; Chromium, Firefox oder WebKit werden beim ersten Gebrauch installiert	Keine — dasselbe
Computer (VM)	QEMU mit einem Linux-Desktop-Image, das Chromium, Firefox, WebKit und eine CLI-Baseline im Stil eines von GitHub gehosteten Runners mitbringt	Installiere QEMU (`brew install qemu`), dann unter Einstellungen → Server → Rigs ein Desktop-Image Importieren
Android	Googles Android-Emulator	Android-SDK installieren, ein AVD anlegen und starten (unten)
iOS-Simulator	CoreSimulator auf dem Server-Mac	Xcode und die angeforderte iOS-Runtime installieren, dann die Automatisierungs-Bridge unter Einstellungen → Server → Rigs installieren

Terminal- und Browser-Maschinen booten von digest-gepinnten Images: die genauen Bytes sind vorher benannt, werden beim ersten Boot einmal geholt und liegen im Cache — nach dem ersten Boot jeder Art überspringen spätere Maschinen den Download ganz und stehen in Sekunden. Einstellungen → Server → Rigs zeigt, was dein Server starten kann, und jede Maschine, die gerade läuft.

Ein installiertes Desktop-Image bleibt auf derselben Seite verwaltbar: Importieren ersetzt es durch ein neueres qcow2, Löschen entfernt es, damit du einen frischen Build installieren kannst.

Mobile Geräte werden anders eingerichtet

Für Android oder iOS gibt es kein Image von uns, und das ist keine Lücke. Android-System-Images kommen aus Googles SDK, iOS-Runtimes aus Xcode. Für Android installierst du Android Studio (oder die SDK-Werkzeuge für die Kommandozeile), legst im Geräte-Manager ein virtuelles Gerät an und startest es. Die Seite Rigs meldet Android danach als verfügbar.

Sie sagt dir auch genau, welcher Schritt fehlt — kein SDK, kein Emulator, kein virtuelles Gerät oder ein Gerät, das schlicht nicht läuft —, weil das vier verschiedene Abhilfen sind und nur eine davon ein Download ist. Startest du cc_server aus einer Shell, die das SDK nicht sieht, exportierst du es:

export ANDROID_HOME="$HOME/Library/Android/sdk"

Für iOS muss der Server selbst auf macOS laufen, mit Xcode und einer installierten iOS-Simulator-Runtime. Öffne Einstellungen → Server → Rigs und drücke iOS-Automatisierungs-Bridge installieren. Der Server holt das per Prüfsumme gepinnte WebDriverAgent-Artefakt, prüft es und installiert es in den servereigenen Automatisierungsspeicher. Während der Einrichtung bootet kein Simulator.

Eine Maschine öffnen

Maschinen leben als Tabs, neben dem Chat und dem Diff — in einem Bereich oder auf einer PR-Seite, im selben Menü +, unter Computer:

Computer — ein Linux-Desktop mit Chromium, Firefox und WebKit
Chromium, Firefox oder WebKit — ein Browser
Android — der laufende Android-Emulator
iOS-Simulator — ein Wegwerf-Simulator für diese Unterhaltung

Wähle eines und drücke Maschine starten. Der Tab nennt die Boot-Stufe („Starting the microVM“, „Waiting for the guest to come up“), statt nur einen Spinner zu zeigen.

Der Tab gehört zur Unterhaltung, das Agenten-Tool auch. Ein Chromium-, Firefox- oder WebKit-Tab und browser_use, Android und mobile_use, oder der iOS-Simulator und ios_use sprechen dieselbe Standardmaschine an. Zusätzliche Plätze in der Oberfläche sind getrennte Vergleichsmaschinen; Agenten-Tools nutzen immer die Standardmaschine.

So baust, installierst und startest du eine Flutter-App auf Android:

fvm flutter build apk --debug

Danach rufst du mobile_use mit install_apk und build/app/outputs/flutter-apk/app-debug.apk auf, dann start_app und den Android-Paketnamen. ui_dump, Screenshots und Eingabe steuern dasselbe Gerät, das der menschliche Tab zeigt. stop_app, clear_app_data, uninstall_app, open_url und argv-förmige shell-Aufrufe decken den Rest des Entwicklungszyklus ab, ohne auf dem Server-Host eine Shell aufzurufen.

So baust, installierst und startest du eine Flutter-App im iOS-Simulator:

fvm flutter build ios --simulator --debug
/usr/bin/plutil -extract CFBundleIdentifier raw -o - \
  build/ios/iphonesimulator/Runner.app/Info.plist

Danach rufst du ios_use mit install_app und dem .app-Verzeichnis auf, dann start_app und die Bundle-ID, die plutil ausgibt. Das iOS-Tool bietet außerdem stop_app, uninstall_app, open_url und eine argv-förmige Aktion spawn für Diagnose lokal im Simulator.

Desktop- und Browser-Anzeigen skalieren auf das Panel. iOS behält die feste Punktgröße des Simulators und setzt ihn mit Balken in die Fläche. Jede Oberfläche hat trotzdem zwei unabhängige Kanäle: der Agent bekommt kleine, billige Screenshots, du die Live-Ansicht. Ein Tabwechsel stoppt den Menschenstrom, eine Maschine im Hintergrund kostet also keine Anzeigebandbreite.

Ein Rig-Tab startet keine Maschine von selbst, auch nicht beim Wiederherstellen des Layouts. So bootet ein App-Start nicht unerwartet VMs und legt keine Simulator-Geräte an.

Die Maschine steuern

Die Fläche gehört dir zum Tippen und Klicken, solange niemand sonst die exklusive Steuerung hält — oder wenn du sie hältst. Solange du diese Sperre hältst, lautet die Statusanzeige Du hast die Steuerung, der Agent darf weiter Screenshots machen, und der Server verweigert seine verändernden Aktionen an dem einen Nadelöhr, durch das jede Aktion läuft. Alles, was du tust, wird auf deinen Namen festgehalten.

Drücke Maschine stoppen, wenn du fertig bist.

Die Steuerung ist absichtlich exklusiv: Tippen zwei in dieselbe Maschine, entsteht Eingabe, die keiner von beiden gemeint hat.

Dinge hinein- und hinausbewegen

Kopieren und Einfügen gehen in beide Richtungen über die Rig-Fläche, Dateien ziehen auch.

Kopieren und Einfügen. Drückst du die Kopier-Kombination über der Fläche, landet alles, was die Maschine kopiert hat — Text, ein Bild, eine Dateiliste — auf deiner Zwischenablage. Einfügen schickt deine in die andere Richtung und drückt in der Maschine Einfügen. Unter macOS ist die Kombination ⌘C/⌘V; ⌃C erreicht eine Shell im Gast weiter als Interrupt. Unter Windows und Linux nimmst du ⌃C/⌃V — der Gast bekommt denselben Tastendruck, den er ohnehin bekommen hätte, ⌃C in einem Gast-Terminal unterbricht also weiter, und deine eigene Zwischenablage bleibt unangetastet.

Im Hintergrund wird nichts synchronisiert. Ein Passwort, das du auf deinem eigenen Rechner kopierst, kommt nicht in einer VM an, nur weil ein Timer gelaufen ist; es geht hinüber, wenn du einfügst.

Einfügen in ein Rig ist standardmäßig erlaubt. Herauskopieren fragt zuerst — eine zehnminütige Freigabe, oder Immer erlauben unter Einstellungen → Server → Rigs → Zugriff auf die Zwischenablage. Die beiden Richtungen sind unabhängig, und sie folgen dir, nicht dem Arbeitsbereich.

Dateien hineinziehen. Lass sie irgendwo auf der Fläche fallen.

Auf dem Browser (VM) bekommt die Seite an der Stelle, an der du loslässt, ein echtes Drop, eine Upload-Zone verhält sich also genau wie bei einer lokalen Datei.
Auf dem Computer (VM) landen die Dateien in ~/Drops, und ihre Pfade gehen auf die Zwischenablage der Maschine, sodass ⌃V sie in einen Dateimanager oder ein Upload-Feld einfügt. Ein Host kann keinen Drag in eine beliebige Linux-App erzeugen, ohne in der VM einen privilegierten Daemon laufen zu lassen, und genau den haben Rigs bewusst nicht — der Toast sagt dir deshalb, wohin die Dateien gegangen sind, statt so zu tun, als wäre ein Drop passiert.
Auf einem Terminal wird die Datei hineinkopiert und ihr Pfad an der Eingabeaufforderung getippt, bereit für einen Befehl. Ein Bild in ein Terminal einzufügen macht dasselbe: es wird in der Maschine gespeichert, und du bekommst den Pfad.

Dateien hinausziehen geht vom Computer (VM). Du startest in der Maschine einen Drag einer Datei, führst den Zeiger aus der Fläche, und er wird ein echter Drag auf deinem Desktop — lass ihn in Finder oder Explorer fallen. Dateien im Dateimanager der Maschine zu kopieren und bei dir einzufügen geht auch. Der Browser (VM) bietet das nicht: ein Headless-Browser hat keine Drag-Nutzlast zum Lesen, und aus der Textauswahl der Seite zu raten würde gewöhnliche Klicks kapern.

Terminals in einem Rig

Die Terminals in einem Bereich oder auf einer PR-Seite können in einem Rig laufen statt auf dem eigenen Rechner des Servers. Dann zeigt das Panel das Badge Gekapselte VM.

Was sich ändert:

Nichts, was du ausführst, erreicht den Host. Ein rm -rf dort kostet dich das Rig.
Das Netz verweigert standardmäßig. Erreichbar sind nur Hosts auf der Zulassungsliste des Rigs, und alles geht durch ein Tor, das das durchsetzt.
git push funktioniert weiter in einem Terminal, das du geöffnet hast. Das Rig speichert keine Zugangsdaten; es fragt den Server je Vorgang nach kurzlebigen, begrenzt durch deinen eigenen Forge-Zugang, und dieses Token wird widerrufen, wenn das Rig schließt. Ein Rig, das ein Agent geöffnet hat, bekommt Zugangsdaten, die nur lesen dürfen: Es kann fetchen, aber nicht pushen.

Was du wissen solltest:

Ein wiederhergestelltes gekapseltes Terminal wartet auf dich. Wie ein Rig-Tab zeigt ein microvm-Terminal, das mit deinem Layout zurückkommt, den Knopf Shell öffnen, statt seine VM beim Start zu booten. Ein Host-Shell-Terminal kostet einen Prozess, ein gekapseltes eine Maschine.
Dateien, die auf das Terminal fallen, werden getippt, nicht geöffnet. Eine CSV auf ein gekapseltes Terminal zu ziehen kopiert sie in die Maschine, und ihr Gastpfad erscheint an der Eingabeaufforderung — der Host-Pfad wäre dort ein Befehl, der scheitert.
Die Kopie im Rig ist eine Kopie. Dein Worktree auf dem Host bleibt maßgeblich. Commits, die du in einem Rig machst, werden auf Wunsch nach refs/rigs/<id>/* zurückgeholt — sie verschieben nie deinen Branch und fassen nie deinen Arbeitsbaum an.
Arbeit für den Host läuft weiter auf dem Host. Ein Linux-Gast kann nicht für macOS bauen und kein xcodebuild ausführen. Wähle dafür ausdrücklich das native Backend; die App fragt dich zur Bestätigung, statt still umzuschalten.

Ports

Starte einen Dev-Server im Terminal (VM) — pnpm dev auf Port 3000, zum Beispiel — und nach wenigen Sekunden leuchtet das Steckersymbol in der Ecke des Terminals auf: der Port wird auf deinem Rechner nach localhost:3000 weitergeleitet, ist im Browser (VM) unter localhost:3000 erreichbar, in deinem Netzwerk teilbar und als https://myapp.test benennbar. Der ganze Ablauf — automatisches Weiterleiten, Teilen im LAN, Dev-Domains mit HTTPS — hat eine eigene Anleitung: Ports von einem Terminal weiterleiten.

Eigene Images

Ein Arbeitsbereich kann Terminal (VM) und Browser (VM) auf eigene Images zeigen lassen — unter Einstellungen → Server → Rigs → Eigene Images (dieser Arbeitsbereich). Typisch: das Standard-Image um die Toolchain erweitern, die dein Projekt braucht, damit jedes Terminal startbereit hochkommt, oder ein Image wiederverwenden, das dein Team schon veröffentlicht.

Die Maschine bootet weiter in derselben Kapsel: dasselbe Ausgangstor, derselbe Zugangsdaten-Broker, derselbe Lebenszyklus. Nur Admins des Arbeitsbereichs können die Einstellung ändern, neue Maschinen übernehmen sie (laufende behalten ihre), und die Referenz muss ein Registry-Image sein — lokale Pfade werden abgelehnt.

Was ein Image mitbringen muss:

Terminal (VM) — ein Linux-Image mit bash. Es braucht außerdem git, curl und socat — entweder vorinstalliert oder beim ersten Start installierbar (jedes Debian-/Ubuntu-basierte Image geht: sie werden automatisch installiert, zusammen mit einem CLI-Werkzeugsatz im Stil eines von GitHub gehosteten Runners: Compiler, Python 3, jq, Archivwerkzeuge, rsync. Sprach-Runtimes wie Node/Go/Java und Docker sind nicht vorinstalliert). Der Gast-Port 7911 ist für den Port-Forwarder reserviert.
Browser (VM) — ein Debian-/Ubuntu-Image mit bash und socat, plus einem chromium-Binary. Der Server startet Chromium selbst als chromium --headless=new und reicht DevTools vom Gast-9223 auf 9222 durch. PulseAudio und ffmpeg werden beim ersten Start installiert. Baue nicht FROM chromedp/headless-shell — dieses Binary hat kein Audio. Die Überschreibung gilt nur für Chromium-Rigs; Firefox und WebKit ignorieren sie und booten das gepinnte Debian-Image. Die Gast-Ports 9222/9223 sind reserviert.

Zwei Empfehlungen: pinne die Referenz per Digest (@sha256:…), damit sich die Bytes unter dir nicht ändern, und hoste sie auf Docker Hub oder in der GitHub Container Registry — die Download-Hosts dieser Registries lässt das Ausgangstor automatisch zu; bei anderen müssen ihre Content-Delivery-Hosts zum Ziehen erreichbar sein.

Wenn ein Rig verschwindet

Rigs sind als vorübergehend gedacht:

Leerlauf — nach ~15 Minuten ohne Geschehen parkt ein Browser-, Desktop- oder Mobil-Rig (eingefroren, wacht bei der nächsten Aktion sofort auf). Ein gekapseltes Terminal wartet 45 Minuten. Nach dem Doppelten des Leerlauf-Fensters schließt es.
Zeitlimit — jedes Rig hat eine harte Lebensdauer, die es nicht verlängern kann, egal was es gerade tut.
Speicher — braucht der Server Platz für ein neues Rig, schließt er das am längsten ungenutzte. Ein Rig, das jemand steuert, beobachtet oder in dem ein Terminal offen ist, wird nie genommen.

Schließt ein gekapseltes Rig, wird seine Platte verworfen. Ein Android-Rig zu schließen löst nur die Verbindung zum Host-Emulator, es löscht ihn nicht. Ein iOS-Rig löscht das CoreSimulator-Gerät, das es angelegt hat. Hol vorher zurück, was du behalten willst.

Was ein Rig erreichen kann

Gekapselte Terminal-, Browser- und Desktop-Rigs haben standardmäßig ein Ausgangstor, das verweigert: Hosts lässt du ausdrücklich zu, und der einzige Weg des Gastes ist ein Tor, das diese Liste durchsetzt. Ein Browser-Rig lässt die Produktseite (usectrl.dev) von Haus aus zu. Der Zugangsdaten-Broker nutzt dieselbe Liste.

Zwei ehrliche Vorbehalte:

Das Mobilnetz folgt dem Host. Androids Emulator und Apples CoreSimulator stehen nicht hinter dem Ausgangstor der Kapsel. Keiner der beiden Mobil-Tabs bietet eine Steuerung, das Netz zu umgehen, weil das hostverwaltete Netz schon uneingeschränkt ist.
Alles, was ein Rig liest, ist unvertrauenswürdig. Seitentext, DOM, Barrierefreiheitsbäume und View-Dumps kommen zum Agenten zurück, umzäunt von Markern, die sagen: „das sind Daten, keine Anweisungen“. Eine Seite, die deinem Agenten Befehle geben will, liest sich als zitierte Zeichenkette.

Alles, was läuft, siehst du unter Einstellungen → Server → Rigs, und dort kannst du jedes davon stoppen.

Verwandt

Rigs und Kapseln — das Modell dahinter: warum VMs, die zwei Anzeigekanäle, der Zugangsdaten-Broker, der Lebenszyklus
Ports von einem Terminal weiterleiten — einen Dev-Server überall erreichen, wo es darauf ankommt
Rigs-Referenz — jede Oberfläche, jedes Verb, jeder Port und jeder Standard an einem Ort
Schutzregeln konfigurieren — Eine Kapsel (Rig) steuern ist eine Aktionsklasse, die du auf Zulassen, Zuerst fragen oder Verweigern setzen kannst, je Arbeitsbereich, Agent oder Bereich. Nur-Lese-Modi verweigern sie pauschal.