VIRGO

추가 Host 설치와 업데이트

원본
docs/website/additional-host.md
고정된 커밋
e106595060cc2787403439a45e1ef52c191e25f7
sha256
1e981f1f8193c362eb64a8ccaab6a1c4160e7a7a1d44e6574054d29fc2a48f95
번역
Virgo documentation maintainers · Full translation of the pinned English source, reviewed against it. Command syntax, release-status boundaries, capability limitations and source hashes are preserved exactly.
번역 원본 sha256
1e981f1f8193c362eb64a8ccaab6a1c4160e7a7a1d44e6574054d29fc2a48f95
한국어 본문 sha256
3d33c5f9e1a0934e440dc404b37f392907d3422f29d673699c38d1230df51a8b

이 가이드는 위에 고정된 원본에서 발행됩니다. 영어 정본을 한국어로 완역했으며, 명령 구문과 출시 상태 경계, 기능 한계, 원본 hash는 그대로 보존합니다.

그림은 사이트를 빌드할 때 정적 이미지로 그려집니다. 같은 흐름을 각 그림 아래에 글로도 적어 두므로, 어떤 스크립트에도 의존하지 않습니다.

추가 Host 설치와 업데이트

이 운영자 절차는 macOS Apple Silicon과 이미 있는 Hub를 대상으로 합니다. Virgo는 출시 준비 단계에 있습니다. 정본 릴리스 저장소에 대한 접근 권한이 필요하며, 누구나 익명으로 쓸 수 있는 공개 설치 프로그램이 아닙니다.

발행 경계: 이 명령들은 승인된 Host 설치/업데이트 CLI와 정본 부트스트랩이 함께 발행되어 있어야 동작합니다. 문서가 바뀐다고 해서 예전 current.json 메타데이터가 새 명령을 갖게 되지는 않습니다. 릴리스 소유자가 그 경계를 발행하고 검증하기 전까지 이 가이드를 준비된 것으로 취급해서는 안 됩니다.

결과는 기존 Hub에 연결된 Host 하나이며, 로컬 Hub 데이터베이스나 Seat별 설정 파일은 필요하지 않습니다. provider 발견, claim을 우선하는 attachment, 기능 활성화는 각자의 가용성 확인 항목을 가집니다.

머신과 런타임 준비

Host를 소유할 macOS 계정으로 로그인한 상태에서 진행하세요. 그 계정의 launchd 사용자 도메인이 프로세스를 관리합니다. uname -m이 arm64를 보고하는지 확인하세요. 검증된 인터프리터는 Bun 1.3.14입니다. 공식 Bun 설치 프로그램으로 정확히 그 버전을 안정적인 위치에 설치하세요.

VIRGO_BUN_HOME="$HOME/.local/share/virgo/providers/bun/1.3.14"
curl -fsSL https://bun.com/install | BUN_INSTALL="$VIRGO_BUN_HOME" bash -s "bun-v1.3.14"
export PATH="$VIRGO_BUN_HOME/bin:$PATH"
bun --version

1.3.14여야 합니다. 이 실행 파일은 같은 위치에 두세요. supervisor가 실제 인터프리터 경로를 기록합니다. 이 추가 Host에는 Docker와 Node가 필요하지 않습니다. GitHub CLI를 설치하고 virgo-codes/virgo-release에 읽기 권한이 있는 계정으로 인증하세요. GitHub 접근 권한과 Hub 등록 권한은 서로 다른 권한입니다.

정본 부트스트랩 받기

인증된 GitHub 경로로 릴리스 저장소를 클론하세요.

VIRGO_BOOTSTRAP="$HOME/virgo-release-bootstrap"
gh repo clone virgo-codes/virgo-release "$VIRGO_BOOTSTRAP"
git -C "$VIRGO_BOOTSTRAP" checkout main

current.json에는 소스 저장소와 커밋, 정확한 릴리스, CLI 체크섬이 기록됩니다. 부트스트랩은 그 CLI를 release-<release>에서 내려받아 검증한 뒤 Bun으로 실행합니다. CLI는 manifest와 네이티브 아카이브를 검증합니다. 로컬 제품 소스 체크아웃은 필요하지 않으며, 릴리스 자리에 feature 브랜치를 대신 쓰지 않습니다.

등록 권한 공급

