csansoon/hostel-rooms

Añadir y gestionar habitaciones

Las máquinas están en el documento de configuración del servidor. Debes ser un administrador (hostel-users). Cada cambio se aplica al instante.

hostel config providers        # NOMBRE, TIPO, MÁQUINAS
hostel config rooms            # MÁQUINA, TIPO, OS, PLATAFORMAS, ETIQUETAS, HABITACIONES
hostel config edit             # cambiar el TOML en $EDITOR

Una máquina se nombra <proveedor>/<máquina>, o solo <máquina> cuando el nombre es único. Los nombres cumplen ^[a-z][a-z0-9-]*$. Los requisitos de plataforma (Xcode, Android SDK, KVM, escritorio) están en hostel-platforms.

Una máquina detrás de NAT (se une al servidor)

Úsalo para la mayoría de máquinas propias: un Mac mini en casa, un PC con Windows, un Linux box. La máquina mantiene una conexión saliente hacia el servidor. No necesita SSH entrante desde internet.

1. En tu computadora, genera un código de máquina (24 horas, funciona una vez):

   hostel config rooms add mac-mini --platform ios --label xcode-26.5 --label desktop
   hostel config rooms add win-pc --label desktop
   

   --platform y --label pueden repetirse. --provider selecciona el proveedor estático (por defecto home; el servidor lo añade si falta). En la aplicación: Recepción › Añadir una habitación.

2. Ejecuta el comando impreso en la nueva máquina como administrador: sudo en macOS y Linux, un PowerShell de administrador en Windows. El comando descarga hostel desde tu servidor y ejecuta hostel machine join <código>.

hostel machine join crea el usuario hostel (sin derechos de administrador), instala la clave del servidor para él, añade la máquina a la configuración (connect = true, SO detectado de la máquina) e instala el servicio que ejecuta hostel machine connect:

SO	Servicio	Log
Linux	unidad systemd hostel-machine-connect.service (usuario hostel-connect)	journalctl -u hostel-machine-connect
macOS	LaunchDaemon so.hostel.machine-connect	/var/log/hostel-machine-connect.log
Windows	tarea programada Hostel machine connect (LOCAL SERVICE)	C:\ProgramData\hostel\machine-connect.log

El token está en /etc/hostel o C:\ProgramData\hostel; el usuario de la habitación no puede leerlo. Si algún paso falla, arréglalo y vuelve a ejecutar el mismo comando: continúa. --no-service omite el servicio e imprime el comando hostel machine connect para ejecutarlo tú mismo (--server <url> --token-file <archivo> [--server-key k] [--ssh 127.0.0.1:22]).

3. Realiza los pasos que join imprime y que solo una persona puede hacer:

   • macOS: Ajustes del Sistema › General › Compartir › Inicio de sesión remoto activado, para hostel; Xcode para iOS; para desktop, inicio de sesión automático de hostel y sin contraseña tras el salvapantallas.
   • Windows: OpenSSH Server ejecutándose y con inicio automático (Get-Service sshd); para desktop, la tarea "Hostel desktop".
   • Linux: el servidor SSH escucha en el puerto 22 y permite inicio de sesión por clave para hostel.

4. Verifica: hostel status muestra la habitación en menos de un minuto.

Una máquina estática a la que el servidor llega por SSH

Úsalo cuando el servidor pueda abrir TCP hacia la máquina (misma LAN o VPN). En la máquina, crea un usuario estándar hostel con la clave SSH del servidor. La clave es la salida de hostel admin pubkey (en la computadora de un administrador), y hostel server init también la imprimió ("clave pública del servidor"). En Linux:

sudo useradd -m -s /bin/bash hostel
sudo install -d -m 700 -o hostel -g hostel ~hostel/.ssh
echo 'ssh-ed25519 AAAA... hostel-server' | sudo tee ~hostel/.ssh/authorized_keys
sudo chown hostel:hostel ~hostel/.ssh/authorized_keys && sudo chmod 600 ~hostel/.ssh/authorized_keys

Permite el inicio de sesión por clave SSH para ese usuario. Mantén la redirección TCP activada en sshd (el valor por defecto de OpenSSH; los túneles lo necesitan). Luego añádelo con hostel config edit:

[providers.home]
kind = "static"

[providers.home.machines.mac-mini]
address = "[email protected]"    # usuario@host[:puerto]; usuario por defecto hostel, puerto 22
os = "macos"                         # requerido: linux, macos o windows
platforms = ["ios", "android"]       # plataformas de dispositivo; la plataforma del SO es automática
labels = ["xcode-26.5", "desktop"]
tools = { java = "21" }              # herramientas mise a nivel de máquina
env = { HOSTEL_IOS_RUNTIME = "26.5" }
# slots = [{ name = "a" }, { name = "b" }]   # dos concesiones a la vez (por defecto: un slot "a")

• slots: cada slot n obtiene los puertos 7500 + 10n a 7509 + 10n para túneles. Un slot puede establecer ports, env y su propio user del SO.
• env y tools en el proveedor se aplican a todas sus máquinas; las claves de máquina reemplazan claves con el mismo nombre.
• El servidor fija la clave de host SSH de la máquina en la primera conexión.
• Windows manualmente: docs/static-room-setup.md, sección "Windows" (el usuario, y las reglas de acceso de authorized_keys que OpenSSH requiere).
• Para una dirección pública: permite SSH entrante solo desde el servidor, o usa connect = true (el flujo de join) y cierra el SSH entrante.

Cambia una clave sin el editor (platforms y labels son listas separadas por comas):

