방 추가 및 관리
머신은 서버의 설정 문서에 있습니다. 관리자(hostel-users)여야 합니다. 각 변경 사항은 즉시 적용됩니다.
hostel config providers # 이름, 종류, 머신
hostel config rooms # 머신, 종류, OS, 플랫폼, 레이블, 방
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가 필요하지 않습니다.
-
컴퓨터에서 머신 코드를 생성합니다(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; 서버가 없으면 추가합니다). 앱에서: 프론트 데스크 › 방 추가. -
새 머신에서 관리자 권한으로 출력된 명령을 실행합니다: macOS와 Linux에서는
sudo, Windows에서는 관리자 PowerShell. 이 명령은 서버에서hostel을 다운로드하고hostel machine join <code>를 실행합니다.
hostel machine join은 hostel 사용자를 생성하고(관리자 권한 없음), 서버의 키를 설치하고, 머신을 설정에 추가하며(connect = true, OS는 머신에서 확인), hostel machine connect를 실행하는 서비스를 설치합니다:
| OS | 서비스 | 로그 |
|---|---|---|
| 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]).
-
join이 출력하고 사람만 수행할 수 있는 단계를 수행합니다:- macOS: 시스템 설정 › 일반 › 공유 › 원격 로그인 켜기 (
hostel사용자 대상); iOS용 Xcode;desktop의 경우hostel자동 로그인 및 화면 보호기 후 암호 없음. - Windows: OpenSSH 서버가 실행되고 자동으로 시작됨 (
Get-Service sshd);desktop의 경우 "Hostel desktop" 작업. - Linux: SSH 서버가 22번 포트에서 실행되고
hostel의 키 로그인을 허용함.
- macOS: 시스템 설정 › 일반 › 공유 › 원격 로그인 켜기 (
-
확인:
hostel status에서 1분 이내에 방이 표시됩니다.
서버가 SSH로 접근하는 정적 머신
서버가 머신으로 TCP 연결을 열 수 있는 경우(동일 LAN 또는 VPN) 사용합니다. 머신에 서버의 SSH 키를 가진 표준 사용자 hostel을 생성합니다. 키는 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"] # 장치 플랫폼; OS 플랫폼은 자동
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및 자체 OSuser를 설정할 수 있습니다.- 제공자의
env및tools는 해당 제공자의 모든 머신에 적용됩니다. 머신 키는 동일한 이름의 키를 덮어씁니다. - 서버는 첫 번째 연결 시 머신의 SSH 호스트 키를 고정합니다.
- Windows 수동 설정:
docs/static-room-setup.md, "Windows" 섹션(사용자 및 OpenSSH가 요구하는authorized_keys의 액세스 규칙). - 공개 주소의 경우: 서버에서만 인바운드 SSH를 허용하거나
connect = true(join 흐름)를 사용하고 인바운드 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를 서버 사용자로 설치하고 서비스의 PATH에 ~/.local/bin을 추가합니다:
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에 도달해도 삭제됩니다. 인스턴스는 서버가 연장하는 고정 기한이 있습니다. - macOS devbox는 Linux devbox보다 분당 비용이 훨씬 높습니다.
- 플랜 제한은 모든 임대에 함께 적용됩니다(하나의 로그인을 공유). Developer 플랜: 사용자당 devbox 1개, 최대 3시간, Windows 없음. "제한 도달" 오류는
limit_retry(2분) 동안 머신을 가득 찬 것으로 표시합니다. linux인스턴스 유형만 지원됩니다. Namespace의 Android는 Linux를 사용합니다.- 로그인은 며칠 동안 지속됩니다. 종료되면 제공자 호출이 실패합니다: 다시 로그인하세요.
외부 제공자 (사용자 정의 명령)
kind = "external"은 각 작업(capabilities, provision, resume, stop, extend, destroy, list, access)에 대해 JSON을 stdin 및 stdout으로 사용하여 명령을 실행합니다. 전체 규약은 docs/design.md, 섹션 7, "External provider contract"에 있습니다. 저장소의 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초)마다 서버는 각 유휴 정적 방을 확인합니다. 응답하지 않는 방은 오프라인으로 전환되고 임대를 받지 않습니다. 다시 응답하면 서버가 자체적으로 방을 다시 준비합니다. 명령이 필요하지 않습니다. hostel status는 offline (last seen ...)을 출력합니다. hostel-troubleshoot을 참조하세요.