Dejte agentovi stroj na testování

Stanice je jednorázový stroj, který agent otevře, když má něco opravdu vyzkoušet: načíst stránku, proklikat desktopovou aplikaci, proťukat telefon. Sleduješ ho v reálném čase a řízení převezmeš, kdykoli chceš.

Izolovaný terminál, prohlížeč a plocha jsou VM s jednorázovými disky a sítí za bránou. Android a iOS jsou emulátory spravované hostitelem: stav zařízení je jednorázový, síť sleduje hostitele serveru.

Připrav to jednou

Stanice běží na stroji, na kterém běží cc_server — na něm, ne na stroji, na který se díváš. Vidíš pět ploch. Plocha počítače a mobilní plochy potřebují přípravu na hostiteli:

Plocha	Běží na	Příprava
Terminal (VM)	microVM, které naběhne z připnutého obrazu Ubuntu	Nic — obraz se při prvním použití stáhne sám
Browser (VM)	microVM z připnutého obrazu Debianu; Chromium, Firefox nebo WebKit se doinstalují při prvním použití	Nic — stejně
Počítač (VM)	QEMU s obrazem linuxové plochy, který veze Chromium, Firefox, WebKit a základní sadu CLI jako runner hostovaný na GitHubu	Nainstaluj QEMU (`brew install qemu`), pak v Nastavení → Server → Stanice obraz plochy Importovat
Android	emulátor Androidu od Googlu	Nainstaluj Android SDK, vytvoř AVD a spusť ho (níže)
Simulátor iOS	CoreSimulator na Macu serveru	Nainstaluj Xcode a požadovaný runtime iOS, pak v Nastavení → Server → Stanice nainstaluj můstek pro automatizaci

Terminál a prohlížeč nabíhají z obrazů připnutých digestem: přesné bajty jsou pojmenované předem, stáhnou se jednou při prvním startu a zůstanou v cache. Po prvním startu každého druhu další stroje stahování přeskočí a naběhnou během sekund. Nastavení → Server → Stanice ukazuje, co server umí nabootovat, a každý stroj, který právě běží.

Nainstalovaný obraz plochy se spravuje na téže stránce: Importovat ho nahradí novějším qcow2 a Smazat ho odstraní, takže nainstaluješ nové sestavení.

Mobilní zařízení se nastavují jinak

Vlastní obraz pro Android ani iOS nemáme. Je to schválně. Systémové obrazy Androidu bereš ze SDK od Googlu, runtimy iOS z Xcode. Pro Android nainstaluj Android Studio (nebo nástroje SDK pro příkazový řádek), v Device Manager přidej virtuální zařízení a spusť ho. Stránka Stanice pak Android nahlásí jako dostupný.

Řekne ti taky přesně, který krok chybí — žádné SDK, žádný emulátor, žádné virtuální zařízení, nebo zařízení, které zkrátka neběží — protože každý z těch stavů se řeší jinak a jen jeden z nich je stažení. Když cc_server spouštíš ze shellu, který SDK nevidí, exportuj ho:

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

U iOS musí server sám běžet na macOS s nainstalovaným Xcode a runtime simulátoru iOS. Otevři Nastavení → Server → Stanice a stiskni Nainstalovat můstek pro automatizaci iOS. Server stáhne artefakt WebDriverAgent připnutý kontrolním součtem, ověří ho a nainstaluje do úložiště automatizace, které patří serveru. Během přípravy se žádný simulátor nespustí.

Otevři stroj

Stroje žijí jako karty, vedle chatu a diffu — v prostoru nebo na stránce PR, ve stejném menu +, pod Počítače:

Počítač — linuxová plocha s Chromium, Firefox a WebKit
Chromium, Firefox nebo WebKit — prohlížeč
Android — běžící emulátor Androidu
Simulátor iOS — jednorázový simulátor vytvořený pro tuhle konverzaci

Jedno vyber a stiskni Spustit stroj. Karta pojmenuje fázi startu („Starting the microVM“, „Waiting for the guest to come up“), takže se netočí naslepo.

