# VibePackr AI installation guide / AI 설치 안내

Read this file before running the supplied `install.sh`. It is one workflow with English and Korean explanations. Execute each numbered step once.

동봉된 `install.sh`를 실행하기 전에 이 문서를 읽으세요. 영문과 한국어는 같은 절차의 설명입니다. 각 번호의 단계는 한 번만 실행하세요.

## 1. Responsibility and inputs / 담당 범위와 입력

VibePackr supplies the downloadable package and its documentation. The customer supplies, authorizes and operates the target VM, OS account, network, storage and AI runtime. Perform the installation in the customer's VM using the customer's approved access. A vendor-operated application VM is not part of this procedure.

VibePackr는 설치 패키지와 문서를 배포합니다. 대상 VM, OS 계정, 네트워크, 저장소, AI 실행 환경의 준비·인가·운영은 고객이 담당합니다. 고객이 허용한 접근 방법으로 고객 소유 VM에 설치하세요. 이 절차에서 공급사 운영 애플리케이션 VM을 만들지 않습니다.

Use the customer's existing installation authorization. Collect only missing inputs; reuse values already established by the package, the target or the customer's request. Ordinary supported installation does not require a VibePackr engineer to join the session.

고객이 부여한 설치 권한 안에서 진행하세요. 패키지, 대상 환경, 고객 요청으로 이미 확인한 값은 재사용하고 빠진 입력만 고객에게 확인하세요. 지원 환경의 일반 설치에 VibePackr 담당자의 세션 참여가 필요하지 않도록 진행하세요.

| Input / 입력 | Required value / 필요한 값 |
|---|---|
| Delivery / 전달본 | Approved download URL or local package and a trusted expected SHA-256. / 승인된 다운로드 주소 또는 로컬 패키지와 신뢰할 수 있는 예상 SHA-256. |
| Target / 설치 대상 | Customer-owned Debian 13, amd64/x86_64 VM with systemd. Confirm the actual VM; do not choose a cloud account or create a server by assumption. / 고객 소유 Debian 13 amd64/x86_64·systemd VM. 실제 대상을 확인하고 클라우드 계정이나 새 서버를 임의로 선택하지 마세요. |
| Access / 접근 | Customer-approved OS login and installation privilege. Keep passwords, private keys and tokens in the customer's credential mechanism. / 고객이 허용한 OS 로그인과 설치 권한. 암호·개인키·토큰은 고객의 자격증명 보관 수단에서 사용하세요. |
| Working area / 작업 위치 | A customer-approved private directory for extraction and retained installation records, with sufficient free disk space. / 압축 해제와 설치 기록 보관에 사용할 고객의 비공개 작업 디렉터리와 충분한 여유 공간. |
| Network / 네트워크 | Online or closed-network installation as actually supplied. The complete appliance does not need an AI provider merely to install; additional client/model dependencies follow their supplied instructions. / 실제 제공 환경에 맞는 온라인 또는 폐쇄망 방식. 완전한 appliance의 설치 자체에는 AI 제공자가 필요하지 않으며, 클라이언트·모델의 추가 의존성은 해당 안내를 따릅니다. |

Do not request credentials in chat, create a shared password, open a firewall, expose a listener or change IAM merely to complete this guide. Obtain a missing target prerequisite from the customer's responsible administrator.

이 안내를 완료하기 위해 채팅으로 비밀값을 받거나 공통 암호를 만들거나 방화벽·외부 리스너·IAM을 임의 변경하지 마세요. 설치 대상의 누락된 준비 사항은 고객 내부 담당자가 해결합니다.

## 2. Locate the complete installer / 완전한 설치본 찾기

Choose the row that matches the files actually supplied. The default route is installation into the customer's existing VM.

실제로 받은 파일 구성에 맞는 경로를 선택하세요. 기본 경로는 고객의 기존 VM에 설치하는 방식입니다.

