csansoon/hostel-rooms

Räume hinzufügen und verwalten

Maschinen befinden sich im Konfigurationsdokument auf dem Server. Du musst ein Administrator sein (hostel-users). Jede Änderung wird sofort wirksam.

hostel config providers        # NAME, ART, MASCHINEN
hostel config rooms            # MASCHINE, ART, BETRIEBSSYSTEM, PLATTFORMEN, LABELS, RÄUME
hostel config edit             # TOML in $EDITOR ändern

Eine Maschine wird als <provider>/<machine> benannt, oder nur <machine> wenn der Name eindeutig ist. Namen entsprechen ^[a-z][a-z0-9-]*$. Plattformanforderungen (Xcode, Android SDK, KVM, Desktop) sind in hostel-platforms.

Eine Maschine hinter NAT (sie tritt dem Server bei)

Verwende dies für die meisten eigenen Maschinen: einen Mac mini zu Hause, einen Windows-PC, eine Linux-Box. Die Maschine hält eine ausgehende Verbindung zum Server aufrecht. Sie benötigt kein eingehendes SSH aus dem Internet.

1. Erstelle auf deinem Computer einen Maschinencode (24 Stunden gültig, einmal verwendbar):

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

   --platform und --label können wiederholt werden. --provider wählt den statischen Anbieter aus (Standard home; der Server fügt ihn hinzu, falls er fehlt). In der App: Rezeption › Einen Raum hinzufügen.

2. Führe den ausgegebenen Befehl auf der neuen Maschine als Administrator aus: sudo auf macOS und Linux, eine Administrator-PowerShell auf Windows. Der Befehl lädt hostel von deinem Server herunter und führt hostel machine join <code> aus.

hostel machine join erstellt den Benutzer hostel (keine Administratorrechte), installiert den Schlüssel des Servers für ihn, fügt die Maschine zur Konfiguration hinzu (connect = true, Betriebssystem von der Maschine) und installiert den Dienst, der hostel machine connect ausführt:

Betriebssystem	Dienst	Protokoll
Linux	systemd-Einheit hostel-machine-connect.service (Benutzer hostel-connect)	journalctl -u hostel-machine-connect
macOS	LaunchDaemon so.hostel.machine-connect	/var/log/hostel-machine-connect.log
Windows	geplanter Task Hostel machine connect (LOCAL SERVICE)	C:\ProgramData\hostel\machine-connect.log

Das Token befindet sich in /etc/hostel oder C:\ProgramData\hostel; der Raumbenutzer kann es nicht lesen. Wenn ein Schritt fehlschlägt, behebe ihn und führe denselben Befehl erneut aus: er wird fortgesetzt. --no-service überspringt den Dienst und gibt den Befehl hostel machine connect aus, den du selbst ausführen kannst (--server <url> --token-file <file> [--server-key k] [--ssh 127.0.0.1:22]).

3. Führe die Schritte aus, die join ausgibt und die nur eine Person durchführen kann:

   • macOS: Systemeinstellungen › Allgemein › Teilen › Remote-Anmeldung aktivieren, für hostel; Xcode für iOS; für desktop, automatische Anmeldung von hostel und kein Passwort nach dem Bildschirmschoner.
   • Windows: OpenSSH-Server läuft und startet automatisch (Get-Service sshd); für desktop, die Aufgabe „Hostel desktop“.
   • Linux: der SSH-Server läuft auf Port 22 und erlaubt Schlüsselanmeldung für hostel.

4. Überprüfen: hostel status zeigt den Raum innerhalb einer Minute an.

Eine statische Maschine, die der Server per SSH erreicht

Verwende dies, wenn der Server TCP zur Maschine öffnen kann (gleiches LAN oder VPN). Erstelle auf der Maschine einen Standardbenutzer hostel mit dem SSH-Schlüssel des Servers. Der Schlüssel ist die Ausgabe von hostel admin pubkey (auf dem Computer eines Administrators), und hostel server init hat ihn ebenfalls ausgegeben („öffentlicher Schlüssel des Servers“). Unter 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

Erlaube die SSH-Schlüsselanmeldung für diesen Benutzer. Lasse die TCP- Weiterleitung in sshd aktiviert (OpenSSH-Standard; Tunnel benötigen sie). Füge sie dann mit hostel config edit hinzu:

[providers.home]
kind = "static"

[providers.home.machines.mac-mini]
address = "[email protected]"    # benutzer@host[:port]; Standardbenutzer hostel, Port 22
os = "macos"                         # erforderlich: linux, macos oder windows
platforms = ["ios", "android"]       # Geräteplattformen; die Betriebssystemplattform ist automatisch
labels = ["xcode-26.5", "desktop"]
tools = { java = "21" }              # Mise-Tools auf Maschinenebene
env = { HOSTEL_IOS_RUNTIME = "26.5" }
# slots = [{ name = "a" }, { name = "b" }]   # zwei Leases gleichzeitig (Standard: ein Slot "a")

