Bir ajana test için makine verme

Rig, bir ajanın gerçekten bir şey denemesi gerektiğinde açtığı atılabilir bir makinedir: bir sayfa yüklemek, bir masaüstü uygulamasında tıklamak, bir telefonu kurcalamak. Çalışmasını gerçek zamanlı izleyebilir ve denetimi istediğiniz an devralabilirsiniz.

Yalıtılmış terminal, tarayıcı ve masaüstü rig’leri, tek kullanımlık disklere ve kapılı ağlara sahip VM’lerdir. Android ve iOS ise ana makine tarafından yönetilen emülatörlerdir: aygıt durumları atılabilir, ancak ağ bağlantıları sunucu ana makinesini izler.

Bir kez kurun

Rig’ler cc_server’ı barındıran makinede çalışır — baktığınız makinede değil, aynı makinede. Beş kullanıcıya dönük yüzey vardır; masaüstü ve mobil yüzeyler ana makine kurulumu gerektirir:

Yüzey	Çalıştığı yer	Kurulum
Terminal (VM)	Sabitlenmiş bir Ubuntu imajı önyükleyen bir microVM	Yok — imaj ilk kullanımda otomatik olarak indirilir
Tarayıcı (VM)	İlk kullanımda Chromium, Firefox veya WebKit kurulan sabitlenmiş bir Debian imajı önyükleyen bir microVM	Yok — aynı
Bilgisayar (VM)	Chromium, Firefox, WebKit ve GitHub tarafından barındırılan runner tarzı bir CLI temeli içeren bir Linux masaüstü imajıyla QEMU	QEMU’yu kurun (`brew install qemu`), ardından Ayarlar → Sunucu → Rigs altından bir masaüstü imajını İçe aktar ile ekleyin
Android	Google’ın Android emülatörü	Android SDK’yı kurun, bir AVD oluşturun ve başlatın (aşağıda)
iOS Simülatörü	Sunucu Mac’inde CoreSimulator	Xcode’u ve istenen iOS çalışma zamanını kurun, ardından Ayarlar → Sunucu → Rigs altından otomasyon köprüsünü kurun

Terminal ve tarayıcı makineleri özetle sabitlenmiş imajlardan önyüklenir: tam bayt dizisi önceden adlandırılır, ilk önyüklemede bir kez indirilir ve önbelleğe alınır — her türün ilk önyüklemesinden sonra, sonraki makineler indirmeyi tamamen atlar ve saniyeler içinde açılır. Ayarlar → Sunucu → Rigs, sunucunuzun neleri önyükleyebileceğini ve şu an çalışan tüm makineleri gösterir.

Kurulu bir masaüstü imajı aynı sayfadan yönetilebilir durumda kalır: İçe aktar onu daha yeni bir qcow2 ile değiştirir, Sil ise onu kaldırır; böylece yeni bir derleme kurabilirsiniz.

Mobil cihazlar farklı kurulur

Android veya iOS için bize ait bir imaj yoktur ve bu bir eksiklik değildir. Android sistem imajları Google’ın SDK’sından; iOS çalışma zamanları Xcode’dan gelir. Android için Android Studio’yu (veya komut satırı SDK araçlarını) kurun, Device Manager içinde bir sanal cihaz ekleyin ve başlatın. Rigs sayfası ardından Android’i kullanılabilir olarak bildirir.

Ayrıca tam olarak hangi adımı atladığınızı da söyler — SDK yok, emülatör yok, sanal cihaz yok ya da yalnızca çalışmayan bir cihaz — çünkü bunların dört farklı çözümü vardır ve yalnızca biri indirmedir. cc_server’ı SDK’yı göremeyen bir kabuktan başlatıyorsanız, onu dışa aktarın:

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

