클라이언트 설치·연결·에이전트 설정

아래 서버 명령은 네이티브 setup 진입점을 포함한 검증된 서버 릴리스가 필요합니다. 복사한 참고 코드만으로 어플라이언스를 설치·설정할 수 없습니다. /opt/vibepackr/setup 사용 전 관리자가 제공한 실제 경로를 확인하십시오.

1 · 서버와 클라이언트 역할 구분

관리자는 Linux VM에서 install.sh로 서버 릴리스를 설치합니다. setup.sh는 초기 구성과 이후 승인된 변경을 위한 서버 진입점입니다. Windows·macOS·Linux 관리자는 SSH로 같은 VM에 접속하여 그 안에서 동일한 Linux 명령을 실행합니다. 데스크톱 클라이언트는 각 OS 패키지로 설치합니다.

ssh ADMIN@VM_HOST
# Run the following on the intended Linux VM, from the verified server package:
sha256sum -c SHA256SUMS
sudo sh ./install.sh
# After installation, inspect the available setup commands:
/opt/vibepackr/setup --help

ADMIN·VM_HOST는 조직에서 제공한 값으로 바꿉니다. install.sh는 서버 설치 용도로 실행하며, 새 레거시나 모델을 추가하려고 VM을 다시 설치하지 않습니다. setup.sh에서 선택한 네이티브 관리 작업과 VM 관리자 안내를 따릅니다. 서버 설치 스크립트를 워크스테이션에서 실행하지 않습니다.

2 · OS에 맞는 패키지 검증·설치

관리자에게 설치 파일과 신뢰 가능한 릴리스 전달 목록을 받습니다. 실행 전 OS·CPU·릴리스·SHA-256을 대조합니다. 체크섬은 바이트 변경을 확인하므로 전달 목록의 신뢰 경로도 별도로 확인합니다. 새 릴리스 확인 전까지 정상 동작 중인 설치와 조직 프로필을 보존합니다.

아래 검증 예제의 설치 파일명은 자리 표시자입니다. 실제 제공 파일명으로 바꾸고 정확한 릴리스 전달 목록과 비교합니다.

Get-FileHash -Algorithm SHA256 -LiteralPath ".\CLIENT_INSTALLER.msi"

shasum -a 256 ./CLIENT_INSTALLER.dmg

sha256sum ./CLIENT_INSTALLER.deb
# On the supported Debian workstation:
sudo apt install ./CLIENT_INSTALLER.deb

폐쇄망은 네이티브 OS 전제 조건을 미리 확보해야 합니다. 선택형 SDK Rust·crate 패키지가 WebView2·GTK·WebKit을 제공하지는 않습니다. 설치를 강제하기 위해 패키지 서명·OS 신뢰 검사를 끄지 않습니다. macOS 정책이 Developer ID·공증을 요구하면 IT의 승인된 배포 경로를 사용합니다. DMG 자체는 Apple 신뢰를 증명하지 않습니다.

3 · 도구 실행 전 설치된 매뉴얼 열기

• Windows: 설치된 시작 메뉴 폴더에서 VibePackr Manual을 열거나 실제 설치 릴리스 안의 Manuals/Start_Setup.html을 엽니다.
• macOS: 복사한 VibePackr Client 폴더의 Open Manual.command를 실행하거나 Manuals/Start_Setup.html을 엽니다. DMG를 추출한 후 마운트된 이미지의 사본을 계속 사용하지 않습니다.
• Linux: 데스크톱 앱 메뉴의 VibePackr Manual을 열거나 설치된 /opt/vibepackr-client 릴리스 아래 Manuals/Start_Setup.html을 엽니다. HTML 열람에는 그래픽 브라우저가 필요합니다.
• Start_Setup은 Part.1을 엽니다. 전체 목차에서 Part.1~8과 이 가이드로 이동합니다. EN이 기본이며 KR은 명령 식별자·영문 SVG를 유지하면서 본문을 전환합니다. 상대 링크는 네트워크 없이도 작동합니다.
• 로컬 브라우저 정책으로 코드 Copy가 작동하지 않으면 코드 텍스트를 선택하여 복사합니다. 명령·타입 헤더는 계속 표시됩니다. 편집할 예제는 새 사용자 결과 폴더에 복사하며 설치된 예제를 직접 수정하지 않습니다.

다음 customer-access 예제는 관리자가 일치하는 네이티브 클라이언트·개인 설정을 제공한 경우에만 실행합니다. 이 실행 파일들은 문서 ZIP에 포함되지 않습니다. issued_at: 0은 현재의 승인된 시각 값으로 바꾸십시오. 이 예제는 그대로 실행할 수 없는 형식입니다.

4 · 대상 어플라이언스 연결 확인

관리자가 예상 어플라이언스·조직 신원, 호환 릴리스, 비공개 접속 주소·TLS 서버명과 본인 기기 인증서·키의 참조를 제공합니다. 공통 설치 파일에는 고객 접속 주소나 비밀키가 없습니다. 자격 증명은 Manuals·예제 입력·에이전트 프롬프트 밖에 보관합니다.

PackrGUI·Builder는 구성된 제품 연결을 통해 네이티브 상태를 표시합니다. Settings의 로컬 AI endpoint를 어플라이언스 mTLS 접속 주소로 사용하지 않습니다. 지원 원격 프로토콜에는 제공된 customer-access 클라이언트와 개인 구성을 사용하며, GUI 연결은 해당 릴리스의 관리자 제공 절차를 따릅니다.