Hub 소유자가 기존의 비공개 운영자 경로로 등록 자격 증명을 전달합니다. 자격 증명은 여러분 계정이 소유하고 모드가 0600인 일반 파일이어야 합니다. 이 경로는 Hub의 기존 installationAdmin 권한을 사용하며, 한 번만 쓰는 등록 허가가 아닙니다. 파일은 Host 인스턴스 디렉터리 밖에 두고 경로만 전달하세요. 그 값을 명령이나 영수증에 붙여 넣지 마세요.

설치 프로그램이 Host 키와 로컬 관리 자격 증명을 만듭니다. 이들은 Hub 등록 자격 증명이나 GitHub 아티팩트 접근 권한과는 별개입니다.

설치

기존 Hub URL, Account, 머신 이름, 자격 증명 파일 경로를 설정하세요. 사용 가능한 고정 로컬 포트를 쓰세요. 이 예시의 --network local은 Host의 loopback 리스너를 가리키며, Hub 연결은 바깥으로 나가는 HTTPS입니다.

umask 077
VIRGO_ROOT="$HOME/virgo"
VIRGO_MACHINE="my-new-host"
VIRGO_HUB_URL="https://your-existing-hub.example/"
VIRGO_ACCOUNT="your-account"
VIRGO_ENROLLMENT_FILE="$HOME/.config/virgo/enrollment/hub-admin.token"
VIRGO_RECEIPT="$HOME/virgo-host-install.json"

bash "$VIRGO_BOOTSTRAP/install.sh" install --mode host \
  --root "$VIRGO_ROOT" --machine "$VIRGO_MACHINE" --instance host \
  --hub-url "$VIRGO_HUB_URL" --account "$VIRGO_ACCOUNT" \
  --network local --advertised-url http://127.0.0.1:58612/ --api-port 58612 \
  --enrollment-credential-file "$VIRGO_ENROLLMENT_FILE" > "$VIRGO_RECEIPT"

종료 코드가 0이어야 하고, 영수증에 ok: true와 state.outcome.state: "active"가 있어야 합니다. 영수증의 정확한 installationDirectory와 releaseDirectory를 보존하고, 인코딩된 인스턴스 경로를 손으로 만들지 마세요. 동일한 재시도는 정체성과 설정을 보존합니다. 새 릴리스로 옮길 때는 Host를 다시 설치하지 말고 업데이트 명령을 쓰세요.

연결 확인

성공한 영수증에 적힌, 설치된 CLI 경로를 사용하세요.

VIRGO_INSTANCE=$(bun -e 'const r=await Bun.file(process.argv[1]).json(); if(!r.ok||r.state?.outcome?.state!=="active")process.exit(1); console.log(r.state.installationDirectory)' "$VIRGO_RECEIPT")
VIRGO_INSTALLED_CLI=$(bun -e 'const r=await Bun.file(process.argv[1]).json(); if(!r.ok||r.state?.outcome?.state!=="active")process.exit(1); console.log(r.state.releaseDirectory+"/bin/virgo")' "$VIRGO_RECEIPT")
bun "$VIRGO_INSTALLED_CLI" --directory "$VIRGO_INSTANCE" host status

반환된 value에는 기대한 process.machine과 process.release, 프로세스 식별자, process.protocol: "responding", hub.state: "connected"가 있어야 하고, hub.associated와 hub.fresh가 모두 true여야 합니다. 나중에 비교할 수 있도록 hub.hostId를 보존하세요. 이 조회에는 Seat이나 provider principal이 필요하지 않습니다. 과거에 연결된 적이 있다는 사실만으로 지금 Hub에 연결되어 있다는 증명이 되지는 않습니다. Hub 상태가 재연결 중인 동안에도 로컬 프로세스는 계속 응답할 수 있습니다.

같은 정본 소스에서 업데이트

깨끗한 부트스트랩 체크아웃을 갱신한 뒤, 기존 대상을 업데이트하세요.

git -C "$VIRGO_BOOTSTRAP" pull --ff-only
VIRGO_UPDATE_RECEIPT="$HOME/virgo-host-update.json"
bash "$VIRGO_BOOTSTRAP/install.sh" upgrade --mode host \
  --root "$VIRGO_ROOT" --machine "$VIRGO_MACHINE" --instance host \
  > "$VIRGO_UPDATE_RECEIPT"

