Dar a un agente una computadora para probar

Un rig es una máquina desechable que un agente abre cuando de verdad necesita probar algo: cargar una página, recorrer con clics una aplicación de escritorio, tocar alrededor de un teléfono. Puedes verlo trabajar en tiempo real y tomar los controles cuando quieras.

Los rigs con recinto de terminal, navegador y escritorio son VM con discos desechables y redes sujetas a una puerta de salida. Android e iOS son emuladores gestionados por el host: el estado de su dispositivo es desechable, pero su red sigue la del host del servidor.

Configúralo una vez

Los rigs se ejecutan en la máquina que aloja cc_server — esa misma máquina, no la que estás viendo. Hay cinco superficies para el usuario; las de escritorio y móviles necesitan configuración en el host:

Superficie	Se ejecuta en	Configuración
Terminal (VM)	Una microVM que arranca una imagen de Ubuntu fijada	Ninguna — la imagen se descarga automáticamente en el primer uso
Navegador (VM)	Una microVM que arranca una imagen de Debian fijada, con Chromium, Firefox o WebKit instalados en el primer uso	Ninguna — igual
Computadora (VM)	QEMU con una imagen de escritorio Linux que incluye Chromium, Firefox, WebKit y una base de CLI tipo GitHub-hosted runner	Instala QEMU (`brew install qemu`) y luego Importar una imagen de escritorio en Ajustes → Servidor → Rigs
Android	El emulador de Android de Google	Instala el SDK de Android, crea un AVD y arráncalo (más abajo)
Simulador de iOS	CoreSimulator en la Mac del servidor	Instala Xcode y el runtime de iOS solicitado, y luego instala el puente de automatización en Ajustes → Servidor → Rigs

Las máquinas de terminal y navegador arrancan desde imágenes fijadas por digest: los bytes exactos se nombran de antemano, se descargan una vez en el primer arranque y quedan en caché; después del primer arranque de cada tipo, las máquinas posteriores se saltan la descarga por completo y aparecen en segundos. Ajustes → Servidor → Rigs muestra lo que tu servidor puede arrancar y todas las máquinas que se ejecutan en este momento.

Una imagen de escritorio instalada se sigue administrando desde la misma página: Importar la reemplaza por una qcow2 más reciente y Eliminar la quita para que puedas instalar una compilación nueva.

Los dispositivos móviles se configuran de otra manera

No hay una imagen nuestra para Android ni iOS, y eso no es una omisión. Las imágenes de sistema de Android vienen del SDK de Google; los runtimes de iOS, de Xcode. Para Android, instala Android Studio (o las herramientas de SDK de línea de comandos), agrega un dispositivo virtual en el Administrador de dispositivos y arráncalo. Después, la página Rigs informa que Android está disponible.

También te dice exactamente qué paso te falta —sin SDK, sin emulador, sin dispositivo virtual o con un dispositivo que simplemente no está en ejecución— porque esos casos tienen cuatro soluciones distintas y solo una de ellas es una descarga. Si inicias cc_server desde un shell que no puede ver el SDK, expórtalo:

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

Para iOS, el servidor mismo debe ejecutarse en macOS con Xcode y un runtime del Simulador de iOS instalados. Abre Ajustes → Servidor → Rigs y presiona Instalar el puente de automatización de iOS. El servidor descarga el artefacto de WebDriverAgent fijado por suma de verificación, lo verifica y lo instala en el almacén de automatización propiedad del servidor. No se arranca ningún simulador durante la configuración.

Abre una máquina

Las máquinas viven como pestañas, junto al chat y al diff — en un espacio o en una página de PR, en el mismo menú +, bajo Máquinas:

Computadora — un escritorio Linux con Chromium, Firefox y WebKit
Chromium, Firefox o WebKit — un navegador
Android — el emulador de Android en ejecución
Simulador de iOS — un simulador desechable creado para esta conversación

Elige uno y presiona Iniciar la máquina. La pestaña indica en qué etapa va el arranque («Iniciando la microVM», «Esperando a que el huésped esté listo») en lugar de solo girar.