예: 설정 에이전트에게 현재 Unix 시각을 사용한 새 HEALTH 요청과 동봉된 Customer access 안내의 개인 클라이언트 구성을 준비하도록 합니다. 설치된 해당 네이티브 실행 파일을 사용합니다. 아래 시각은 자리 표시자이며 재사용 요청이 아닙니다.

{
  "protocol_version": "PACKR_CUSTOMER_ACCESS_V1",
  "request_id": "client-health-01",
  "issued_at": 0,
  "operation": {"type": "HEALTH"}
}

./bin/packr-customer-access-client \
  --config /absolute/private/customer-access-client.json \
  --request-file /absolute/private/client-health.json

& ".\bin\packr-customer-access-client.exe" `
  --config "C:\PRIVATE\customer-access-client.json" `
  --request-file "C:\PRIVATE\client-health.json"

준비 완료 응답의 기대 필드: SUCCESS·READY·CUSTOMER_ACCESS_READY·transport_is_authority:false·authority_added:false입니다. 이것은 기대 출력 예제이며 사용자 어플라이언스의 응답 캡처가 아닙니다. 반환된 설치 신원과 허용 역할도 따로 확인합니다. 창 열림·로컬 어댑터 상태·인증서 복사만으로 인증된 어플라이언스 접근이 확인되지는 않습니다.

Skills·MCP·TOML 전체 참조 열기

5 · 공통 Skills·MCP·계획 워크시트 연결

AI 에이전트가 실제로 실행되는 위치를 선택합니다. Linux VM에서만 실행되는 에이전트는 VM 어댑터를 사용합니다. Windows·macOS·Linux 워크스테이션의 에이전트는 해당 OS 어댑터를 사용합니다. 하나의 공통 도구별 Skill 세트가 install/setup·헤드리스·PackrGUI·GAPE·Helper·Contract & Document·SDK·Builder를 다룹니다. 앱마다 전체 세트를 복제하지 않습니다.

설정 에이전트가 packr-agent-mcp register로 새 개인 등록을 만들고 선택한 AI 런타임의 공식 방식으로 일반 stdio descriptor를 가져옵니다. Skills도 해당 런타임이 지원하는 방식으로 불러옵니다. 기존 런타임 설정을 보존하며 일반 작업자는 세트를 편집하지 않습니다. runtime-plan.example.toml은 계획 워크시트이며 실행 가능한 연결 구성으로 로드하지 않습니다.

./bin/packr-agent-mcp --version
./bin/packr-agent-mcp register /absolute/private/setup-request.json

등록은 새 개인 출력 디렉터리에 registration.json·mcp-server.json·SETUP_RECEIPT.json을 만듭니다. AI 호스트를 자동으로 바꾸거나 Skill 로딩·Work 권한을 입증하지 않습니다. 관리자는 initialize/initialized·기대 도구 13개의 tools/list·vibepackr.setup.status와 호스트가 실제 읽은 Skills를 확인합니다. 스키마 필드·복구 예제는 동봉된 에이전트 세트의 MCP_SETUP.md를 참조합니다.

MCP 어댑터의 네이티브 도구 범위는 설정 상태·헤드리스 읽기 조회·GAPE 검증/비교·SDK 분석·Helper 작업입니다. GAPE 캡처·SDK 생성·Builder UI·서버 설치·실제 바인딩은 제공된 공개 도구 경로와 Skills를 사용합니다. 로컬 stdio 어댑터가 VM으로 자동 터널을 만드는 것은 아닙니다.

Part.8 · 복구·설치 후 확장

6 · 설치 후 새 레거시·런타임·모델 추가

• 정상 설치·현재 바인딩·미완료 Work를 보존합니다. 기존 릴리스와 승인된 변경 전 관찰을 기록하고 새 결과 폴더를 선택합니다.
• 변경된 지원 소스 리비전에 GAPE를 다시 실행합니다. 변경 전후 snapshot을 검증·비교하며 워크시트·과거 snapshot을 새 관찰로 사용하지 않습니다.
• 선언 전 Helper로 차이·위험을 확인하고 Contract & Document 선언을 갱신한 뒤 영향받는 Helper 검증·준비 검사를 다시 수행합니다.
• 호환 구현·승인 Pack이 목표를 충족하면 재사용합니다. 새 지원 어댑터가 필요할 때 SDK를, 새 Pack 후보가 필요할 때 Builder를 사용합니다. 후보와 승인 Pack은 구분해 보존합니다.
• 승인된 네이티브 서버 setup·바인딩 작업을 적용하고 실제 연결·영향받는 기존 흐름을 검증하며 롤백 방침을 기록합니다. 후보·등록 성공에서 실행 권한을 추론하지 않습니다.

중단된 작업은 재실행 전에 원래 작업 참조·네이티브 기록과 대조하여 정합성을 확인합니다. 대상·입력·catalog가 달라지면 검토한 새 등록을 사용합니다. 새 request ID를 주는 것만으로 복구 절차가 되지는 않습니다.

7 · 구체적인 실패·복구 사례

8 · 유용한 설치·연결 기록 남기기

릴리스·설치 파일 해시, OS·CPU, 실제 설치·매뉴얼 경로, 네이티브 버전, 예상 설치 신원, 비식별화한 연결 결과, 실제 MCP 도구·Skills와 미해결 reason code를 기록합니다. 개인 연결 파일·인증서는 공유 지원 기록 밖에 보관합니다. Work 실행을 요청하기 전에 일반 읽기 전용 예제를 확인합니다.