csansoon/hostel-platforms

Plataformas

Una plataforma es lo que un huésped solicita (hostel acquire <platform>). Hay dos tipos:

Tipo	Nombres	Qué máquinas lo sirven
Plataforma de SO	linux, macos, windows	Toda máquina con ese SO, automáticamente. Nunca se lista en platforms.
Plataforma de dispositivo	ios, android, o la propia	Máquinas que lo listan en platforms.

Herramientas como Node, Java o pnpm no son plataformas: los archivos mise del repositorio decláranlas (hostel-use), o la clave tools de la máquina (hostel-rooms).

hostel platforms              # para todos: espacios libres, cola, espera, dispositivos
hostel config platforms       # para administradores: NOMBRE, TIPO, MÁQUINAS, ORIGEN

Las plataformas predeterminadas

El binario incluye ios, android, macos y windows. linux es una plataforma de SO sin scripts.

Plataforma	Dispositivos	SO de la máquina	Qué necesita la máquina
ios	iphone-17-pro, ipad-pro-13 (máx. 2)	macOS	Xcode y un runtime de iOS Simulator, instalados por una persona. La plataforma requiere la etiqueta xcode-26.5. Variables de env opcionales de la máquina: HOSTEL_IOS_RUNTIME (por ejemplo 26.5), DEVELOPER_DIR.
android	pixel-9, pixel-tablet (máx. 2)	Linux o macOS	Java 17 o posterior: establecer tools = { java = "21" } en la máquina. Linux: /dev/kvm usable por el usuario de la sala (dar a la máquina una etiqueta como kvm), y los paquetes del emulador o sudo sin contraseña. La provisión descarga unos 5 GB (tiempo de espera 30 min). Variables env opcionales: HOSTEL_ANDROID_API (36), HOSTEL_ANDROID_TAG (google_apis), HOSTEL_ANDROID_PORT (5554).
macos	ninguno	macOS	Compilaciones sin cabeza: nada. Aplicaciones de escritorio: la etiqueta desktop, un inicio de sesión automático del usuario de la sala, una pantalla desbloqueada, Grabación de Pantalla para /usr/libexec/sshd-keygen-wrapper, y Modo Automatización sin contraseña (sudo automationmodetool enable-automationmode-without-authentication).
windows	ninguno	Windows	Servidor OpenSSH. Aplicaciones de escritorio: la etiqueta desktop y la tarea "Hostel desktop" en una sesión de escritorio iniciada y desbloqueada.
linux	ninguno	Linux	Un servidor SSH.

Lo que las plataformas proporcionan a los comandos:

• ios: simuladores nuevos y limpios para cada lease; SIMULATOR_UDID (primer dispositivo) y SIMULATOR_UDIDS.
• android: emuladores de solo lectura desde una instantánea limpia; ANDROID_SERIAL, ANDROID_SERIALS, ANDROID_HOME.
• Un lease que requiere desktop es exclusivo: toma toda la máquina.

Cada sala también recibe agent-device (tocar, escribir, leer la pantalla) y, en Windows, winapp. mise.agent_device = false (hostel config settings set) desactiva esto.

La preparación completa de Mac y Windows (usuarios, Inicio de Sesión Remoto, inicio de sesión automático, la tarea de escritorio) está en docs/static-room-setup.md.

Dispositivos y etiquetas

• --device <d> selecciona dispositivos de la plataforma (repítelo, hasta max_devices). Sin él, se aplican los devices del repositorio o el primer dispositivo de la plataforma.
• Las etiquetas son palabras libres en las máquinas (labels = [...]). Una máquina es candidata solo si tiene todas las etiquetas requeridas: los requires de la plataforma, los requires del repositorio en hostel.toml, y cada --require.
• Nombra las etiquetas según lo que tiene la máquina: xcode-26.5, desktop, kvm.
• Una plataforma o dispositivo desconocido, o una etiqueta que ninguna máquina tiene, falla de inmediato con el código de salida 69.

Tu propia plataforma