| Supplied material / 받은 자료 | Action / 진행 방법 |
|---|---|
| Complete appliance archive / 완전한 appliance archive | Verify the archive, then extract it into a new private directory in the customer's VM. Use the resulting directory containing `install.sh`, `bin/`, `systemd/`, `release-manifest.json` and `SHA256SUMS`. / archive를 검증한 뒤 고객 VM의 새 비공개 디렉터리에 해제하세요. 나열한 파일과 디렉터리가 있는 설치본 루트에서 진행합니다. |
| PoC download bundle / PoC 다운로드 묶음 | On the customer's existing supported VM, use its `installer-media/vibepackr-appliance.tar.gz`. The outer bundle's `START_HERE.html` identifies the supplied media and checksums. / 고객의 지원 VM에서 묶음 안의 `installer-media/vibepackr-appliance.tar.gz`를 사용하세요. 외부 묶음의 `START_HERE.html`에서 미디어와 체크섬을 확인합니다. |
| Read-only installation ISO / 읽기 전용 설치 ISO | Attach it through the customer's VM platform, mount it read-only using the customer's approved administration route, and copy the appliance archive into the private working directory before extraction. / 고객 VM 플랫폼에서 연결하고 승인된 관리 방법으로 읽기 전용 마운트한 뒤, appliance archive를 비공개 작업 위치로 복사하여 해제하세요. |
| Already installed release / 이미 설치된 제품 | Start with `/opt/vibepackr/setup paths` and the installed bootstrap instructions. Preserve that installation and any Work; do not force a reinstall or upgrade. / `/opt/vibepackr/setup paths`와 설치된 bootstrap 안내부터 확인하세요. 기존 설치와 Work를 보존하며 강제 재설치·업그레이드를 하지 마세요. |

If a clean QCOW2/cloud-init template is also supplied, it is optional media for the customer's own VM platform. The customer chooses the VM, instance identity and public login key. Follow that platform's documented import/NoCloud procedure and the supplied templates. There is no vendor VM login or shared password to substitute.

깨끗한 QCOW2·cloud-init 템플릿이 함께 제공된다면 고객 VM 플랫폼에서 사용할 수 있는 선택형 미디어입니다. VM, 인스턴스 식별자, 로그인 공개키는 고객이 정합니다. 해당 플랫폼의 import·NoCloud 절차와 동봉 템플릿을 따르세요. 공급사 VM 로그인이나 공통 암호로 대체하지 않습니다.

`install.sh` alone is not a complete installer. Do not download missing binaries individually, copy a repository into the VM or run `curl ... | sh`. Keep the complete package together.

`install.sh` 한 파일만으로는 설치할 수 없습니다. 빠진 바이너리를 개별 다운로드하거나 저장소를 VM에 복사하거나 `curl ... | sh`를 실행하지 마세요. 완전한 패키지를 함께 유지하세요.

## 3. Verify before mutation / 변경 전 검증

Run observations on the customer's target VM and retain their actual output. Confirm Debian 13, x86_64 and systemd as PID 1 before running the installer. Other OS/CPU combinations require their matching supplied package.

고객의 실제 대상 VM에서 아래 정보를 조회하고 원래 출력을 보관하세요. 설치 전에 Debian 13, x86_64, PID 1의 systemd를 확인합니다. 다른 OS·CPU에는 그 환경에 맞는 별도 전달본이 필요합니다.

```sh
uname -s
uname -m
cat /etc/os-release
ps -p 1 -o comm=
df -h
```

Compare the archive's SHA-256 with the trusted expected value from the approved delivery. A checksum copied from an unrelated website, or placed beside an otherwise untrusted archive, is not independent publisher verification. If the trusted outer PoC bundle contains the inner archive and its checksum, preserve that chain.

archive의 SHA-256을 승인된 전달 경로에서 받은 예상 값과 대조하세요. 무관한 웹사이트의 체크섬이나 신뢰하지 못한 archive 옆의 체크섬만으로 발행자 신뢰가 생기지는 않습니다. 신뢰한 외부 PoC 묶음에 inner archive와 체크섬이 함께 들어 있다면 그 연결을 보존하세요.

```sh
sha256sum "$ARCHIVE"
```