iOS için sunucunun kendisi, Xcode ve kurulu bir iOS Simülatörü çalışma zamanıyla macOS üzerinde çalışmalıdır. Ayarlar → Sunucu → Rigs bölümünü açın ve iOS otomasyon köprüsünü yükle düğmesine basın. Sunucu, sağlama toplamıyla sabitlenmiş WebDriverAgent artefaktını indirir, doğrular ve sunucuya ait otomasyon deposuna kurar. Kurulum sırasında hiçbir simülatör önyüklenmez.

Bir makine açın

Makineler, sohbetin ve diff’in yanında sekmeler olarak yaşar — bir alanda ya da bir PR sayfasında, aynı + menüsünde, Makineler altında:

Bilgisayar — Chromium, Firefox ve WebKit içeren bir Linux masaüstü
Chromium, Firefox veya WebKit — bir tarayıcı
Android — çalışan Android emülatörü
iOS Simülatörü — bu konuşma için oluşturulan atılabilir bir simülatör

Birini seçin ve Makineyi başlat düğmesine basın. Sekme, yalnızca dönen bir simge göstermek yerine önyüklemenin hangi aşamada olduğunu söyler (“Starting the microVM”, “Waiting for the guest to come up”).

Sekme konuşmaya kapsamlanır ve ajan aracı da öyledir. Bir Chromium, Firefox veya WebKit sekmesi ile browser_use, Android ile mobile_use, iOS Simülatörü ile ios_use aynı varsayılan makineyi adresler. Ek arayüz yuvaları ayrı karşılaştırma makineleridir; ajan araçları her zaman varsayılanı kullanır.

Android’de bir Flutter uygulamasını derlemek, kurmak ve başlatmak için:

fvm flutter build apk --debug

Ardından mobile_use aracını install_apk ve build/app/outputs/flutter-apk/app-debug.apk ile çağırın; peşinden start_app ve Android paket adını verin. ui_dump, ekran görüntüleri ve girdi, insan sekmesinde gösterilen aynı aygıtı sürer. stop_app, clear_app_data, uninstall_app, open_url ve argv biçimli shell çağrıları, geliştirme döngüsünün geri kalanını sunucu ana makinesinde bir kabuk çağırmadan kapsar.

iOS Simülatörü’nde bir Flutter uygulamasını derlemek, kurmak ve başlatmak için:

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

Ardından ios_use aracını install_app ve .app dizini ile çağırın; peşinden start_app ve plutil tarafından yazdırılan paket tanımlayıcısını verin. iOS aracı ayrıca stop_app, uninstall_app, open_url ve simülatöre özel tanılamalar için argv biçimli bir spawn eylemi sunar.

Masaüstü ve tarayıcı görüntüleri panele göre yeniden boyutlanır. iOS, simülatörün sabit punto boyutunu korur ve görüntüyü siyah bantlarla çerçeveler. Her yüzeyin hâlâ iki bağımsız kanalı vardır: ajan küçük ve ucuz ekran görüntüleri alırken siz canlı görünümü alırsınız. Sekmeler arasında geçiş yapmak insan akışını durdurur; böylece arka plandaki bir makine görüntü bant genişliği harcamaz.

Bir rig sekmesi, düzen geri yükleme sırasında dahil olmak üzere, kendi başına bir makine başlatmaz. Bu kural, bir uygulama başlatmanın beklenmedik biçimde VM önyüklemesini ya da simülatör aygıtı oluşturmasını önler.

Makineyi yönetin

Tuval, başka biri özel denetimi elinde tutmadığı sürece — ya da o kilidi siz tutuyorsanız — yazmanıza ve tıklamanıza açıktır. Bu kilidi elinizde tuttuğunuz sürece durum etiketi Kontrol sizde diye okunur, ajan yine de ekran görüntüsü alabilir ve sunucu, onun değiştirici eylemlerini her eylemin geçtiği tek geçiş noktasında reddeder. Yaptığınız her şey adınıza kaydedilir.

İşiniz bittiğinde Makineyi durdur düğmesine basın.

Denetim bilinçli olarak tekeldir: tek bir makineye iki aktörün yazması, ikisinin de amaçlamadığı girdiler üretir.

İçeri ve dışarı taşıma

