Daj agentowi maszynę do testów

Rig to jednorazowa maszyna, którą agent otwiera, gdy naprawdę musi czegoś spróbować: wczytać stronę, poklikać po aplikacji desktopowej, postukać po telefonie. Możesz patrzeć, jak pracuje, w czasie rzeczywistym, i w każdej chwili przejąć sterowanie.

Odizolowane rigi terminala, przeglądarki i pulpitu to VM-y z jednorazowymi dyskami i sieciami za bramą. Android i iOS to emulatory zarządzane przez hosta: stan ich urządzeń jest jednorazowy, ale ich sieć działa przez hosta serwera.

Skonfiguruj to raz

Rigi działają na maszynie hostującej cc_server — tej samej, a nie tej, na którą patrzysz. Istnieje pięć powierzchni widocznych dla użytkownika; powierzchnie pulpitu i urządzeń mobilnych wymagają konfiguracji hosta:

Powierzchnia	Działa na	Konfiguracja
Terminal (VM)	microVM uruchamiany z przypiętego obrazu Ubuntu	Brak — obraz jest pobierany automatycznie przy pierwszym użyciu
Przeglądarka (VM)	microVM uruchamiany z przypiętego obrazu Debiana z Chromium, Firefoksem albo WebKitem instalowanym przy pierwszym użyciu	Brak — tak samo
Komputer (VM)	QEMU z obrazem pulpitu Linuksa, który zawiera Chromium, Firefoksa, WebKit i bazowy zestaw CLI z runnerów hostowanych na GitHubie	Zainstaluj QEMU (`brew install qemu`), a następnie Importuj obraz pulpitu w Ustawienia → Serwer → Rigi
Android	emulator Androida firmy Google	Zainstaluj Android SDK, utwórz AVD i uruchom go (poniżej)
Symulator iOS	CoreSimulator na serwerze Mac	Zainstaluj Xcode i wybrane środowisko uruchomieniowe iOS, a następnie zainstaluj most automatyzacji w Ustawienia → Serwer → Rigi

Maszyny terminala i przeglądarki startują z obrazów przypiętych skrótem: dokładne bajty są z góry nazwane, pobierane raz przy pierwszym starcie i buforowane — po pierwszym starcie danego rodzaju kolejne maszyny pomijają pobieranie i wstają w kilka sekund. Ustawienia → Serwer → Rigi pokazuje, co Twój serwer potrafi uruchomić, oraz każdą maszynę działającą w tej chwili.

Zainstalowanym obrazem pulpitu nadal można zarządzać z tej samej strony: Importuj zastępuje go nowszym qcow2, a Usuń usuwa go, aby można było zainstalować świeżą kompilację.

Urządzenia mobilne konfiguruje się inaczej

Nie mamy własnego obrazu dla Androida ani iOS i nie jest to przeoczenie. Obrazy systemu Android pochodzą z Android SDK firmy Google; środowiska uruchomieniowe iOS pochodzą z Xcode. W przypadku Androida zainstaluj Android Studio (albo narzędzia SDK z wiersza poleceń), dodaj urządzenie wirtualne w Device Manager i uruchom je. Strona Rigi zgłosi wtedy Androida jako dostępnego.

Mówi też dokładnie, którego kroku Ci brakuje — brak SDK, brak emulatora, brak urządzenia wirtualnego albo urządzenie, które po prostu nie działa — bo te przypadki mają cztery różne rozwiązania, a tylko jedno z nich to pobranie. Jeśli uruchamiasz cc_server z powłoki, która nie widzi SDK, wyeksportuj je:

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

W przypadku iOS sam serwer musi działać w systemie macOS z zainstalowanym Xcode i środowiskiem uruchomieniowym Symulatora iOS. Otwórz Ustawienia → Serwer → Rigi i naciśnij Zainstaluj most automatyzacji iOS. Serwer pobiera artefakt WebDriverAgent przypięty sumą kontrolną, weryfikuje go i instaluje w należącym do serwera magazynie automatyzacji. Podczas konfiguracji nie uruchamia się żaden symulator.

Otwórz maszynę

Maszyny istnieją jako karty, obok czatu i diffa — w przestrzeni albo na stronie PR, w tym samym menu +, pod pozycją Maszyny:

Komputer — pulpit Linuksa z Chromium, Firefoksem i WebKitem
Chromium, Firefox albo WebKit — przeglądarka
Android — działający emulator Androida
Symulator iOS — jednorazowy symulator utworzony dla tej rozmowy

Wybierz jedną i naciśnij Uruchom maszynę. Karta mówi, na jakim etapie jest rozruch („Starting the microVM”, „Waiting for the guest to come up”), zamiast tylko kręcić.