hostel config platforms new tvos ./tvos --os macos     # una carpeta de plantilla (--os linux|macos|windows)
# edita ./tvos/platform.toml y los scripts
hostel config platforms push ./tvos                    # verifica y guarda; el nombre es el de la carpeta
hostel config rooms set mac-mini platforms=ios,tvos     # permite que una máquina lo sirva

Cambiar una plataforma predeterminada:

hostel config platforms pull ios ./ios      # los archivos actuales en una nueva carpeta
hostel config platforms push ./ios          # guarda tu versión (origen: changed)
hostel config platforms reset ios           # vuelve a la versión de esta versión
hostel config platforms remove tvos         # rechazado mientras una máquina lo liste

push --name <n> guarda la carpeta con otro nombre. Un push se aplica de inmediato. Una sala libre cuya plataforma ha cambiado se aprovisiona de nuevo. Un push envía solo platform.toml, README.md y scripts.

platform.toml

description = "Simulador tvOS"
devices = ["apple-tv-4k"]          # el primero es el predeterminado (solo plataformas de dispositivo)
max_devices = 1                    # predeterminado 1
requires = ["xcode-26.5"]          # etiquetas que cada máquina debe tener
exclusive = false                  # true: el lease toma toda la sala
script_timeouts = { provision = "20m" }   # predeterminados: provision 20m, otros 3m

Una carpeta de plataforma de SO (linux, macos, windows) puede tener description, requires, exclusive y script_timeouts, pero no devices.

Scripts

Nombres de archivo: <paso>.<so>.sh para macos y linux, <paso>.<so>.ps1 para windows. El SO de la sala selecciona el archivo. Un nombre de script mal escrito es un error.

Paso	Cuándo	Se ejecuta en
provision	una vez por cada sala, y otra vez cuando los scripts cambian: instala y verifica lo que la plataforma necesita	hostel/
prepare	cada lease, antes de que esté listo: inicia los dispositivos, escribe sus hechos en device.env	slots/<slot>/
screenshot	hostel screenshot: $1 es la ruta PNG de salida, $2 el dispositivo	slots/<slot>/
reset	en la limpieza: detiene y elimina lo que prepare inició	slots/<slot>/
health	después de la limpieza, en la reparación, antes de que una sala caliente tome un lease: sale no cero si la sala no puede servir la plataforma	hostel/

Reglas:

• Cada paso es opcional, excepto prepare para una plataforma de dispositivo en cada SO de las máquinas que la listan.
• Cada paso debe ser seguro de ejecutar de nuevo.
• Un código de salida no cero es un fallo. Los fallos de provisión o preparación ponen la sala en estado "Broken" y devuelven el lease a la cola. Los últimos 4 KB de salida van al registro de eventos (hostel status <room>).
• El ayudante ejecuta /bin/sh <script> (no es necesario bit ejecutable) y detiene su grupo de procesos al alcanzar el tiempo de espera.
• Las tools a nivel de máquina se instalan antes de la provision, por lo que los scripts pueden usarlas.

Entorno de los scripts: HOSTEL_PLATFORM, HOSTEL_PLATFORM_DEVICES (todos los dispositivos de la plataforma), HOSTEL_SLOT, HOSTEL_SLOT_DIR, HOSTEL_WORK_DIR, HOSTEL_CACHE_DIR (conservado entre leases), HOSTEL_LEASE_ID, y para prepare, screenshot y reset: HOSTEL_DEVICES (los dispositivos del lease, separados por comas) y HOSTEL_EXCLUSIVE (1 para un lease de toda la sala). También las variables MISE_*, el env del proveedor, máquina y slot, y device.env (para screenshot y reset). Usa el env de la máquina para variar un script entre máquinas.

Las líneas de device.env (NOMBRE=valor) se agregan al entorno de cada comando del lease. Documenta los nombres que tu plataforma escribe.

Comprobación

hostel config platforms
hostel status mac-mini       # los eventos muestran la salida de provisión y errores