Karta patří ke konverzaci a nástroj agenta taky. Karta Chromium, Firefox nebo WebKit a browser_use, Android a mobile_use, nebo Simulátor iOS a ios_use míří na stejný výchozí stroj. Další pozice v rozhraní jsou samostatné stroje na srovnání; nástroje agenta berou vždy ten výchozí.

Flutter aplikaci na Androidu sestavíš, nainstaluješ a spustíš takhle:

fvm flutter build apk --debug

Pak zavolej mobile_use s install_apk a build/app/outputs/flutter-apk/app-debug.apk, potom start_app a název balíčku Androidu. ui_dump, snímky obrazovky a vstup řídí totéž zařízení, které ukazuje lidská karta. stop_app, clear_app_data, uninstall_app, open_url a volání shell ve tvaru argv pokryjí zbytek vývojového cyklu, aniž by se na hostiteli serveru spouštěl shell.

Flutter aplikaci na simulátoru iOS sestavíš, nainstaluješ a spustíš takhle:

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

Pak zavolej ios_use s install_app a adresářem .app, potom start_app a identifikátor balíčku, který vypsal plutil. Nástroj pro iOS navíc nabízí stop_app, uninstall_app, open_url a akci spawn ve tvaru argv pro diagnostiku přímo v simulátoru.

Obraz plochy a prohlížeče se přizpůsobí panelu. iOS si nechá pevnou velikost v bodech a kolem obrazu nechá pruhy. Každá plocha má pořád dva nezávislé kanály: agent dostává malé a levné snímky, ty živý náhled. Přepnutí karty lidský proud zastaví, takže stroj na pozadí obraz nepřenáší.

Karta stanice stroj sama nespustí, ani při obnovení rozložení. Spuštění aplikace tak samo od sebe nenabootuje VM a nevytvoří zařízení simulátoru.

Řiď stroj

Na plátno píšeš a klikáš, kdykoli výhradní řízení nedrží nikdo jiný — a taky když ho držíš ty. Dokud ten zámek držíš, stavový štítek říká Máte řízení, agent pořád pořizuje snímky a server jeho akce měnící stav odmítne v jediném úzkém místě, kterým projde každá akce. Všechno, co uděláš, se zapíše pod tvým jménem.

Až skončíš, stiskni Zastavit stroj.

Řízení je výhradní schválně. Když do jednoho stroje píšou dva, vznikne vstup, který nechtěl ani jeden.

Dovnitř a ven

Kopírování a vkládání funguje přes plátno stanice oběma směry. Přetahování souborů taky.

Kopírování a vkládání. Stiskni nad plátnem kombinaci pro kopírování a to, co stroj zkopíroval — text, obrázek, seznam souborů — skončí na tvé schránce. Vložení pošle tvou schránku opačným směrem a uvnitř stroje stiskne vložení. Na macOS je kombinace ⌘C/⌘V; ⌃C dál dorazí do shellu hosta jako přerušení. Na Windows a Linuxu použij ⌃C/⌃V. Host dostane tentýž stisk, který by dostal tak jako tak, takže ⌃C v terminálu hosta pořád přeruší a tvoje schránka zůstane, jak je.

Na pozadí se nic nesynchronizuje. Heslo zkopírované na vlastním stroji přejde do VM až ve chvíli, kdy ho vložíš.

Vložení do stanice je ve výchozím stavu povolené. Kopírování ven ze stanice se nejdřív zeptá — povolení na deset minut, nebo Vždy povolit v Nastavení → Server → Stanice → Přístup ke schránce. Oba směry jsou nezávislé a patří k tobě, ne k pracovnímu prostoru.

Soubory dovnitř. Pusť je kdekoli na plátno.

Na Browser (VM) dostane stránka v místě, kde pustíš, skutečné přetažení, takže zóna nahrání se chová stejně jako u místního souboru.
Na Počítač (VM) soubory přistanou v ~/Drops a jejich cesty se položí na schránku stroje, takže ⌃V je vloží do správce souborů nebo do pole nahrání. Hostitel by přetažení do libovolné linuxové aplikace syntetizoval jen privilegovaným démonem ve VM a ten stanice schválně nemají. Hláška proto řekne, kam soubory šly.
Na terminálu se soubor zkopíruje dovnitř a jeho cesta se napíše na výzvu, připravená k předání příkazu. Vložení obrázku do terminálu udělá totéž: uloží se ve stroji a dostaneš cestu.