La pestaña está limitada a la conversación, y la herramienta del agente también. Una pestaña de Chromium, Firefox o WebKit y browser_use, Android y mobile_use, o el Simulador de iOS y ios_use apuntan a la misma máquina predeterminada. Los espacios de interfaz adicionales son máquinas de comparación independientes; las herramientas del agente siempre usan la predeterminada.

Para compilar, instalar e iniciar una app de Flutter en Android:

fvm flutter build apk --debug

Luego llama a mobile_use con install_apk y build/app/outputs/flutter-apk/app-debug.apk, seguido de start_app y el nombre del paquete de Android. ui_dump, las capturas de pantalla y la entrada controlan el mismo dispositivo que se muestra en la pestaña humana. stop_app, clear_app_data, uninstall_app, open_url y las llamadas shell con forma de argv cubren el resto del ciclo de desarrollo sin invocar un shell en el host del servidor.

Para compilar, instalar e iniciar una app de Flutter en el Simulador de iOS:

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

Luego llama a ios_use con install_app y el directorio .app, seguido de start_app y el identificador de paquete que imprima plutil. La herramienta de iOS también expone stop_app, uninstall_app, open_url y una acción spawn con forma de argv para diagnósticos locales del simulador.

Las pantallas de escritorio y navegador se redimensionan al panel. iOS conserva el tamaño fijo en puntos del simulador y le añade barras negras. Cada superficie sigue teniendo dos canales independientes: el agente recibe capturas de pantalla pequeñas y baratas mientras tú ves la vista en vivo. Cambiar de pestaña detiene el canal humano, así que una máquina en segundo plano no consume ancho de banda de pantalla.

Una pestaña de rig no inicia una máquina por sí sola, ni siquiera durante la restauración del diseño. Esa regla evita que al abrir la app se arranquen VM o se creen dispositivos de simulador sin esperarlo.

Controla la máquina

El lienzo es tuyo para escribir y hacer clic siempre que nadie más tenga el control exclusivo, o cuando lo tengas tú. Mientras tienes ese bloqueo, la etiqueta de estado dice Tienes el control, el agente todavía puede tomar capturas de pantalla y el servidor rechaza sus acciones que mutan en el único punto de paso obligado por el que cruza cada acción. Todo lo que haces queda registrado a tu nombre.

Presiona Detener la máquina cuando termines.

El control es exclusivo a propósito: dos actores escribiendo en una misma máquina producen entrada que ninguno de los dos quiso.

Mueve cosas hacia dentro y hacia fuera

Copiar y pegar funcionan en ambos sentidos en el lienzo del rig, y arrastrar archivos también.

Copiar y pegar. Presiona la combinación de copiar sobre el lienzo y lo que haya copiado la máquina —texto, una imagen, una lista de archivos— llegará a tu portapapeles. Pegar envía el tuyo en sentido contrario y presiona pegar dentro de la máquina. En macOS la combinación es ⌘C/⌘V; ⌃C sigue llegando a un shell del huésped como interrupción. En Windows y Linux usa ⌃C/⌃V: el huésped recibe la misma pulsación que recibiría de todos modos, así que ⌃C en un terminal del huésped sigue interrumpiendo y tu propio portapapeles no se toca.

Nada se sincroniza en segundo plano. Una contraseña que copias en tu propia máquina no llega al interior de una VM porque se dispare un temporizador; cruza cuando pegas.

Pegar en un rig está permitido de forma predeterminada. Copiar desde un rig pregunta primero —un permiso de diez minutos, o Permitir siempre en Ajustes → Servidor → Rigs → Acceso al portapapeles. Los dos sentidos son independientes y te siguen a ti, no al espacio de trabajo.

Arrastrar archivos hacia dentro. Suéltalos en cualquier parte del lienzo.