`ARCHIVE` must be the observed absolute path of the supplied archive. Stop on a mismatch. After trusted extraction, set `PACKAGE_ROOT` to the observed complete installer directory and `WORK_DIR` to the customer's approved private working directory. Resolve these paths from the actual files before using the following blocks.

`ARCHIVE`는 실제 받은 archive의 절대 경로입니다. 불일치하면 중단하세요. 신뢰한 압축 해제 후 `PACKAGE_ROOT`에는 완전한 설치본 디렉터리, `WORK_DIR`에는 고객이 허용한 비공개 작업 디렉터리를 지정합니다. 아래 블록을 실행하기 전에 실제 파일에서 경로를 확인하세요.

```sh
(
  set -eu
  : "${PACKAGE_ROOT:?Set the observed complete installer directory}"
  cd "$PACKAGE_ROOT"
  test -f install.sh
  test -f release-manifest.json
  test -f SHA256SUMS
  test -d bin
  test -d systemd
  sha256sum -c SHA256SUMS
)
```

Retain an existing `/etc/vibepackr/release-manifest.json` if present. A matching release can resume configuration through `setup`; a different installed release is not permission to replace it. Do not edit manifests, symlinks or native state to bypass that check.

`/etc/vibepackr/release-manifest.json`이 있으면 기존 값을 보존하세요. 같은 릴리스는 `setup`으로 설정을 이어가고, 다른 릴리스가 설치돼 있으면 이 안내로 교체하지 않습니다. 검사를 통과시키려고 manifest·심볼릭 링크·native 상태를 고치지 마세요.

## 4. Run the shared installer once / 공용 설치 스크립트 한 번 실행

The AI and a human operator use the same supplied `install.sh`. It validates supplied bytes, installs runtime files and systemd units, creates the runtime account as needed and starts the control plane. Use the customer's existing root session or approved noninteractive sudo. If that privilege is unavailable, retain the refusal and let the customer's administrator provide the permitted installation route.

AI와 사람 운영자는 동일한 `install.sh`를 사용합니다. 이 스크립트는 전달본 검증, 실행 파일·systemd unit 설치, 필요한 runtime 계정 생성과 control plane 시작을 수행합니다. 고객의 기존 root 세션 또는 허용된 비대화형 sudo를 사용하세요. 권한이 없으면 거부 결과를 보존하고 고객 관리자가 허용한 설치 경로를 마련하도록 하세요.

Create a new private record directory. The following block preserves the real installer exit even when installation fails. Do not repeat it automatically after a timeout or failure.

새 비공개 기록 디렉터리를 만드세요. 아래 블록은 설치 실패 시에도 실제 종료 코드를 보존합니다. 시간 초과나 실패 뒤 자동 반복하지 마세요.

```sh
umask 077
: "${WORK_DIR:?Set the approved private working directory}"
record_dir=$(mktemp -d "$WORK_DIR/vibepackr-install.XXXXXX") || exit 73
printf '%s\n' "$record_dir"
(
  set +e
  cd "$PACKAGE_ROOT" || exit 66
  if [ "$(id -u)" -eq 0 ]; then
    sh ./install.sh >"$record_dir/install.log" 2>&1
  else
    sudo -n sh ./install.sh >"$record_dir/install.log" 2>&1
  fi
  install_exit=$?
  printf '%s\n' "$install_exit" >"$record_dir/install.exit"
  exit "$install_exit"
)
```

Read `install.exit` and the first failing stage in `install.log`. An output file, running VM, active process or script name is not an installation success signal.

`install.exit`와 `install.log`의 최초 실패 단계를 확인하세요. 출력 파일이 생겼거나 VM·프로세스가 실행 중이라는 사실만으로 설치 성공을 판정하지 마세요.

## 5. Inspect the installed result / 실제 설치 결과 확인

Use the installed public paths. `setup paths` discovers the release and supplied documentation; it does not grant product access. When this guide is included in the release, `install=` identifies its installed location, also available at `/opt/vibepackr/current/install.md`.