• slots: jeder Slot n erhält die Ports 7500 + 10n bis 7509 + 10n für Tunnel. Ein Slot kann ports, env und seinen eigenen OS-user setzen.
• env und tools auf dem Anbieter gelten für alle seine Maschinen; Maschinenschlüssel ersetzen Schlüssel mit demselben Namen.
• Der Server fixiert den SSH-Hostschlüssel der Maschine bei der ersten Verbindung.
• Windows von Hand: docs/static-room-setup.md, Abschnitt „Windows“ (der Benutzer und die Zugriffsregeln von authorized_keys, die OpenSSH erfordert).
• Für eine öffentliche Adresse: eingehendes SSH nur vom Server erlauben oder connect = true verwenden (den Join-Flow) und eingehendes SSH schließen.

Ändere einen Schlüssel ohne Editor (platforms und labels sind Komma-getrennte Listen):

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

Namespace (On-Demand-Cloud-Maschinen)

Namespace (namespace.so) erstellt Räume, wenn ein Lease sie benötigt: eine Devbox für macOS (oder Linux), eine Instance für Linux. Installiere beide CLIs als Benutzer des Servers und füge ~/.local/bin zum PATH des Dienstes hinzu:

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

Von deinem Computer aus (es wird eine URL ausgegeben; öffne sie und wähle den Arbeitsbereich):

hostel config providers login namespace        # --cli devbox oder --cli nsc für eine CLI
hostel config providers add ns --kind namespace

Füge dann Maschinenvorlagen mit hostel config edit hinzu:

[providers.ns]
kind = "namespace"
max_rooms = 3                        # alle Maschinen dieses Anbieters zusammen
# 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"                  # erforderlich für eine Devbox: die maximale Dauer des Plans

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

Kosten und Grenzen (überprüfe den aktuellen Plan bei Namespace):

• Hostel handelt nur bei Räumen mit seinem Namenspräfix hostel-<server_id>-.
• Eine Devbox ist flüchtig: sie wird nach etwa 15 Minuten Inaktivität und bei ihrer max_lifetime gelöscht. Eine Instance hat eine feste Frist, die der Server verlängert.
• Eine macOS-Devbox kostet pro Minute viel mehr als eine Linux-Devbox.
• Plangrenzen gelten für alle Leases zusammen (sie teilen sich eine Anmeldung). Im Entwicklerplan: eine Devbox pro Benutzer, maximal 3 Stunden, kein Windows. Ein Fehler „Grenze erreicht“ markiert die Maschine für limit_retry (2 Minuten) als voll.
• Es werden nur linux-Instance-Typen unterstützt. Android auf Namespace verwendet Linux.
• Eine Anmeldung hält Tage. Wenn sie endet, schlagen Anbieteraufrufe fehl: melde dich erneut an.

Der externe Anbieter (dein eigener Befehl)

kind = "external" führt deinen Befehl für jeden Vorgang aus (capabilities, provision, resume, stop, extend, destroy, list, access) mit JSON auf stdin und stdout. docs/design.md, Abschnitt 7, „Externer Anbietervertrag“, enthält den vollständigen Vertrag. Das test/fakeprovider-Repository (Docker- Container) ist ein Testwerkzeug, kein unterstützter Anbieter.

[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"                         # erforderlich
spec = { image = "debian:13" }       # wird unverändert an deinen Befehl übergeben
max_rooms = 2

Grenzen und warme Räume (On-Demand-Maschinen)

Schlüssel	Wo	Standard
max_rooms	Anbieter (alle seine Maschinen) / Maschine	keine / 1
limits	Anbieter: [{ machines = [...], max_rooms = N }]	[]
max_lease	Anbieter, Maschine	2h
max_lifetime	Anbieter, Maschine	keine
warm_running	Anbieter, Maschine: einen freien Raum so lange laufen lassen	5m
warm_stopped	Anbieter, Maschine: einen gestoppten Raum so lange behalten	24h

Drainen, Reparieren, Entfernen, Zerstören

hostel config rooms drain mac-mini        # keine neuen Leases; aktuelle Leases laufen weiter
hostel config rooms undrain mac-mini
hostel config rooms repair mac-mini       # einen defekten Raum erneut prüfen
hostel config rooms repair mac-mini --accept-host-key
hostel config rooms destroy ns/mac        # ein On-Demand-Raum ohne Lease (Raumnamen angeben, wenn mehrere)
hostel config rooms remove mac-mini       # die Maschine entfernen; ihre Raum-Tokens werden widerrufen
hostel config providers remove ns         # nur ohne On-Demand-Räume

• Eine Maschine mit einem aktiven Lease kann nicht entfernt werden: draine sie und warte.
• Eine On-Demand-Maschine kann nicht entfernt werden, während sie Räume hat: zerstöre sie zuerst.
• hostel admin room drain|undrain|repair|destroy <Raumname oder ID> macht dasselbe pro Raum.

Offline-Maschinen

Alle intervals.presence (30 s) überprüft der Server jeden freien statischen Raum. Ein Raum, der nicht antwortet, wird Offline und nimmt kein Lease an. Wenn er wieder antwortet, bereitet der Server ihn selbstständig wieder vor. Es ist kein Befehl erforderlich. hostel status gibt offline (zuletzt gesehen ...) aus. Siehe hostel-troubleshoot.