En el Navegador (VM), la página recibe un soltado real en el punto donde sueltas, así que una zona de subida se comporta exactamente como lo haría con un archivo local.
En la Computadora (VM), los archivos llegan a ~/Drops y sus rutas van al portapapeles de la máquina, así que ⌃V los pega en un gestor de archivos o en un campo de subida. Un host no puede sintetizar un arrastre hacia una aplicación Linux arbitraria sin ejecutar un demonio privilegiado dentro de la VM, que es precisamente lo que los rigs deliberadamente no tienen — por eso el aviso te dice a dónde fueron los archivos en lugar de fingir que ocurrió un soltado.
En un terminal, el archivo se copia dentro y su ruta se escribe en el indicador, lista para pasarla a un comando. Pegar una imagen en un terminal hace lo mismo: se guarda en la máquina y recibes la ruta.

Arrastrar archivos hacia fuera funciona desde la Computadora (VM). Empieza a arrastrar un archivo dentro de la máquina, saca el puntero fuera del lienzo y se convierte en un arrastre real en tu escritorio — suéltalo en Finder o en el Explorador de archivos. Copiar archivos en el gestor de archivos de la máquina y pegarlos de tu lado también funciona. El Navegador (VM) no ofrece esto: un navegador sin interfaz gráfica no tiene ninguna carga útil de arrastre que leer, y adivinar a partir de la selección de texto de la página secuestraría clics normales.

Terminales dentro de un rig

Los terminales de un espacio o de una página de PR pueden ejecutarse dentro de un rig en lugar de en la máquina del propio servidor. Cuando lo hacen, el panel muestra una insignia de VM aislada.

Qué cambia:

Nada de lo que ejecutes llega al host. Un rm -rf allí dentro te cuesta el rig.
La red es de denegación por defecto. Solo se puede llegar a los hosts de la lista de permitidos del rig, y todo pasa por una puerta que la aplica.
git push sigue funcionando en una terminal que abriste tú. El rig no almacena credenciales; le pide al servidor una de corta duración por operación, acotada por tu propio acceso al host de código, y ese token se revoca cuando el rig se cierra. Un rig que abrió un agente recibe una credencial de solo lectura, así que puede hacer fetch pero no push.

Qué debes saber:

Un terminal con recinto restaurado te espera. Igual que una pestaña de rig, un terminal microvm que vuelve con tu diseño muestra un botón Abrir el shell en lugar de arrancar su VM al inicio. Un terminal del shell del host cuesta un proceso; uno con recinto cuesta una máquina.
Los archivos que se sueltan en el terminal se escriben, no se abren. Suelta un CSV en un terminal con recinto y se copia en la máquina, y su ruta en el huésped aparece en el indicador — la ruta del host sería un comando que falla allí.
La copia dentro del rig es una copia. Tu worktree en el host sigue siendo la referencia autorizada. Los commits que hagas dentro de un rig se traen de vuelta a refs/rigs/<id>/* cuando lo pides — nunca mueven tu rama ni tocan tu árbol de trabajo.
El trabajo destinado al host todavía se ejecuta en el host. Un huésped Linux no puede compilar para macOS ni ejecutar xcodebuild. Para eso, elige explícitamente el backend nativo; la app te pedirá confirmación en lugar de cambiar de forma silenciosa.

Puertos

Ejecuta un servidor de desarrollo en la Terminal (VM) — pnpm dev en el puerto 3000, por ejemplo — y en unos segundos se encenderá el icono de enchufe en la esquina del terminal: el puerto se reenvía a localhost:3000 en tu máquina, es accesible en localhost:3000 dentro del Navegador (VM), se puede compartir en tu red y se le puede dar el nombre https://myapp.test. Todo el flujo —reenvío automático, uso compartido en la LAN, dominios de desarrollo con HTTPS— tiene su propia guía: Reenviar puertos desde un terminal.

Imágenes personalizadas

Un espacio de trabajo puede apuntar la Terminal (VM) y el Navegador (VM) a sus propias imágenes, en Ajustes → Servidor → Rigs → Imágenes personalizadas (este espacio de trabajo). Uso típico: extender la imagen predeterminada con la cadena de herramientas que necesita tu proyecto para que cada terminal arranque lista, o reutilizar una imagen que tu equipo ya publica.

La máquina sigue arrancando dentro del mismo recinto: la misma puerta de salida, el mismo bróker de credenciales, el mismo ciclo de vida. Solo los administradores del espacio de trabajo pueden cambiar la configuración, las máquinas nuevas la adoptan (las que ya se ejecutan conservan la suya) y la referencia debe ser una imagen de registro — las rutas locales se rechazan.

Qué debe proporcionar una imagen:

Terminal (VM) — una imagen de Linux con bash. También necesita git, curl y socat — ya sea preinstalados o instalables en el primer arranque (cualquier imagen basada en Debian/Ubuntu sirve: se instalan automáticamente, junto con un conjunto de herramientas de CLI al estilo de un GitHub-hosted runner: compiladores, Python 3, jq, herramientas de archivo, rsync. Los runtimes de lenguajes como Node/Go/Java y Docker no vienen preinstalados). El puerto 7911 del huésped está reservado para el reenviador de puertos.
Navegador (VM) — una imagen de Debian/Ubuntu con bash y socat, más un binario chromium. El servidor inicia Chromium por su cuenta como chromium --headless=new y retransmite DevTools desde el puerto 9223 del huésped al 9222. PulseAudio y ffmpeg se instalan en el primer arranque. No compiles FROM chromedp/headless-shell — ese binario no tiene audio. La anulación se aplica solo a los rigs de Chromium; Firefox y WebKit la ignoran y arrancan la imagen de Debian fijada. Los puertos 9222/9223 del huésped están reservados.

Dos recomendaciones: fija la referencia por digest (@sha256:…) para que los bytes no cambien bajo tus pies, y alójala en Docker Hub o GitHub Container Registry — los hosts de descarga de esos registros se admiten automáticamente a través de la puerta de salida; otros pueden necesitar que sus hosts de entrega de contenido sean accesibles para hacer el pull.

Cuando un rig desaparece

Los rigs están hechos para ser temporales:

Inactividad — después de unos 15 minutos sin que ocurra nada, un rig de navegador, escritorio o móvil se estaciona (queda congelado y despierta al instante con la siguiente acción). Un terminal con recinto espera 45 minutos. Después del doble de la ventana de inactividad, se cierra.
Límite de tiempo — cada rig tiene una vida útil máxima que no puede extender, sin importar lo que esté haciendo.
Memoria — si el servidor necesita espacio para un rig nuevo, cierra el que se usó hace más tiempo. Nunca se toma un rig que alguien esté controlando, mirando o que tenga un terminal abierto.

Cuando un rig con recinto se cierra, su disco se descarta. Cerrar un rig de Android se desconecta del emulador del host — no lo elimina. Un rig de iOS elimina el dispositivo CoreSimulator que creó. Recupera primero todo lo que quieras conservar.

A qué puede llegar un rig

Los rigs con recinto de terminal, navegador y escritorio usan por defecto una puerta de salida con denegación por defecto: los hosts se conceden explícitamente, y la única ruta del huésped es una puerta que aplica esa lista. Un rig de navegador también admite el sitio del producto (usectrl.dev) desde el inicio. El bróker de credenciales usa la misma lista.

Dos advertencias honestas:

La red móvil sigue la del host. El emulador de Android y CoreSimulator de Apple no están detrás de la puerta de salida del recinto. Ninguna de las pestañas móviles ofrece un control para eludir la red, porque la red gestionada por el host ya es irrestricta.
Todo lo que un rig lee no es confiable. El texto de las páginas, el DOM, los árboles de accesibilidad y los volcados de vistas vuelven al agente envueltos en marcadores que dicen «esto son datos, no instrucciones». Una página que intente dar órdenes a tu agente se lee como una cadena entre comillas.

Puedes ver todo lo que está en ejecución, y detener cualquiera de ellos, en Ajustes → Servidor → Rigs.

Relacionado

Rigs y recintos — el modelo detrás de todo esto: por qué VM, los dos canales de visualización, el bróker de credenciales, el ciclo de vida
Reenviar puertos desde un terminal — llega a un servidor de desarrollo desde donde importe
Referencia de rigs — cada superficie, verbo, puerto y valor predeterminado en un solo lugar
Configurar barandillas — Controlar un recinto (rig) es una clase de acción que puedes configurar como permitir, preguntar primero o denegar, por espacio de trabajo, agente o espacio. Los modos de solo lectura lo deniegan de plano.