Kopyalama ve yapıştırma, rig tuvali üzerinde iki yönde de çalışır; dosya sürüklemek de öyle.

Kopyala ve yapıştır. Tuvalin üzerindeyken kopyalama kısayoluna basın; makinenin kopyaladığı şey — metin, bir görüntü, bir dosya listesi — panonuza düşer. Yapıştırma sizinkini ters yönde gönderir ve makinenin içinde yapıştırmaya basar. macOS’ta kısayol ⌘C/⌘V’dir; ⌃C ise misafir kabuğa hâlâ kesme sinyali olarak ulaşır. Windows ve Linux’ta ⌃C/⌃V kullanın — misafir, zaten alacağı aynı tuş vuruşunu alır; böylece misafir terminaldeki ⌃C yine kesme yapar ve sizin panonuz olduğu gibi kalır.

Arka planda hiçbir şey eşitlenmez. Kendi makinenizde kopyaladığınız bir parola, bir zamanlayıcı çaldı diye bir VM’in içine ulaşmaz; ancak siz yapıştırdığınızda geçer.

Bir rig’e yapıştırmaya varsayılan olarak izin verilir. Bir rig’den kopyalamak ise önce sorar — on dakikalık bir izin ya da Ayarlar → Sunucu → Rigs → Pano erişimi altındaki Her zaman izin ver. İki yön birbirinden bağımsızdır ve çalışma alanını değil, sizi izler.

Dosyaları içeri sürükleyin. Onları tuvalin herhangi bir yerine bırakın.

Tarayıcı (VM) üzerinde sayfa, bıraktığınız noktada gerçek bir bırakma olayı alır; böylece bir yükleme alanı, yerel bir dosyayla tam olarak nasıl davranıyorsa öyle davranır.
Bilgisayar (VM) üzerinde dosyalar ~/Drops içine düşer ve yolları makinenin panosuna konur; böylece ⌃V onları bir dosya yöneticisine ya da bir yükleme alanına yapıştırır. Bir ana makine, VM’in içinde ayrıcalıklı bir daemon çalıştırmadan rastgele bir Linux uygulamasına sürükleme üretemez — rig’lerde bu bilinçli olarak yoktur — bu yüzden toast, bir bırakma olmuş gibi davranmak yerine dosyaların nereye gittiğini söyler.
Bir terminalde dosya içeri kopyalanır ve yolu istem satırına yazılır, komuta geçirilmeye hazır olur. Bir terminale görüntü yapıştırmak da aynı şeyi yapar: makinede kaydedilir ve yolu size verilir.

Dosyaları dışarı sürükleyin özelliği Bilgisayar (VM)’den çalışır. Makinenin içinde bir dosyayı sürüklemeye başlayın, imleci tuvalin dışına taşıyın; dosya masaüstünüzde gerçek bir sürüklemeye dönüşür — onu Finder veya Explorer’a bırakın. Makinenin dosya yöneticisinde dosyaları kopyalayıp kendi tarafınızda yapıştırmak da çalışır. Tarayıcı (VM) bunu sunmaz: başsız bir tarayıcının okuyacağı bir sürükleme yükü yoktur ve sayfanın metin seçiminden tahmin yürütmek sıradan tıklamaları ele geçirirdi.

Bir rig içindeki terminaller

Bir alandaki ya da bir PR sayfasındaki terminaller, sunucunun kendi makinesi yerine bir rig’in içinde çalışabilir. Çalıştıklarında panel bir Kapalı VM rozeti gösterir.

Değişenler:

Çalıştırdığınız hiçbir şey ana makineye ulaşmaz. Oradaki bir rm -rf size rig’e mal olur.
Ağ varsayılan olarak reddeder. Yalnızca rig’in izin listesindeki host’lara erişilebilir ve her şey bunu uygulayan bir kapıdan geçer.
git push, sizin açtığınız bir terminalde yine çalışır. Rig’de saklı bir kimlik bilgisi yoktur; her işlem için sunucudan, kendi forge erişiminizle sınırlı, kısa ömürlü bir tane ister ve bu token rig kapandığında iptal edilir. Bir ajanın açtığı rig salt okunur bir kimlik bilgisi alır; bu yüzden fetch yapabilir ama push edemez.