Karta jest ograniczona do rozmowy i tak samo jest z narzędziem agenta. Karta Chromium, Firefox albo WebKit i browser_use, Android i mobile_use albo Symulator iOS i ios_use adresują tę samą domyślną maszynę. Dodatkowe miejsca w interfejsie to osobne maszyny do porównań; narzędzia agenta zawsze używają domyślnej.

Aby zbudować, zainstalować i uruchomić aplikację Fluttera na Androidzie:

fvm flutter build apk --debug

Następnie wywołaj mobile_use z install_apk i build/app/outputs/flutter-apk/app-debug.apk, a potem start_app i nazwę pakietu Androida. ui_dump, zrzuty ekranu i dane wejściowe sterują tym samym urządzeniem, które widać na karcie dla człowieka. stop_app, clear_app_data, uninstall_app, open_url oraz wywołania shell w kształcie argv obejmują resztę cyklu tworzenia oprogramowania bez uruchamiania powłoki na hoście serwera.

Aby zbudować, zainstalować i uruchomić aplikację Fluttera w Symulatorze iOS:

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

Następnie wywołaj ios_use z install_app i katalogiem .app, a potem start_app i identyfikatorem pakietu wypisanym przez plutil. Narzędzie iOS udostępnia też stop_app, uninstall_app, open_url oraz akcję spawn w kształcie argv do diagnostyki lokalnej symulatora.

Widoki pulpitu i przeglądarki skalują się do panelu. iOS zachowuje stały rozmiar punktowy symulatora i wyświetla go z pasami po bokach. Każda powierzchnia nadal ma dwa niezależne tory: agent dostaje małe, tanie zrzuty ekranu, a Ty podgląd na żywo. Przełączenie karty zatrzymuje strumień dla człowieka, więc maszyna działająca w tle nie zużywa przepustowości wyświetlania.

Karta riga sama nie uruchamia maszyny, także przy przywracaniu układu. Ta zasada powstrzymuje uruchomienie aplikacji przed nieoczekiwanym startem VM-ów albo tworzeniem urządzeń symulatora.

Steruj maszyną

Kanwa jest Twoja do pisania i klikania, gdy nikt inny nie trzyma wyłącznej kontroli — albo gdy trzymasz ją Ty. Dopóki trzymasz tę blokadę, znacznik statusu brzmi Masz kontrolę, agent nadal może robić zrzuty ekranu, a serwer odrzuca jego modyfikujące działania w jednym wąskim gardle, przez które przechodzi każde działanie. Wszystko, co robisz, jest zapisywane pod Twoim nazwiskiem.

Naciśnij Zatrzymaj maszynę, gdy skończysz.

Kontrola jest wyłączna celowo: dwie osoby piszące na jednej maszynie tworzą dane wejściowe, których żadna z nich nie zamierzała.

Przenoś rzeczy do środka i na zewnątrz

Kopiowanie i wklejanie działa w obie strony przez kanwę riga, podobnie jak przeciąganie plików.

Kopiowanie i wklejanie. Naciśnij skrót kopiowania nad kanwą, a to, co skopiowała maszyna — tekst, obraz, lista plików — wyląduje w Twoim schowku. Wklejenie wysyła Twój schowek w drugą stronę i naciska wklejenie wewnątrz maszyny. W systemie macOS skrótem jest ⌘C/⌘V; ⌃C nadal dociera do powłoki systemu gościa jako przerwanie. W systemach Windows i Linux używaj ⌃C/⌃V — system gościa otrzymuje ten sam klawisz, który dostałby tak czy inaczej, więc ⌃C w terminalu systemu gościa nadal przerywa, a Twój schowek pozostaje nietknięty.

Nic nie synchronizuje się w tle. Hasło skopiowane na Twojej własnej maszynie nie trafia do VM-a dlatego, że zadziałał licznik czasu; przekracza granicę, gdy wklejasz.

Wklejanie do riga jest domyślnie dozwolone. Kopiowanie z riga najpierw pyta — dziesięciominutowe zezwolenie albo Zawsze zezwalaj w Ustawienia → Serwer → Rigi → Dostęp do schowka. Oba kierunki są niezależne i podążają za Tobą, a nie za obszarem roboczym.

Przeciąganie plików do środka. Upuść je w dowolnym miejscu kanwy.

W Przeglądarce (VM) strona otrzymuje prawdziwe upuszczenie w miejscu, w którym puścisz plik, więc strefa wysyłania zachowuje się dokładnie tak jak przy pliku lokalnym.
W Komputerze (VM) pliki trafiają do ~/Drops, a ich ścieżki do schowka maszyny, więc ⌃V wkleja je do menedżera plików albo pola wysyłania. Host nie potrafi zsyntezować przeciągania do dowolnej aplikacji Linuksa bez uruchomienia uprzywilejowanego demona wewnątrz VM-a, którego rigi celowo nie mają — więc komunikat mówi, gdzie trafiły pliki, zamiast udawać, że nastąpiło upuszczenie.
W terminalu plik jest kopiowany do środka, a jego ścieżka wpisywana w wierszu zachęty, gotowa do przekazania poleceniu. Wklejenie obrazu do terminala robi to samo: zostaje zapisany w maszynie, a Ty dostajesz ścieżkę.