설치된 공개 진입점을 사용하세요. `setup paths`는 릴리스와 동봉 문서의 경로를 알려 주며 제품 권한을 부여하지 않습니다. 이 문서가 포함된 릴리스는 `install=`로 설치된 문서 위치를 표시하며 `/opt/vibepackr/current/install.md`에서도 읽을 수 있습니다.

```sh
/opt/vibepackr/setup paths
systemctl is-active vibepackr-control-plane.service
```

Run `/opt/vibepackr/health` using the customer's approved administration route and record its actual exit and output. It checks installation/customer-binding prerequisites as well as the control plane. A nonzero health result needs its actual missing prerequisite resolved; do not relabel it as ready or repeatedly reinstall. Installation, product binding, AI runtime readiness and Work authority are separate observations.

고객이 허용한 관리 방법으로 `/opt/vibepackr/health`를 실행하고 실제 종료 코드와 출력을 기록하세요. 이 진입점은 control plane과 설치·고객 바인딩 준비 사항을 함께 검사합니다. 0이 아닌 종료는 실제 누락 원인을 해결해야 하며 READY로 바꾸어 보고하거나 재설치를 반복하지 마세요. 설치, 제품 바인딩, AI runtime 준비, Work 권한은 각각 확인합니다.

## 6. Connect the customer's environment / 고객 환경 연결

Read the local `bootstrap=` and `skills=` locations returned by `setup paths`. Follow the supplied `BOOTSTRAP.md`, `MCP_SETUP.md` and relevant Skills for this exact release. These local files are supplied with the installer; downloading an online copy of an older guide is not required.

`setup paths`가 반환한 로컬 `bootstrap=`·`skills=` 위치를 읽으세요. 해당 릴리스의 `BOOTSTRAP.md`, `MCP_SETUP.md`, 필요한 Skill을 따릅니다. 설치본에 함께 제공되는 로컬 파일을 사용하며 이전 온라인 문서를 다시 받을 필요는 없습니다.

The customer's AI may prepare and execute the permitted setup requests, inspect actual native responses and connect the supported client/runtime. Bind actual installation, customer, OS identity, runtime/account/model and returned references. Keep secrets in the customer's approved mechanism. Do not invent values or use a vendor's previous test account, endpoint or Work ID.

고객의 AI는 허용된 설정 요청을 준비·실행하고 native 반환값을 확인하며 지원 클라이언트·runtime을 연결할 수 있습니다. 실제 설치·고객·OS 신원·runtime·계정·모델과 반환 참조를 사용하세요. 비밀값은 고객의 승인된 보관 수단에서 처리하며 공급사의 이전 시험 계정·주소·Work ID나 추정 값을 사용하지 마세요.

Where the native setup requires the appointed human's terminal confirmation, pause at that exact step for the customer's designated person and resume the same installation afterwards. This is a local customer responsibility; it does not require a vendor engineer to operate the VM. Do not substitute an AI, root or service account for a required human decision.

native 설정이 지정된 사람의 터미널 확인을 요구하면 그 단계에서 고객이 지정한 사람이 확인한 뒤 같은 설치에서 이어가세요. 이는 고객 내부의 로컬 확인이며 공급사 담당자가 VM을 대신 운영하는 절차가 아닙니다. 필요한 사람 결정을 AI·root·서비스 계정으로 대체하지 마세요.

Only continue to a first Work when the customer has authorized that operation and its inputs. Installation authorization alone does not submit business Work. Follow the release's same-Work result/report inspection and human-acceptance procedure.

첫 Work는 고객이 해당 작업과 입력을 허용했을 때 진행합니다. 설치 권한만으로 업무 Work를 제출하지 마세요. 해당 릴리스의 같은 Work 결과·감사보고서 확인 및 사람 수락 절차를 따릅니다.

## 7. Failure and resumption / 실패와 재개