Bilinmesi gerekenler:

Geri yüklenen yalıtılmış terminal sizi bekler. Bir rig sekmesi gibi, düzeninizle birlikte geri gelen bir microvm terminali de başlatma sırasında VM’ini önyüklemek yerine bir Shell’i aç düğmesi gösterir. Ana makine kabuğundaki bir terminal bir sürece mal olur; yalıtılmış olan ise bir makineye.
Terminale bırakılan dosyalar açılmaz, yazılır. Yalıtılmış bir terminale bir CSV bırakın; dosya makineye kopyalanır ve istem satırında misafirdeki yolu görünür — ana makinedeki yol, orada başarısız olacak bir komut olurdu.
Rig’deki kopya bir kopyadır. Ana makinedeki worktree’niz doğruluk kaynağı olarak kalır. Bir rig’in içinde yaptığınız commit’ler, siz istediğinizde refs/rigs/<id>/* içine geri taşınır — dalınızı asla taşımaz ve çalışma ağacınıza dokunmaz.
Ana makineyi hedefleyen iş yine ana makinede çalışır. Bir Linux misafiri macOS için derleme yapamaz ya da xcodebuild çalıştıramaz. Bunun için yerel arka ucu açıkça seçin; uygulama sessizce geçiş yapmak yerine sizden onay ister.

Portlar

Terminal (VM) içinde bir geliştirme sunucusu çalıştırın — diyelim ki 3000 portunda pnpm dev — ve birkaç saniye içinde terminalin köşesindeki fiş simgesi yanar: port, makinenizdeki localhost:3000 adresine yönlendirilir, Tarayıcı (VM) içinde localhost:3000 adresinden erişilebilir, ağınızda paylaşılabilir ve https://myapp.test olarak adlandırılabilir. Akışın tamamı — otomatik yönlendirme, LAN paylaşımı, HTTPS’li geliştirme etki alanları — kendi kılavuzunda: Bir terminalden port yönlendirme.

Özel imajlar

Bir çalışma alanı, Terminal (VM) ve Tarayıcı (VM)’yi kendi imajlarına yönlendirebilir — Ayarlar → Sunucu → Rigs → Özel imajlar (bu çalışma alanı) altından. Tipik kullanım: varsayılan imajı, projenizin ihtiyaç duyduğu araç zinciriyle genişleterek her terminalin hazır başlamasını sağlamak ya da ekibinizin zaten yayımladığı bir imajı yeniden kullanmak.

Makine yine aynı yalıtılmış ortamın içinde önyüklenir: aynı çıkış kapısı, aynı kimlik bilgisi broker’ı, aynı yaşam döngüsü. Bu ayarı yalnızca çalışma alanı yöneticileri değiştirebilir, yeni makineler bunu alır (çalışanlar kendilerininkini korur) ve referans bir registry imajı olmalıdır — yerel yollar reddedilir.

Bir imajın sağlaması gerekenler:

Terminal (VM) — bash içeren bir Linux imajı. Ayrıca git, curl ve socat gerekir — ya önceden kurulu ya da ilk başlatmada kurulabilir olmalıdır (Debian/Ubuntu tabanlı her imaj çalışır: bunlar, GitHub tarafından barındırılan runner tarzı bir CLI araç setiyle — derleyiciler, Python 3, jq, arşiv araçları, rsync — birlikte otomatik olarak kurulur. Node/Go/Java gibi dil çalışma zamanları ve Docker önceden kurulu değildir). Misafir portu 7911 port yönlendiricisi için ayrılmıştır.
Tarayıcı (VM) — bash ve socat ile bir chromium ikilisi içeren bir Debian/Ubuntu imajı. Sunucu, Chromium’u kendisi chromium --headless=new olarak başlatır ve DevTools’u misafirdeki 9223 portundan 9222’ye aktarır. PulseAudio ve ffmpeg ilk başlatmada kurulur. FROM chromedp/headless-shell ile derlemeyin — o ikilide ses yoktur. Bu geçersiz kılma yalnızca Chromium rig’leri için geçerlidir; Firefox ve WebKit bunu yok sayar ve sabitlenmiş Debian imajını önyükler. Misafir portları 9222/9223 ayrılmıştır.

İki öneri: referansı özetle (@sha256:…) sabitleyin ki baytlar altınızdan değişemesin ve imajı Docker Hub ya da GitHub Container Registry’de barındırın — bu registry’lerin indirme host’ları çıkış kapısından otomatik olarak geçirilir; diğerlerinin çekilebilmesi için içerik dağıtım host’larının erişilebilir olması gerekebilir.

Bir rig ortadan kalktığında

Rig’ler geçici olacak şekilde tasarlanmıştır:

Boşta kalma — hiçbir şey olmadan ~15 dakika geçince bir tarayıcı, masaüstü ya da mobil rig park eder (donar, sonraki eylemde anında uyanır). Yalıtılmış bir terminal 45 dakika bekler. Boşta kalma penceresinin iki katı sonra kapanır.
Süre sınırı — her rig’in, ne yapıyor olursa olsun uzatamayacağı katı bir ömrü vardır.
Bellek — sunucunun yeni bir rig için yere ihtiyacı olursa, en son kullanılan rig’i kapatır. Birinin yönettiği, izlediği ya da içinde bir terminal açık olan bir rig asla alınmaz.

Yalıtılmış bir rig kapandığında diski atılır. Bir Android rig’ini kapatmak, ana makinedeki emülatörden bağlantıyı keser — onu silmez. Bir iOS rig’i, oluşturduğu CoreSimulator aygıtını siler. Saklamak istediğiniz her şeyi önce geri taşıyın.

Bir rig nereye erişebilir

Yalıtılmış terminal, tarayıcı ve masaüstü rig’leri varsayılan olarak reddeden bir çıkış kapısıyla başlar: host’ları açıkça izin verirsiniz ve misafirin tek yolu bu listeyi uygulayan bir kapıdır. Bir tarayıcı rig’i ayrıca ürün sitesini (usectrl.dev) kutudan çıktığı gibi kabul eder. Kimlik bilgisi broker’ı aynı listeyi kullanır.

İki dürüst uyarı:

Mobil ağ, ana makineyi izler. Android’in emülatörü ve Apple’ın CoreSimulator’ı yalıtılmış ortamın çıkış kapısının arkasında değildir. Hiçbir mobil sekme, ağı atlama denetimi sunmaz; çünkü ana makine tarafından yönetilen ağ zaten kısıtlamasızdır.
Bir rig’in okuduğu her şey güvenilmezdir. Sayfa metni, DOM, erişilebilirlik ağaçları ve görünüm dökümleri ajana, “bu veridir, talimat değildir” diyen işaretlerle çevrelenmiş olarak döner. Ajanınıza emir vermeye çalışan bir sayfa, alıntılanmış bir dize olarak okunur.

Çalışan her şeyi Ayarlar → Sunucu → Rigs altında görebilir ve istediğinizi durdurabilirsiniz.

İlgili

Rig’ler ve yalıtılmış ortamlar — bunun arkasındaki model: neden VM’ler, iki görüntü kanalı, kimlik bilgisi broker’ı, yaşam döngüsü
Bir terminalden port yönlendirme — bir geliştirme sunucusuna önemli olduğu her yerden erişin
Rig’ler — her yüzey, fiil, port ve varsayılan tek bir yerde
Korumaları yapılandırma — Bir enclosure’ı (rig) yönet, izin ver, önce sor ya da reddet olarak ayarlayabileceğiniz bir eylem sınıfıdır — çalışma alanı, ajan veya alan başına. Salt okunur modlar bunu tümden reddeder.