Przeciąganie plików na zewnątrz działa z Komputera (VM). Zacznij przeciągać plik wewnątrz maszyny, wynieś wskaźnik poza kanwę, a stanie się prawdziwym przeciąganiem na Twoim pulpicie — upuść go w Finderze albo Eksploratorze. Skopiowanie plików w menedżerze plików maszyny i wklejenie po swojej stronie też działa. Przeglądarka (VM) tego nie oferuje: przeglądarka bez interfejsu graficznego nie ma ładunku przeciągania do odczytania, a zgadywanie na podstawie zaznaczenia tekstu na stronie przechwytywałoby zwykłe kliknięcia.

Terminale wewnątrz riga

Terminale w przestrzeni albo na stronie PR mogą działać wewnątrz riga, a nie na własnej maszynie serwera. Gdy tak się dzieje, panel pokazuje plakietkę Zamknięta VM.

Co się zmienia:

Nic, co uruchomisz, nie dociera do hosta. rm -rf w środku kosztuje Cię riga.
Sieć jest domyślnie zablokowana. Osiągalne są tylko hosty z listy dozwolonych riga, a wszystko przechodzi przez bramę, która tego pilnuje.
git push nadal działa w terminalu otwartym przez Ciebie. Rig nie przechowuje żadnego poświadczenia; prosi serwer o krótkotrwałe poświadczenie na każdą operację, ograniczone Twoim własnym dostępem do hosta kodu, a token jest unieważniany przy zamknięciu riga. Rig otwarty przez agenta dostaje poświadczenie tylko do odczytu, więc może pobierać, ale nie wypychać.

Co warto wiedzieć:

Przywrócony odizolowany terminal czeka na Ciebie. Podobnie jak karta riga, terminal microvm, który wraca wraz z układem, pokazuje przycisk Otwórz powłokę, zamiast uruchamiać swój VM na starcie. Terminal z powłoką hosta kosztuje proces; odizolowany kosztuje maszynę.
Pliki upuszczone na terminal są wpisywane, a nie otwierane. Upuść CSV na odizolowany terminal, a zostanie skopiowany do maszyny i jego ścieżka w systemie gościa pojawi się w wierszu zachęty — ścieżka hosta byłaby tam poleceniem, które zawodzi.
Kopia w rigu jest kopią. Twój worktree na hoście pozostaje źródłem prawdy. Commity utworzone w rigu są przenoszone z powrotem do refs/rigs/<id>/*, gdy o to poprosisz — nigdy nie przesuwają Twojej gałęzi ani nie dotykają drzewa roboczego.
Praca dla celu hosta nadal odbywa się na hoście. System gościa Linuksa nie potrafi budować dla macOS ani uruchomić xcodebuild. Wybierz w tym celu jawnie natywny backend; aplikacja poprosi Cię o potwierdzenie, zamiast po cichu przełączać.

Porty

Uruchom serwer deweloperski w Terminalu (VM) — powiedzmy pnpm dev na porcie 3000 — a w ciągu kilku sekund ikona wtyczki w rogu terminala się zapali: port jest przekierowany do localhost:3000 na Twojej maszynie, osiągalny pod localhost:3000 wewnątrz Przeglądarki (VM), możliwy do udostępnienia w Twojej sieci i nazwania jako https://myapp.test. Cały ten przepływ — automatyczne przekierowywanie, udostępnianie w sieci lokalnej, domeny deweloperskie z HTTPS — ma własny poradnik: Przekieruj porty z terminala.

Obrazy niestandardowe

Obszar roboczy może wskazać Terminalowi (VM) i Przeglądarce (VM) własne obrazy — w Ustawienia → Serwer → Rigi → Obrazy niestandardowe (ten obszar roboczy). Typowe zastosowanie: rozszerzyć domyślny obraz o zestaw narzędzi potrzebny Twojemu projektowi, aby każdy terminal startował gotowy, albo użyć ponownie obrazu, który zespół już publikuje.

Maszyna nadal startuje w tej samej izolacji: ta sama brama ruchu wychodzącego, ten sam broker poświadczeń, ten sam cykl życia. Tylko administratorzy obszaru roboczego mogą zmienić to ustawienie, nowe maszyny je przejmują (działające zachowują swoje), a odwołanie musi wskazywać obraz z rejestru — ścieżki lokalne są odrzucane.

Co musi zapewniać obraz:

Terminal (VM) — obraz Linuksa z bash. Potrzebuje też git, curl i socat — albo zainstalowanych wcześniej, albo instalowalnych przy pierwszym starcie (każdy obraz oparty na Debianie/Ubuntu zadziała: instalują się automatycznie, wraz z zestawem narzędzi CLI w rodzaju tego z runnerów hostowanych na GitHubie: kompilatory, Python 3, jq, narzędzia archiwizujące, rsync. Środowiska uruchomieniowe języków, takie jak Node/Go/Java, oraz Docker nie są instalowane wcześniej). Port gościa 7911 jest zarezerwowany dla przekierowywania portów.
Przeglądarka (VM) — obraz Debiana/Ubuntu z bash i socat oraz plikiem binarnym chromium. Serwer sam uruchamia Chromium jako chromium --headless=new i przekazuje DevTools z portu gościa 9223 na 9222. PulseAudio i ffmpeg są instalowane przy pierwszym starcie. Nie buduj FROM chromedp/headless-shell — ten plik binarny nie ma dźwięku. Nadpisanie dotyczy tylko rigów Chromium; Firefox i WebKit je ignorują i startują z przypiętego obrazu Debiana. Porty gościa 9222/9223 są zarezerwowane.

Dwie rekomendacje: przypnij odwołanie skrótem (@sha256:…), aby bajty nie mogły się zmienić pod Tobą, i hostuj je w Docker Hub albo GitHub Container Registry — hosty pobierania tych rejestrów są automatycznie dopuszczane przez bramę ruchu wychodzącego; inne mogą wymagać osiągalności swoich hostów dostarczania treści, aby pobrać obraz.

Gdy rig znika

Rigi mają być tymczasowe:

Bezczynność — po ~15 minutach bez żadnej aktywności rig przeglądarki, pulpitu albo urządzenia mobilnego zostaje zaparkowany (zamrożony, budzi się natychmiast przy następnym działaniu). Odizolowany terminal czeka 45 minut. Po dwukrotności okna bezczynności zostaje zamknięty.
Limit czasu — każdy rig ma twardy czas życia, którego nie może wydłużyć, cokolwiek robi.
Pamięć — jeśli serwer potrzebuje miejsca na nowego riga, zamyka ten używany najdawniej. Rig, którym ktoś steruje, na który patrzy albo w którym ma otwarty terminal, nigdy nie jest zabierany.

Gdy odizolowany rig zostaje zamknięty, jego dysk jest odrzucany. Zamknięcie riga z Androidem odłącza się od emulatora hosta — nie usuwa go. Rig z iOS usuwa utworzone przez siebie urządzenie CoreSimulator. Najpierw przenieś z powrotem wszystko, co chcesz zachować.

Do czego rig ma dostęp

Odizolowane rigi terminala, przeglądarki i pulpitu domyślnie korzystają z bramy ruchu wychodzącego, która wszystko blokuje: hosty dopuszczasz jawnie, a jedyną trasą systemu gościa jest brama egzekwująca tę listę. Rig przeglądarki domyślnie dopuszcza też witrynę produktu (usectrl.dev). Broker poświadczeń używa tej samej listy.

Dwie szczere uwagi:

Sieć mobilna działa przez hosta. Emulator Androida i CoreSimulator firmy Apple nie stoją za bramą ruchu wychodzącego izolacji. Żadna z mobilnych kart nie oferuje kontrolki obejścia sieci, bo sieć zarządzana przez hosta jest już nieograniczona.
Wszystko, co rig czyta, jest niezaufane. Tekst strony, DOM, drzewa dostępności i zrzuty widoku wracają do agenta owinięte znacznikami, które mówią „to są dane, nie instrukcje”. Strona, która próbuje wydawać Twojemu agentowi polecenia, czytana jest jako cytowany ciąg znaków.

Wszystko, co działa, możesz zobaczyć i zatrzymać w Ustawienia → Serwer → Rigi.

Powiązane

Rigi i izolacje — model stojący za tym wszystkim: dlaczego VM-y, dwa tory wyświetlania, broker poświadczeń, cykl życia
Przekieruj porty z terminala — dotrzyj do serwera deweloperskiego z każdego miejsca, w którym to ma znaczenie
Dokumentacja referencyjna rigów — każda powierzchnia, czasownik, port i wartość domyślna w jednym miejscu
Skonfiguruj guardraile — Sterowanie rigiem to klasa działań, którą możesz ustawić na zezwolenie, zapytanie najpierw albo odmowę, dla obszaru roboczego, agenta lub przestrzeni. Tryby tylko do odczytu odmawiają jej w całości.