hostel config rooms set mac-mini labels=xcode-26.5,desktop
hostel config rooms set mac-mini platforms=ios

Namespace (máquinas en la nube bajo demanda)

Namespace (namespace.so) crea habitaciones cuando una concesión las necesita: un devbox para macOS (o Linux), una instancia para Linux. Instala ambas CLI como el usuario del servidor y pon ~/.local/bin en el PATH del servicio:

curl -fsSL https://get.namespace.so/cloud/install.sh | sh        # nsc
curl -fsSL get.namespace.so/devbox/install.sh | bash             # devbox
sudo mkdir -p /etc/systemd/system/hostel.service.d
printf '[Service]\nEnvironment=PATH=%s/.local/bin:/usr/local/bin:/usr/bin:/bin\n' "$HOME" \
  | sudo tee /etc/systemd/system/hostel.service.d/path.conf
sudo systemctl daemon-reload && sudo systemctl restart hostel

Desde tu computadora (imprime una URL; ábrela y selecciona el espacio de trabajo):

hostel config providers login namespace        # --cli devbox o --cli nsc para una sola CLI
hostel config providers add ns --kind namespace

Luego añade plantillas de máquina con hostel config edit:

[providers.ns]
kind = "namespace"
max_rooms = 3                        # todas las máquinas de este proveedor juntas
# limits = [{ machines = ["mac"], max_rooms = 1 }]

[providers.ns.machines.mac]
spec = { product = "devbox", platform = "macos", size = "m", image = "tahoe-slim" }
platforms = ["ios"]
labels = ["xcode-26.5", "desktop"]
env = { DEVELOPER_DIR = "/Applications/Xcode_26.5.app/Contents/Developer", HOSTEL_IOS_RUNTIME = "26.5" }
max_rooms = 1
max_lifetime = "3h"                  # requerido para un devbox: la duración máxima del plan

[providers.ns.machines.linux]
spec = { product = "instance", machine_type = "linux/amd64:8x16" }   # opcional: image (por defecto ubuntu:24.04)
platforms = ["android"]
labels = ["kvm"]
tools = { java = "21" }
max_rooms = 2

Costo y límites (consulta el plan actual en Namespace):

• Hostel actúa solo sobre habitaciones con el prefijo de su nombre hostel-<server_id>-.
• Un devbox es efímero: se elimina tras unos 15 minutos inactivo, y al alcanzar su max_lifetime. Una instancia tiene una fecha límite fija que el servidor extiende.
• Un devbox macOS cuesta mucho más por minuto que uno Linux.
• Los límites del plan se aplican a todas las concesiones juntas (comparten un mismo inicio de sesión). En el plan Developer: un devbox por usuario, máximo 3 h, sin Windows. Un error de "límite alcanzado" marca la máquina como llena durante limit_retry (2 minutos).
• Solo se admiten tipos de instancia linux. Android en Namespace usa Linux.
• Un inicio de sesión dura días. Cuando termina, las llamadas al proveedor fallan: inicia sesión de nuevo.

El proveedor externo (tu propio comando)

kind = "external" ejecuta tu comando para cada operación (capabilities, provision, resume, stop, extend, destroy, list, access) con JSON en stdin y stdout. docs/design.md, sección 7, "Contrato del proveedor externo", tiene el contrato completo. El repositorio test/fakeprovider (contenedores Docker) es una herramienta de prueba, no un proveedor soportado.

[providers.docker]
kind = "external"
command = ["/usr/local/bin/my-provider"]
command_env = { DOCKER_HOST = "unix:///var/run/docker.sock" }
timeouts = { provision = "5m", default = "1m" }

[providers.docker.machines.small]
os = "linux"                         # requerido
spec = { image = "debian:13" }       # se pasa a tu comando tal cual
max_rooms = 2

Límites y habitaciones calientes (máquinas bajo demanda)

Clave	Dónde	Por defecto
max_rooms	proveedor (todas sus máquinas) / máquina	ninguno / 1
limits	proveedor: [{ machines = [...], max_rooms = N }]	[]
max_lease	proveedor, máquina	2h
max_lifetime	proveedor, máquina	ninguno
warm_running	proveedor, máquina: mantener una habitación libre funcionando este tiempo	5m
warm_stopped	proveedor, máquina: mantener una habitación detenida este tiempo	24h

Drenar, reparar, eliminar, destruir

hostel config rooms drain mac-mini        # sin nuevas concesiones; las concesiones actuales continúan
hostel config rooms undrain mac-mini
hostel config rooms repair mac-mini       # comprobar de nuevo una habitación rota
hostel config rooms repair mac-mini --accept-host-key
hostel config rooms destroy ns/mac        # una habitación bajo demanda sin concesión (dar el nombre de la habitación si hay varias)
hostel config rooms remove mac-mini       # eliminar la máquina; sus tokens de habitación se revocan
hostel config providers remove ns         # solo sin habitaciones bajo demanda

• Una máquina con una concesión activa no puede eliminarse: drénala y espera.
• Una máquina bajo demanda no puede eliminarse mientras tenga habitaciones: destrúyelas primero.
• hostel admin room drain|undrain|repair|destroy <nombre o ID de habitación> hace lo mismo por habitación.

Máquinas desconectadas

Cada intervals.presence (30 s) el servidor comprueba cada habitación estática inactiva. Una habitación que no responde pasa a Desconectada y no recibe concesiones. Cuando vuelve a responder, el servidor la prepara de nuevo automáticamente. No se necesita ningún comando. hostel status imprime offline (visto por última vez ...). Consulta hostel-troubleshoot.