래퍼는 current.json에서 새로 발행된 릴리스를 선택합니다. 릴리스나 번들, 배포 출처를 따로 지정하지 마세요. 업그레이드는 기존 Hub, Account, 키, 연결 관계, 그리고 관련 없는 provider 설정을 보존합니다. 반환된 planId와 상태를 저장하세요. 같은 릴리스를 반복하면 아티팩트를 검증하고, 원래 롤백 계획을 빈 업그레이드로 대체하지 않고 그대로 보존합니다.

처음 설치 영수증은 과거 기록으로 남습니다. 업데이트 뒤에는 성공한 업데이트 영수증에서 설치된 CLI를 구하세요.

VIRGO_INSTALLED_CLI=$(bun -e 'const r=await Bun.file(process.argv[1]).json(); if(!r.ok||r.state?.state!=="active")process.exit(1); console.log(r.releaseDirectory+"/bin/virgo")' "$VIRGO_UPDATE_RECEIPT")
bun "$VIRGO_INSTALLED_CLI" --directory "$VIRGO_INSTANCE" host status

새 릴리스와 새로 맺어진 Hub 연결, 그리고 바뀌지 않은 hub.hostId를 확인하세요. 이미 provider를 실행 중인 Host라면, 설치 소유자가 보존된 provider 세션, 대기 중인 효과, 실제 네이티브 전달까지 확인해야 합니다. Host 상태 결과만으로는 그 provider 결과들이 입증되지 않습니다.

그 업데이트를 정확히 되돌리기

짐작한 예전 릴리스가 아니라, 그 업데이트의 계획을 사용하세요.

VIRGO_APPLIED_PLAN=$(bun -e 'const r=await Bun.file(process.argv[1]).json(); if(typeof r.planId!=="string")process.exit(1); console.log(r.planId)' "$VIRGO_UPDATE_RECEIPT")
VIRGO_UPDATE_CLI="$VIRGO_INSTALLED_CLI"
VIRGO_ROLLBACK_RECEIPT="$HOME/virgo-host-rollback.json"
bash "$VIRGO_BOOTSTRAP/install.sh" rollback --mode host \
  --root "$VIRGO_ROOT" --machine "$VIRGO_MACHINE" --instance host \
  --plan-id "$VIRGO_APPLIED_PLAN" > "$VIRGO_ROLLBACK_RECEIPT"

롤백은 이전에 검증된 아티팩트와 설정을 복원하고 Host를 멈춘 상태로 둡니다. 그 영수증에서 복원된 릴리스를 읽고, 여전히 설치되어 있는 더 새로운 검증된 CLI로 명시적으로 다시 활성화하세요.

VIRGO_PRIOR_RELEASE=$(bun -e 'const r=await Bun.file(process.argv[1]).json(); const v=r.state?.actual?.installedRelease; if(!r.ok||r.activation!=="stopped"||typeof v!=="string")process.exit(1); console.log(v)' "$VIRGO_ROLLBACK_RECEIPT")
bun "$VIRGO_UPDATE_CLI" upgrade --mode host \
  --root "$VIRGO_ROOT" --machine "$VIRGO_MACHINE" --instance host \
  --release "$VIRGO_PRIOR_RELEASE" --github-repository virgo-codes/virgo-release
bun "$VIRGO_UPDATE_CLI" --directory "$VIRGO_INSTANCE" host status

복원된 릴리스와, 같은 Host 정체성으로 새로 맺어진 연결을 확인하세요. 정본 래퍼는 current.json을 선택하므로 평범한 업그레이드는 다시 더 새로운 릴리스를 고르게 됩니다. 이 명시적 복구 명령은 정확한 롤백 계획이 복원한 릴리스만 선택합니다.

후속 활성화가 실패한 경우에도 반환된 계획으로 되돌릴 수 있습니다. 상태가 확정되지 않았다면 영수증과 키를 보존하세요. 연결 관계를 지우거나 새 머신 이름을 지어내지 마세요. Hub만 사용할 수 없는 상황이라면 그 경로를 복구하고 상태를 다시 읽으세요. Host는 기존 정체성으로 다시 연결됩니다.

설치된 provider와 기능 능력에 대해서는 아래에서 위로의 검증을 이어서 진행하세요. 통제된 환경에서 얻은 설치 증거와 실제 여러분 머신에서의 승인은 서로 다른 것입니다.