Soubory ven fungují z Počítač (VM). Začni soubor přetahovat uvnitř stroje, vyveď ukazatel z plátna a na tvé ploše z toho bude skutečné přetažení — pusť ho ve Finderu nebo v Průzkumníkovi. Kopírování ve správci souborů stroje a vložení na tvé straně funguje taky. Browser (VM) to nenabízí: bezhlavý prohlížeč nemá data přetažení, která by šla číst, a odhad z textového výběru na stránce by unesl obyčejná kliknutí.

Terminály ve stanici

Terminály v prostoru nebo na stránce PR můžou běžet ve stanici, ne na vlastním stroji serveru. Když ano, panel ukáže odznak Izolované VM.

Co se změní:

Nic, co spustíš, se na hostitele nedostane. rm -rf uvnitř tě stojí stanici.
Síť má výchozí odmítnutí. Dosažitelní jsou jen hostitelé ze seznamu povolených té stanice a všechno jde přes bránu, která seznam vynucuje.
git push pořád funguje v terminálu, který sis otevřel. Stanice nemá uložený přihlašovací údaj. Na každou operaci si od serveru vyžádá krátkodobý, ohraničený tvým vlastním přístupem k forge, a ten token se při zavření stanice zruší. Stanice, kterou otevřel agent, dostane přihlašovací údaj jen pro čtení, takže umí fetch, ale ne push.

Co je dobré vědět:

Obnovený izolovaný terminál počká na tebe. Stejně jako karta stanice ukáže terminál microvm, který se vrátí s tvým rozložením, tlačítko Otevřít shell. Při spuštění aplikace své VM nenabootuje. Terminál na shellu hostitele stojí proces. Izolovaný stojí stroj.
Soubory puštěné na terminál se napíšou na výzvu. Pusť CSV na izolovaný terminál: zkopíruje se do stroje a na výzvě se objeví jeho cesta v hostu. Cesta na hostiteli by tam byl příkaz, který selže.
Kopie ve stanici je kopie. Worktree na hostiteli zůstává autoritativní. Commity uvnitř stanice se na požádání přenesou do refs/rigs/<id>/*. Tvou větví nepohnou a na pracovní strom nesáhnou.
Práce pro hostitele pořád běží na hostiteli. Linuxový host neumí sestavit pro macOS ani spustit xcodebuild. Nativní backend pro to vyber výslovně. Aplikace si vyžádá potvrzení a sama se potichu nepřepne.

Porty

Spusť vývojový server v Terminal (VM) — třeba pnpm dev na portu 3000 — a během pár sekund se v rohu terminálu rozsvítí ikona zástrčky: port se předá na localhost:3000 na tvém stroji, je dosažitelný na localhost:3000 uvnitř Browser (VM), dá se sdílet ve tvé síti a pojmenovat jako https://myapp.test. Celý postup — automatické předání, sdílení v LAN, vývojové domény s HTTPS — má vlastní návod: Přesměrujte porty z terminálu.

Vlastní obrazy

Pracovní prostor může Terminal (VM) a Browser (VM) nasměrovat na vlastní obrazy — v Nastavení → Server → Stanice → Vlastní obrazy (tento pracovní prostor). Typicky: rozšířit výchozí obraz o toolchain, který projekt potřebuje, aby každý terminál startoval připravený, nebo znovu použít obraz, který tým už publikuje.

Stroj pořád nabíhá ve stejném izolovaném prostředí: stejná brána odchozího provozu, stejný broker přihlašovacích údajů, stejný životní cyklus. Nastavení smí změnit jen správci pracovního prostoru. Nové stroje ho převezmou, běžící si nechají svoje. Odkaz musí být obraz z registru — místní cesty se odmítnou.

Co obraz musí mít:

Terminal (VM) — linuxový obraz s bash. Potřebuje taky git, curl a socat — buď předinstalované, nebo doinstalovatelné při prvním startu (funguje jakýkoli obraz založený na Debianu nebo Ubuntu: nainstalují se samy, spolu se sadou CLI ve stylu runneru hostovaného na GitHubu: překladače, Python 3, jq, nástroje na archivy, rsync. Jazykové runtimy jako Node/Go/Java a Docker předinstalované nejsou). Port hosta 7911 je vyhrazený pro předávání portů.
Browser (VM) — obraz Debianu nebo Ubuntu s bash a socat, plus binárka chromium. Server Chromium spouští sám jako chromium --headless=new a předává DevTools z hosta 9223 na 9222. PulseAudio a ffmpeg se nainstalují při prvním startu. Nepoužívej FROM chromedp/headless-shell — ta binárka nemá zvuk. Přepsání platí jen pro stanice Chromium; Firefox a WebKit ho ignorují a naběhnou z připnutého obrazu Debianu. Porty hosta 9222/9223 jsou vyhrazené.

Dvě doporučení: odkaz připni digestem (@sha256:…), aby se bajty nemohly potichu změnit, a dej ho na Docker Hub nebo do GitHub Container Registry. Hostitelé, odkud se z těch registrů stahuje, projdou bránou odchozího provozu sami. U jiných registrů musí být pro stažení dosažitelní i hostitelé, kteří obsah doručují.

Když stanice zmizí

Stanice mají být dočasné:

Nečinnost — po ~15 minutách, kdy se nic neděje, se stanice prohlížeče, plochy nebo mobilu zaparkuje (zmrazená, při další akci se probudí hned). Izolovaný terminál čeká 45 minut. Po dvojnásobku okna nečinnosti se zavře.
Časový limit — každá stanice má pevný strop životnosti a ten neprodlouží, ať právě dělá cokoli.
Paměť — když server potřebuje místo na novou stanici, zavře tu, která se nepoužívala nejdéle. Stanici, kterou někdo řídí, sleduje, nebo v ní má otevřený terminál, nesejme.

Když se izolovaná stanice zavře, její disk se zahodí. Zavření stanice Androidu ji od emulátoru na hostiteli odpojí a emulátor nesmaže. Stanice iOS smaže zařízení CoreSimulator, které vytvořila. Nejdřív si odnes, co si chceš nechat.

Kam stanice dosáhne

Izolovaný terminál, prohlížeč a plocha mají ve výchozím stavu bránu odchozího provozu s výchozím odmítnutím: hostitele povoluješ výslovně a jediná cesta hosta je brána, která ten seznam vynucuje. Stanice prohlížeče navíc rovnou pustí web produktu (usectrl.dev). Broker přihlašovacích údajů používá stejný seznam.

Dvě věci rovnou:

Síť mobilu sleduje hostitele. Emulátor Androidu a CoreSimulator od Applu nejsou za bránou odchozího provozu izolovaného prostředí. Ani jedna mobilní karta nenabízí ovládání obejití sítě: síť spravovaná hostitelem už omezení nemá.
Všechno, co stanice přečte, je nedůvěryhodné. Text stránky, DOM, stromy přístupnosti a výpisy zobrazení se k agentovi vracejí ohraničené značkami, které říkají „tohle jsou data, ne pokyny“. Stránka, která se pokusí dávat agentovi příkazy, se čte jako citovaný text.

Všechno, co běží, uvidíš a cokoli z toho zastavíš v Nastavení → Server → Stanice.

Související

Stanice a izolovaná prostředí — model za tím vším: proč VM, dva kanály zobrazení, broker přihlašovacích údajů, životní cyklus
Přesměrujte porty z terminálu — jak se k vývojovému serveru dostat odkudkoli, odkud ho potřebuješ
Reference stanic — každá plocha, sloveso, port a výchozí hodnota na jednom místě
Nastavte guardraily — Drive an enclosure (rig) (Ovládat izolované prostředí (stanici)) je třída akce, kterou nastavíš na Povolit, Nejdřív se zeptat nebo Zakázat, pro pracovní prostor, agenta nebo prostor. Režimy jen pro čtení ji odmítnou celé.