csansoon/hostel-platforms

Plataformas

Uma plataforma é o que um hóspede solicita (hostel acquire <plataforma>). Existem dois tipos:

Tipo	Nomes	Quais máquinas o servem
Plataforma de SO	linux, macos, windows	Toda máquina com esse SO, automaticamente. Nunca a liste em platforms.
Plataforma de dispositivo	ios, android, ou sua própria	Máquinas que a listam em platforms.

Ferramentas como Node, Java ou pnpm não são plataformas: os arquivos mise do repositório as declaram (hostel-use), ou a chave tools da máquina (hostel-rooms).

hostel platforms              # para todos: slots livres, fila, espera, dispositivos
hostel config platforms       # para administradores: NOME, TIPO, MÁQUINAS, ORIGEM

As plataformas padrão

O binário possui ios, android, macos e windows embutidos. linux é uma plataforma de SO sem scripts.

Plataforma	Dispositivos	SO da máquina	O que a máquina precisa
ios	iphone-17-pro, ipad-pro-13 (máx. 2)	macOS	Xcode e um runtime do Simulador iOS, instalados por uma pessoa. A plataforma requer o rótulo xcode-26.5. env opcional da máquina: HOSTEL_IOS_RUNTIME (por exemplo 26.5), DEVELOPER_DIR.
android	pixel-9, pixel-tablet (máx. 2)	Linux ou macOS	Java 17 ou posterior: defina tools = { java = "21" } na máquina. Linux: /dev/kvm utilizável pelo usuário da sala (dê à máquina um rótulo como kvm), e os pacotes do emulador ou sudo sem senha. O provisionamento baixa cerca de 5 GB (timeout de 30 min). env opcional: HOSTEL_ANDROID_API (36), HOSTEL_ANDROID_TAG (google_apis), HOSTEL_ANDROID_PORT (5554).
macos	nenhum	macOS	Builds headless: nada. Aplicativos de desktop: o rótulo desktop, um login automático do usuário da sala, uma tela desbloqueada, Gravação de Tela para /usr/libexec/sshd-keygen-wrapper e Modo Automação sem senha (sudo automationmodetool enable-automationmode-without-authentication).
windows	nenhum	Windows	Servidor OpenSSH. Aplicativos de desktop: o rótulo desktop e a tarefa "Hostel desktop" em uma sessão de desktop conectada e desbloqueada.
linux	nenhum	Linux	Um servidor SSH.

O que as plataformas fornecem aos comandos:

• ios: simuladores novos e limpos para cada locação; SIMULATOR_UDID (primeiro dispositivo) e SIMULATOR_UDIDS.
• android: emuladores somente leitura a partir de um snapshot limpo; ANDROID_SERIAL, ANDROID_SERIALS, ANDROID_HOME.
• Uma locação que requer desktop é exclusiva: ela ocupa a máquina inteira.

Cada sala também recebe agent-device (tocar, digitar, ler a tela) e, no Windows, winapp. mise.agent_device = false (hostel config settings set) desativa isso.

A preparação completa do Mac e Windows (usuários, Login Remoto, login automático, a tarefa de desktop) está em docs/static-room-setup.md.

Dispositivos e rótulos

• --device <d> seleciona dispositivos da plataforma (repita-o, até max_devices). Sem ele, os devices do repositório ou o primeiro dispositivo da plataforma são aplicados.
• Rótulos são palavras livres nas máquinas (labels = [...]). Uma máquina é candidata somente se possuir todos os rótulos exigidos: o requires da plataforma, o requires do repositório em hostel.toml e cada --require.
• Nomeie os rótulos conforme o que a máquina possui: xcode-26.5, desktop, kvm.
• Uma plataforma ou dispositivo desconhecido, ou um rótulo que nenhuma máquina possui, falha imediatamente com código de saída 69.

Sua própria plataforma

hostel config platforms new tvos ./tvos --os macos     # uma pasta de modelo (--os linux|macos|windows)
# edite ./tvos/platform.toml e os scripts
hostel config platforms push ./tvos                    # verifica e salva; o nome é o nome da pasta
hostel config rooms set mac-mini platforms=ios,tvos     # permite que uma máquina a sirva

Altere uma plataforma padrão:

hostel config platforms pull ios ./ios      # os arquivos atuais em uma nova pasta
hostel config platforms push ./ios          # salva sua versão (origem: changed)
hostel config platforms reset ios           # volta para a versão desta release
hostel config platforms remove tvos         # recusado enquanto uma máquina a listar

push --name <n> salva a pasta com outro nome. Um push é aplicado imediatamente. Uma sala livre cuja plataforma mudou provisiona novamente. Um push envia apenas platform.toml, README.md e scripts.

platform.toml

description = "Simulador tvOS"
devices = ["apple-tv-4k"]          # o primeiro é o padrão (apenas plataformas de dispositivo)
max_devices = 1                    # padrão 1
requires = ["xcode-26.5"]          # rótulos que cada máquina deve ter
exclusive = false                  # true: a locação ocupa a sala inteira
script_timeouts = { provision = "20m" }   # padrões: provision 20m, outros 3m

Uma pasta de plataforma de SO (linux, macos, windows) pode ter description, requires, exclusive e script_timeouts, mas não devices.

Scripts

Nomes de arquivo: <etapa>.<so>.sh para macos e linux, <etapa>.<so>.ps1 para windows. O SO da sala seleciona o arquivo. Um nome de script incorreto é um erro.

Etapa	Quando	Executa em
provision	uma vez para cada sala, e novamente quando os scripts mudam: instala e verifica o que a plataforma precisa	hostel/
prepare	a cada locação, antes de estar pronta: inicia os dispositivos, escreve seus fatos em device.env	slots/<slot>/
screenshot	hostel screenshot: $1 é o caminho PNG de saída, $2 o dispositivo	slots/<slot>/
reset	na limpeza: para e exclui o que prepare iniciou	slots/<slot>/
health	após a limpeza, no reparo, antes de uma sala aquecida aceitar uma locação: sair diferente de zero se a sala não puder servir a plataforma	hostel/

Regras:

• Cada etapa é opcional, exceto prepare para uma plataforma de dispositivo em cada SO das máquinas que a listam.
• Cada etapa deve ser segura para executar novamente.
• Um código de saída diferente de zero é uma falha. Falhas no provisionamento ou preparação tornam a sala Quebrada e enviam a locação de volta à fila. Os últimos 4 KB de saída vão para o log de eventos (hostel status <room>).
• O helper executa /bin/sh <script> (nenhum bit de execução necessário) e interrompe seu grupo de processos no timeout.
• As tools no nível da máquina são instaladas antes do provision, para que os scripts possam usá-las.

Ambiente dos scripts: HOSTEL_PLATFORM, HOSTEL_PLATFORM_DEVICES (todos os dispositivos da plataforma), HOSTEL_SLOT, HOSTEL_SLOT_DIR, HOSTEL_WORK_DIR, HOSTEL_CACHE_DIR (mantido entre locações), HOSTEL_LEASE_ID e, para prepare, screenshot e reset: HOSTEL_DEVICES (os dispositivos da locação, separados por vírgula) e HOSTEL_EXCLUSIVE (1 para uma locação de sala inteira). Também as variáveis MISE_*, o provedor, máquina e slot env, e device.env (para screenshot e reset). Use env da máquina para variar um script entre máquinas.

As linhas de device.env (NOME=valor) vão para o ambiente de cada comando da locação. Documente os nomes que sua plataforma escreve.

Verificação

hostel config platforms
hostel status mac-mini       # os eventos mostram a saída e erros do provisionamento