| Observation / 관측 | Next action / 다음 조치 |
|---|---|
| Incomplete package or digest mismatch / 패키지 누락·해시 불일치 | Stop using that copy; obtain the exact verified delivery again. Retain the first observation. / 해당 사본 사용을 중단하고 정확히 검증된 전달본을 받으세요. 최초 관측은 보존합니다. |
| Unsupported OS/CPU / 지원하지 않는 OS·CPU | The customer selects the supported target or obtains its matching package. / 고객이 지원 대상을 선택하거나 해당 환경용 전달본을 준비합니다. |
| Exit 77 or sudo denied / 종료 77·sudo 거절 | The customer's administrator supplies approved installation privilege; do not expand your own access. / 고객 관리자가 허용된 설치 권한을 마련합니다. AI가 자기 권한을 확대하지 마세요. |
| Different installed release; exit 65 / 다른 릴리스 설치·종료 65 | Preserve both identities and use the supplied upgrade/recovery procedure. / 두 릴리스 신원을 보존하고 제공된 업그레이드·복구 절차를 사용하세요. |
| Partial installation or nonzero health / 부분 설치·health 실패 | Record the first failed stage, actual files/service state and exit. Resolve that prerequisite before any explicitly approved resumption. / 최초 실패 단계, 실제 파일·서비스 상태, 종료 코드를 보존하고 누락 원인을 해결한 뒤 허용된 재개를 진행하세요. |
| Missing runtime/binding/human confirmation / runtime·바인딩·사람 확인 누락 | Continue the release's local bootstrap checkpoint with the customer's designated owner. / 고객이 지정한 담당자와 해당 릴리스의 로컬 bootstrap 체크포인트를 이어가세요. |

`disable` and `uninstall` require the release's explicit native request and credential inputs. They are not automatic rollback commands. Do not delete product state, remove evidence, edit a native journal or restart unrelated services as cleanup.

`disable`·`uninstall`에는 해당 릴리스의 명시적인 native 요청과 자격증명 입력이 필요합니다. 자동 롤백 명령이 아닙니다. 정리 목적으로 제품 상태·근거를 삭제하거나 native 원장을 편집하거나 무관한 서비스를 재시작하지 마세요.

## 8. Return a usable installation record / 이어 쓸 수 있는 설치 기록

Return the following to the customer in their selected language, using actual observations and references to private local records. Keep unperformed checks explicitly pending. Preserve an original Work ID when resuming; do not create a replacement execution to hide uncertainty.

아래 내용을 고객이 선택한 언어로 보고하되 실제 관측과 비공개 로컬 기록의 참조를 사용하세요. 하지 않은 검사는 대기로 남깁니다. 재개 시 원래 Work ID를 보존하고 불확실한 결과를 새 실행으로 대체하지 마세요.

| Record / 기록 | Include / 포함할 내용 |
|---|---|
| Target and delivery / 대상·전달본 | Observed OS/CPU, supplied filename and verified archive SHA-256. / 실제 OS·CPU, 전달 파일명, 대조한 archive SHA-256. |
| Installation / 설치 | Installer exit, first failure if any, installed release identity and native paths. / 설치 종료 코드·최초 실패, 설치된 릴리스 신원과 native 경로. |
| Readiness / 준비 상태 | Actual service and health observations; product/runtime binding checkpoint. / 실제 service·health 관측과 제품·runtime 바인딩 체크포인트. |
| Evidence / 근거 | Customer-local record directory and unchanged native receipt references. / 고객 로컬 기록 디렉터리와 변경하지 않은 native 영수증 참조. |
| Next action / 다음 단계 | Exact missing input or customer-local action; otherwise the supported authorized next use. / 정확한 누락 입력·고객 내부 후속 조치, 또는 지원되는 다음 사용 단계. |

Full manuals / 전체 매뉴얼: <https://www.vibepackr.com/docs/>, <https://www.vibepackr.com/ko/docs/>.

Installation reference / 설치 상세: <https://www.vibepackr.com/docs/manuals/Part_01_Installation.html#start>, <https://www.vibepackr.com/ko/docs/manuals/Part_01_Installation.html#start>.

Operations reference / 운영 상세: <https://www.vibepackr.com/docs/manuals/Part_08_Operations.html#main>, <https://www.vibepackr.com/ko/docs/manuals/Part_08_Operations.html#main>.