csansoon/hostel-rooms

添加和管理房间

机器位于服务器的配置文档中。您必须是管理员（hostel-users）。每次更改都会立即生效。

hostel config providers        # NAME, KIND, MACHINES
hostel config rooms            # MACHINE, KIND, OS, PLATFORMS, LABELS, ROOMS
hostel config edit             # 在 $EDITOR 中更改 TOML

机器命名为 <provider>/<machine>，或者当名称唯一时仅命名 <machine>。名称匹配 ^[a-z][a-z0-9-]*$。平台要求（Xcode、Android SDK、KVM、桌面）在 hostel-platforms 中。

位于 NAT 后的机器（加入服务器）

用于大多数自有机器：家中的 Mac mini、Windows PC、Linux 主机。机器保持与服务器的出站连接。它不需要来自互联网的入站 SSH。

1. 在您的计算机上，生成一个机器代码（有效期 24 小时，仅使用一次）：

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

   --platform 和 --label 可以重复。--provider 选择静态提供者（默认为 home；如缺失，服务器会添加它）。在应用程序中：前台 › 添加一个房间。

2. 在新机器上以管理员身份运行打印的命令：macOS 和 Linux 上使用 sudo，Windows 上使用管理员 PowerShell。该命令从您的服务器下载 hostel 并运行 hostel machine join <code>。

hostel machine join 会创建用户 hostel（无管理员权限），安装服务器的密钥，将机器添加到配置中（connect = true，OS 来自机器），并安装运行 hostel machine connect 的服务：

操作系统	服务	日志
Linux	systemd 单元 hostel-machine-connect.service（用户 hostel-connect）	journalctl -u hostel-machine-connect
macOS	LaunchDaemon so.hostel.machine-connect	/var/log/hostel-machine-connect.log
Windows	计划任务 Hostel machine connect（LOCAL SERVICE）	C:\ProgramData\hostel\machine-connect.log

令牌位于 /etc/hostel 或 C:\ProgramData\hostel；房间用户无法读取它。如果某一步失败，请修复后重新运行相同的命令：它会继续执行。--no-service 跳过服务，并打印需要您手动运行的 hostel machine connect 命令（--server <url> --token-file <file> [--server-key k] [--ssh 127.0.0.1:22]）。

3. 执行 join 打印的且仅能由人完成的步骤：

   • macOS：系统设置 › 通用 › 共享 › 远程登录开启，针对 hostel；iOS 需要 Xcode；对于 desktop，需要自动登录 hostel 且屏幕保护程序后无需密码。
   • Windows：OpenSSH Server 运行并自动启动（Get-Service sshd）；对于 desktop，需要“Hostel desktop”任务。
   • Linux：SSH 服务器在端口 22 上运行，并允许 hostel 用户的密钥登录。

4. 检查：hostel status 会在一分钟内显示该房间。

服务器通过 SSH 可达的静态机器

当服务器可以打开到机器的 TCP 连接（同一局域网或 VPN）时使用此方式。在机器上，创建一个标准用户 hostel，并安装服务器的 SSH 密钥。该密钥是 hostel admin pubkey 的输出（在管理员计算机上），hostel server init 也会打印它（“服务器公钥”）。在 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

允许该用户的 SSH 密钥登录。保持 sshd 中的 TCP 转发开启（OpenSSH 默认值；隧道需要它）。然后通过 hostel config edit 添加：

[providers.home]
kind = "static"

[providers.home.machines.mac-mini]
address = "[email protected]"    # user@host[:port]；默认用户 hostel，端口 22
os = "macos"                         # 必填：linux、macos 或 windows
platforms = ["ios", "android"]       # 设备平台；操作系统平台是自动的
labels = ["xcode-26.5", "desktop"]
tools = { java = "21" }              # 机器级别的 mise 工具
env = { HOSTEL_IOS_RUNTIME = "26.5" }
# slots = [{ name = "a" }, { name = "b" }]   # 一次两个租约（默认：一个插槽 "a"）

• slots：每个插槽 n 获得用于隧道的端口 7500 + 10n 到 7509 + 10n。一个插槽可以设置 ports、env 和其自己的操作系统 user。
• env 和 tools 在提供者级别应用于其所有机器；机器级别的键会替换相同名称的键。
• 服务器在首次连接时固定机器的 SSH 主机密钥。
• Windows 手动设置：docs/static-room-setup.md，“Windows”部分（用户以及 OpenSSH 要求的 authorized_keys 访问规则）。
• 对于公共地址：仅允许来自服务器的入站 SSH，或使用 connect = true（加入流程）并关闭入站 SSH。

不使用编辑器更改一个键（platforms 和 labels 是逗号列表）：

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

Namespace（按需云机器）

Namespace (namespace.so) 在需要租约时创建房间：macOS（或 Linux）的 devbox，Linux 的 instance。将两个 CLI 安装为服务器用户，并将 ~/.local/bin 加入服务的 PATH：

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

从您的计算机（它会打印一个 URL；打开它并选择工作区）：

hostel config providers login namespace        # --cli devbox 或 --cli nsc 用于单个 CLI
hostel config providers add ns --kind namespace

然后通过 hostel config edit 添加机器模板：

[providers.ns]
kind = "namespace"
max_rooms = 3                        # 此提供者的所有机器总共
# 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"                  # devbox 必填：计划的最大持续时间

[providers.ns.machines.linux]
spec = { product = "instance", machine_type = "linux/amd64:8x16" }   # 可选：image（默认 ubuntu:24.04）
platforms = ["android"]
labels = ["kvm"]
tools = { java = "21" }
max_rooms = 2

成本和限制（查看 Namespace 的当前计划）：

• Hostel 仅对名称前缀为 hostel-<server_id>- 的房间进行操作。
• Devbox 是临时的：空闲约 15 分钟后会被删除，并在其 max_lifetime 结束时被删除。Instance 有一个固定的截止时间，服务器会延长。
• macOS devbox 每分钟费用远高于 Linux devbox。
• 计划限制适用于所有租约（它们共享一个登录）。在开发者计划中：每个用户一个 devbox，最长 3 小时，无 Windows。“达到限制”错误会将机器标记为已满，持续 limit_retry（2 分钟）。
• 仅支持 linux 实例类型。Namespace 上的 Android 使用 Linux。
• 登录持续数天。当它结束时，提供者调用会失败：请重新登录。

外部提供者（您自己的命令）

kind = "external" 对每个操作（capabilities、provision、resume、stop、extend、destroy、list、access）运行您的命令，并通过 stdin 和 stdout 传递 JSON。docs/design.md 第 7 节“外部提供者合约”包含完整合约。仓库中的 test/fakeprovider（Docker 容器）是一个测试工具，不是受支持的提供者。

[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"                         # 必填
spec = { image = "debian:13" }       # 按原样传递给您的命令
max_rooms = 2

限制和预热房间（按需机器）

键	位置	默认值
max_rooms	提供者（其所有机器）/ 机器	无 / 1
limits	提供者：[{ machines = [...], max_rooms = N }]	[]
max_lease	提供者，机器	2h
max_lifetime	提供者，机器	无
warm_running	提供者，机器：保持一个空闲房间运行这么长时间	5m
warm_stopped	提供者，机器：保持一个停止的房间这么长时间	24h

腾空、修复、移除、销毁

hostel config rooms drain mac-mini        # 无新租约；当前租约继续
hostel config rooms undrain mac-mini
hostel config rooms repair mac-mini       # 再次检查故障房间
hostel config rooms repair mac-mini --accept-host-key
hostel config rooms destroy ns/mac        # 一个没有租约的按需房间（如有多个，给出房间名称）
hostel config rooms remove mac-mini       # 移除机器；其房间令牌被吊销
hostel config providers remove ns         # 仅在没有按需房间时

• 具有活动租约的机器无法移除：将其腾空并等待。
• 按需机器在有房间时无法移除：先销毁它们。
• hostel admin room drain|undrain|repair|destroy <room name or ID> 按房间执行相同操作。

离线机器

每 intervals.presence（30 秒）服务器检查每个空闲的静态房间。一个没有响应的房间会变为 Offline 状态且不接受租约。当它再次响应时，服务器会自动重新准备它。无需任何命令。hostel status 会打印 offline (last seen ...)。请参阅 hostel-troubleshoot。