22/Documentation

관리 및 업데이트

휴대폰 또는 터미널에서 업데이트, 롤백, crew 업데이트, 메이저 버전 업그레이드, 중지, 제거, 0.x 버전을 1.0으로 업그레이드

설치에 사용한 도구:	현재 상태:	Verb 표기:
`herdr plugin install` 또는 `herdr plugin link`	Herdr 관리형(`herdr plugin list`에 `herdr.collie` 표시됨)	`herdr plugin action invoke <verb> --plugin herdr.collie`
설치 스크립트 또는 소스 빌드	독립형	설치 디렉터리에서의 `bin/collie <verb>`

Herdr 설치는 PATH에 collie이(가) 없습니다. Herdr 작업 ID(Herdr 작업)를 사용하십시오. 독립형 설치는 바이너리를 ~/.local/share/collie/current/bin/collie 또는 <checkout>/bin/collie에 배치합니다.

# the install script's layout
cd ~/.local/share/collie/current && bin/collie version
# a source build or a linked clone
cd ~/my/collie-checkout && bin/collie version

바이너리를 ~/.local/bin(PATH에 collie 추가)에 심볼릭 링크하려면 bin/collie link을(를) 실행하십시오.

설정 및 상태는 체크아웃 외부에 위치하며 업데이트 후에도 유지됩니다(bridge/solo-baseline.test.ts). .env 및 tailscale serve 레코드는 설정 디렉터리에 있습니다(바이너리 설치의 경우 ~/.config/collie, Herdr 설치의 경우 Herdr의 플러그인 설정 디렉터리). 페어링된 기기 및 stt.json은(는) 상태 디렉터리에 있습니다(COLLIE_STATE_DIR이(가) 이동하지 않는 한 ~/.local/state/collie).

패키지 설치본

패키지 관리자가 Collie를 설치한 경우 업데이트도 패키지 관리자가 수행하며, 이 섹션 아래의 모든 내용은 적용되지 않습니다:

sudo pacman -Syu collie-bin    # or `nix profile upgrade collie`, or `brew upgrade collie`

Collie는 디스크의 구조를 보고 패키지 설치본임을 인식합니다: .git 없음, versions/ 레이아웃 없음, 릴리스 페이로드가 포함하는 매니페스트, 읽기 전용이거나 홈 디렉터리 외부에 있거나 root 소유인 루트 경로. 마지막 세 조건 중 하나만 충족해도 충분합니다. 이후 인플레이스 업데이트를 거부하고 폴더를 소유한 관리자를 식별할 수 있는 경우 해당 명령을 안내합니다:

error: /opt/collie is a packaged install — updates come from your package manager.
       `collie update` will not replace its files.
       Take the new version with: sudo pacman -Syu collie-bin

접두사 경로에서 Collie가 인식하는 관리자를 찾을 수 없는 경우, 실행할 수 없는 명령을 추측하지 않고 첫 두 줄만 출력한 후 중단합니다.

collie doctor은(는) 동일한 설치를 정상 상태로 보고하며, 휴대전화의 업데이트 카드에는 업데이트 버튼 대신 패키지 명령과 함께 최신 릴리스가 있다는 내용이 계속 표시됩니다.

참고. 이는 우회해야 할 제한 사항이 아닙니다. 해당 폴더는 패키지 관리자의 소유이며, 패키지 관리자 모르게 파일을 교체하면 설치된 항목에 대한 데이터베이스 정보가 부정확해집니다. sudo collie update도 동일한 방식으로 작업을 거부합니다.

새 버전을 적용하려면 패키지 관리자를 실행한 다음 서비스를 다시 시작하십시오.

paru -Syu collie-bin                              # Arch, or your AUR helper of choice
nix profile upgrade collie                        # Nix
mise upgrade --bump github:AltanS/collie          # mise
collie restart

mise 설치는 예외입니다. 트리 구조가 .git 및 versions/ 레이아웃 없이 홈 디렉터리에 위치하므로 Collie는 이를 패키지된 것으로 인식하지 않습니다. 따라서 collie update 명령은 cannot tell how this Collie was installed 메시지와 함께 거부되며 관리자 이름을 지정하지 않습니다. mise가 계속 이를 소유합니다. 설치을(를) 참조하십시오.

다시 시작하는 작업은 Collie가 대신 처리할 수 없는 영역이며, 생략할 수 없습니다. 패키지 관리자는 실행 중인 브리지 아래에서 파일을 교체하므로, 프로세스가 이미 새 버전을 보고하는 중에도 기존 코드를 계속 실행하게 됩니다. Collie는 이러한 불일치를 감지하여 보고합니다. collie doctor 명령은 restart-pending 오류를 발생시키고, 휴대전화에는 "Collie was replaced on disk. Restart it."라는 내용의 "Bridge restart needed" 배너가 표시됩니다. 두 알림은 collie restart 명령이 실행되는 즉시 사라집니다.

crew에서 패키지로 설치된 멤버는 휴대폰을 통한 업데이트를 받지 않습니다. 크루는 이를 "패키지 관리자를 기다리는 중"으로 표시하고 해당 멤버 없이 실행을 완료된 것으로 처리하므로, 위 두 명령어를 실행하여 버전을 맞춰야 합니다.

패키지된 lead은(는) 자체 이동만 거부합니다. 휴대폰은 여전히 모든 member를 lead가 실행 중인 버전으로 맞추며, 한 번의 확인으로 모두 처리됩니다. 위의 두 명령으로 lead를 이동한 후에는 어떤 것도 자동으로 버전을 맞추지 않습니다. Updates 페이지를 한 번 더 탭하면 member가 lead의 새 버전을 따릅니다.

휴대폰 또는 터미널에서 업데이트

두 가지 업데이트 경로가 있으며, 둘 다 각 호스트에서 동일한 단계를 실행합니다. 즉, 활성 릴리스 옆에 새 릴리스를 스테이징하고, 심볼릭 링크를 전환하고, 재시작한 후 서비스가 응답하는지 확인합니다. 크루 리드에서는 두 경로 모두 전체 크루를 대상으로 합니다. 휴대폰은 빠른 경로입니다. 터미널은 휴대폰으로 버전을 맞출 수 없는 머신을 위한 대체 수단입니다.

휴대폰에서 진행

Settings을 열고 Updates를 선택합니다. 카드에는 실행 중인 버전, 최신 릴리스, 업데이트에 포함된 중간 버전이 표시됩니다. 호스트가 최신 릴리스 상태이면 카드에 해당 내용이 표시되고 아무것도 제공하지 않습니다.

그 아래에는 사전 점검이 검사 항목당 한 줄씩 표시됩니다: doctor, disk, bun, tree, upstream, service. 리드에서는 모든 크루 멤버도 함께 점검합니다.

초록색 상태는 정상입니다.
황색은 알아둘 가치가 있으며 진행을 차단하지 않습니다. 크루 전반의 버전 불일치, 일반적이지 않은 설치 유형, 출시되었으나 적용되지 않는 메이저 버전 등이 여기에 해당합니다. 체크아웃 내의 추적되지 않는 임시 파일은 녹색 상태를 유지합니다.
빨간색 상태는 업데이트를 차단합니다. 해당 줄에는 빨간색 collie doctor, 스테이징 빌드를 위한 1GB 미만의 여유 공간, 호스트에 bun 없음, 업스트림에 접근할 수 없음 등 이유가 명시됩니다. 단일 명령으로 해결할 수 있는 경우 카드는 해당 명령을 Fix: <command>로 출력합니다.

<version>(으)로 업데이트을 탭하면 한 번 확인을 요청하며, 확인 텍스트의 내용은 문자 그대로 적용됩니다. 터미널 세션은 유지되고 휴대폰 화면은 최대 30초 동안 끊깁니다. 재시작 시 멀티플렉서가 아닌 브리지가 종료되므로 에이전트는 계속 실행되며 휴대폰은 새 버전으로 다시 연결됩니다. 메이저 버전은 일반 업데이트로 진행되지 않습니다. 메이저 버전 전환 시 별도의 확인을 거치며 버전을 새 메이저로 명시하고 릴리스 노트를 먼저 읽도록 안내합니다.

실행되는 동안 시트가 화면을 차지합니다. 아래의 업데이트가 실행되는 동안 휴대폰에 표시되는 내용 항목을 참조하십시오. Updates 페이지의 카드는 동일한 상태를 더 자세히 전달합니다.

State	의미
`preflight`	이 머신을 확인하는 중입니다. 변경된 사항은 없습니다.
`staging`	이전 버전 옆에 새 버전을 빌드하거나 다운로드하는 중입니다.
`restarting`	브리지가 의도적으로 중단되었습니다. 장애가 아닙니다.
`verifying`	새 버전의 응답을 기다리는 중입니다.
`done`	새 버전이 응답했습니다.
`rolled-back`	새 버전이 응답하지 않아 업데이트 프로그램이 이전 버전으로 되돌렸습니다.
`stuck`	두 버전 모두 응답하지 않았습니다. 자동으로 다시 시작되지 않습니다.
`interrupted`	완료되기 전에 실행이 중단되었습니다. 불완전하게 설치된 항목은 없습니다.

처음 네 개는 진행 상황입니다. 카드에 해당 내용이 표시되며 화면을 열어 두라는 안내가 나타납니다. rolled-back에는 현재 유지 중인 버전이 표시되고, 서비스 로그의 끝부분이 나타나며, 다시 시도 옵션을 제공합니다. stuck는 터미널에서 실행할 단일 명령어를 출력합니다. interrupted는 다시 시도도 함께 제공합니다.

다음 요약 때 다시 알림는 카드의 알림을 닫습니다. 음소거가 아닙니다. 다음 푸시는 더 최신 릴리스와 새로운 주기가 모두 충족될 때까지 대기합니다.

알림 주기. 업데이트 푸시는 다이제스트 방식이며, 하루에 최대 한 번 호스트 로컬 시간 기준 09:00 이후에만 전송됩니다. 패치 릴리스로만 구성된 변경 사항은 대신 주간 윈도우를 기다리므로, 패치 트레인은 네 번으로 나누어지지 않고 한 번의 푸시로 도착합니다. 마이너 또는 메이저 릴리스는 일일 주기를 유지하며 대기 중인 패치를 함께 전달합니다. 보류된 릴리스는 하나로 합쳐지며 절대로 누락되지 않습니다. 패치에서도 일일 주기를 요청할 수 있습니다. 당일 즉시 적용해야 하는 수정 사항은 빌드 시 긴급으로 표시되며, 업데이트 카드에 이유를 설명하는 한 문장과 함께 긴급 레이블이 표시됩니다. 릴리스 시점 또는 릴리스 이후 다음 09:00에 알림을 받습니다. 긴급 릴리스가 하나라도 있으면 대기 중인 전체 트레인이 일일 주기로 전환되며, 버전 번호는 여전히 일반 패치로 유지됩니다. 이 기능이 추가되기 전에 설치한 환경은 한 번 업데이트될 때까지 긴급 패치에 주간 윈도우를 유지합니다. 윈도우와 관계없이 카드는 항상 현재 상태를 표시합니다. Settings → notifications (Web Push)에 있는 updates 알림 설정이 유일한 비활성화 스위치입니다.

크루 리드에서는 버튼에 크루를 <version> 버전으로 업데이트이 표시되며, 한 번의 확인으로 모든 머신에 적용됩니다. 리드가 자체 헬스 게이트에 따라 먼저 업데이트됩니다. 그런 다음 각 피어가 자체 사전 점검, 헬스 게이트, 롤백을 사용하여 순차적으로 동일한 릴리스로 버전을 맞춥니다. 피어별 버튼이나 두 번째 확인 프롬프트는 없습니다. 자세한 내용, 두 가지 복구 경로, 휴대폰으로 해결할 수 없는 한 가지 사례는 나머지 크루 업데이트을 참조하십시오.

모든 화면 상단의 띠에는 실행 중인 작업 대신 대기 중인 상태가 표시됩니다. 제공되는 릴리스, 업데이트할 수 없는 피어, 현재 사용 중인 앱이 bridge보다 이전 버전일 때의 New version — tap to update 등이 포함됩니다. 실행 중인 업데이트는 상단 띠가 아니라 시트에 표시됩니다.

업데이트가 실행되는 동안 휴대폰에 표시되는 내용

확인을 탭한 기기에서는 시트가 화면을 차지하고, 다른 모든 기기에는 배지가 표시됩니다.

시트에는 lead를 시작으로 머신당 한 행씩 버전 및 현재 상태가 표시됩니다. 그 아래에는 머신이 아닌 현재 사용 중인 앱에 관한 이 기기 자체의 행이 표시됩니다. bridge가 새 버전을 제공하면 휴대폰이 백그라운드에서 해당 앱을 가져오며, 행에는 파일이 도착할 때마다 개수가 표시됩니다. 시트에는 업데이트가 머신에서 실행되며 앱을 닫아도 업데이트가 중지되지 않는다는 내용이 작은 글씨로 한 번 표시됩니다.

실행을 시작한 기기는 시트 뒤에 있는 앱을 사용할 수 없습니다. 그 외에는 아무것도 차단되지 않습니다. 두 번째 휴대폰이나 태블릿에는 탭하여 열 수 있는 한 줄이 표시되며 다시 닫힙니다.

모든 머신의 작업이 끝나고 휴대폰에서 새 앱이 실행되면 시트가 자동으로 닫히고 짧은 메시지로 버전을 알립니다. crew에서는 Crew updated to <version>으로 표시되고, 단일 머신에서는 해당 머신의 이름이 대신 표시됩니다.

크루 업데이트 재시도과(와) 같이 멤버만 업데이트하는 실행도 동일한 방식으로 화면을 차지합니다. lead는 해당 실행의 일부가 아니며 재시작되지 않으므로 lead 행에는 already up to date이(가) 표시됩니다. 끝에는 Members updated to <version>이(가) 표시되며, 업데이트하지 못한 멤버가 있으면 실행을 시작한 휴대폰에 이유와 함께 시트가 열린 상태로 유지됩니다.

세 가지 상태가 정지될 수 있으며, 각각 해결 방법이 있습니다. 어떤 방법도 업데이트를 취소하지 않으며, 앱을 다시 로드하지도 않습니다.

표시되는 항목	의미	조치 방법
머신의 `last seen <time> ago`	해당 머신이 lead에 응답하지 않습니다.	이유를 확인하려면 Updates 확인을 참조하거나 그대로 두십시오.
다운로드 중입니다. 현재 앱을 계속 사용하십시오…	휴대폰 자체 다운로드가 2분 동안 진행되지 않았습니다.	앱을 계속 사용하십시오. 다운로드를 계속 진행합니다.
계속 작업 중입니다. 아직 문제 없습니다…	실행이 3분 동안 단일 상태를 유지했습니다.	계속 기다려 주십시오. 실행을 계속 진행합니다.

참고. "다운로드 중입니다. 앱을 계속 사용하십시오"는 휴대전화의 앱에 해당하는 내용이며 머신과는 무관합니다. 머신 작업은 완료되었으며, 새 앱이 아직 도착하지 않은 것뿐입니다. 사용 중인 앱은 계속 작동하며 다운로드가 완료되는 즉시 자동으로 전환됩니다.

터미널에서 실행

collie update --check            # read-only preflight, --json for a script
collie update --check --local    # the same, this instance only, no crew members
collie update                    # stage, flip, restart, verify
collie update --status           # what the updater did, or is doing, --json for a script
collie update --rollback         # put the previous version back
collie update --major            # cross one major, see below

collie update --help 명령은 사용법을 출력하고 아무것도 시작하지 않습니다. 모든 collie 명령은 작업을 수행하기 전에 -h 및 --help에 동일한 방식으로 응답합니다.

Herdr로 관리되는 설치 환경에서는 동일한 동작이 Herdr 액션으로 수행됩니다.

herdr plugin action invoke update --plugin herdr.collie      # Herdr-managed
bin/collie update                                            # Standalone

collie update --check은(는) 아무것도 변경하지 않습니다. collie doctor을(를) 실행하고, 여유 공간, bun 버전, 작업 트리, 업스트림 릴리스 목록, 서비스 유닛을 읽으며, 리드에서는 자체 SSH를 통해 모든 crew 멤버에게 동일한 내용을 질의합니다. 이상이 없으면 0으로 종료되며, --json은(는) 버전이 지정된 보고서를 출력합니다. 이 인스턴스만 확인하고 crew 멤버를 건너뛰려면 --local을(를) 추가하십시오. 휴대폰은 자체 호스트에서 해당 로컬 검사를 실행하고 crew 링크를 통해 각 피어의 줄을 읽으므로 사전 검사에 SSH가 필요하지 않습니다.

collie update는 현재 메이저의 최신 릴리스를 가져와 준비합니다. 재시작 시 업데이트를 요청한 브리지가 종료되므로, 이 명령어는 교체 작업을 별도의 업데이트 프로그램에 넘기고 종료됩니다. 해당 업데이트 프로그램은 current가 새 버전을 가리키도록 설정하고, 새 바이너리를 통해 다시 시작한 후, 방금 설치한 버전을 포함한 응답이 오는지 최대 30초 동안 GET /api/health를 폴링합니다. 응답이 오지 않거나 이전 버전에서 응답이 오면 current를 다시 되돌리고 한 번 더 재시작한 뒤, 서비스 로그의 끝부분과 함께 rolled-back를 기록합니다. 이마저도 실행되지 않으면 직접 실행할 명령어와 함께 stuck를 기록하며, 더 이상 자동으로 재시작되지 않습니다. 롤백은 한 번만 수행되며 두 번 수행되지 않습니다.

머신에서 30초로 부족하다면 COLLIE_UPDATE_HEALTH_TIMEOUT_MS를 설정하십시오. 허용 시간을 초과하는 느린 콜드 스타트는 업데이트 실패로 간주되어 롤백됩니다.

collie update --status는 업데이트 프로그램이 유지하는 기록을 출력하며, 모바일 기기도 동일한 기록을 읽습니다. 메인 포트가 다운된 동안 deputy의 대기 도어가 /standby/update에서 이를 제공합니다.

새로운 beacon 훅 이벤트가 제공되면, update이(가) hooks install claude을(를) 다시 실행하라는 안내를 출력합니다.

업데이트, 롤백 또는 전환이 성공할 때마다 새 빌드가 collie skill sync 명령을 실행합니다. 이 머신의 모든 에이전트 하네스에 walky talky 스킬을 설치하고 구버전 복사본을 업데이트하여, 에이전트가 현재 실행 중인 빌드를 알 수 있도록 합니다. 변경된 파일당 한 줄씩 출력하며 업데이트를 실패로 처리하지는 않습니다. 실행할 수 없는 경우 update 명령이 안내를 하나 출력하고 사용자가 수동으로 collie skill sync 명령을 실행합니다. 사용자가 collie skill uninstall 명령을 실행한 하네스는 제외됩니다. 지침 파일을 그대로 유지하려면 COLLIE_SKILL_SYNC=off 변수를 설정하십시오. 이 경우 스킬이 구버전일 때 업데이트 시 안내만 출력됩니다(스킬 설치).

버전이 저장되는 위치

바이너리 설치와 연결된 클론은 설치 루트(바이너리 설치의 경우 ~/.local/share/collie 또는 $COLLIE_DIR, 체크아웃의 경우 클론 자체) 아래에서 동일한 레이아웃을 공유합니다.

current -> versions/v1.3.0
versions/v1.3.0/
versions/v1.2.0/

체크아웃 환경에서 각 versions/vX.Y.Z는 릴리스 태그의 git worktree이며 단일 .git를 공유하므로, 버전 추가 시 두 번째 객체 저장소가 아닌 트리 하나만큼의 공간만 사용됩니다. 빌드는 새 디렉터리 내부에서 실행되고 마지막에 완료 마커를 기록합니다. 해당 마커가 없으면 전환이 거부되므로 빌드가 중단되어도 현재 실행 중인 버전은 변경되지 않습니다. 라이브 전환은 current 심볼릭 링크의 이름을 한 번 바꾸는 작업입니다. 보존 정책에 따라 current 및 최신 이전 버전 2개가 유지되며, 성공적인 실행 시에만 정리가 수행되므로 롤백 대상이 필요할 수 있는 실행에서는 해당 대상이 제거되지 않습니다.

Herdr 관리형 체크아웃은 예외이며 해당 위치에서 계속 업데이트됩니다(ADR 0006, 2026-09-03 개정). 분리된 얕은 복제본(shallow)이며 Herdr가 소유한 디렉터리에 위치하므로, 옆에 versions/ 레이아웃이 없고 인계할 대상이나 되돌릴 대상이 없습니다. 여기서는 --rollback가 거부되며, 복구 경로는 지정된 태그의 재설치(herdr plugin install AltanS/collie --ref vX.Y.Z --yes)입니다.

1.8.0에서 1.7.0으로 롤백하려면 상태 디렉터리에서 두 번의 수동 편집이 필요합니다. 1.8.0은 최초 시작 시 세 개의 상태 파일 이름을 변경하므로 ~/.local/state/collie/은(는) 이제 crew-trust.json, crew-ops.json, crew-runtime.json을(를) 보관하며, 1.7.0 빌드는 이전 이름만 읽습니다. 1.7.0 빌드를 시작하기 전에 세 파일의 이름을 모두 원래대로 변경하십시오.

cd ~/.local/state/collie
mv crew-trust.json pack-trust.json
mv crew-ops.json pack-ops.json
mv crew-runtime.json pack-runtime.json

그런 다음 pack-trust.json 내부의 두 키 이름을 편집하십시오. 1.8.0은 두 가지 철자 중 하나로 crew 블록을 읽고 "crew" 및 내부의 "crewId" 형태로 다시 기록하지만, 1.7.0은 "pack" 및 "packId"을(를) 기록했습니다. 1.7.0 빌드는 자체 철자만 읽으므로, 1.8.0이 저장소를 기록한 후(참여, 순환, warrant 갱신, 제거 시 수행됨) 해당 블록의 이름을 다시 "pack"로, id 필드를 다시 "packId"로 변경하십시오. 세 파일 내부의 다른 항목은 변경되지 않았으며, crew-ops.json 및 crew-runtime.json은(는) 편집할 필요가 없습니다. 파일을 수정하지 않으려면 업데이트 전에 생성한 pack-trust.json 사본을 복원하거나 1.8.0을 유지하십시오. 트러스트 저장소를 읽을 수 없는 1.7.0 빌드는 단독으로 시작되며 로스터를 강제하지 않습니다.

반대로 1.9.0으로 직접 이동할 때도 동일한 두 가지 수동 수정 작업이 필요합니다. 1.8.x는 최초 시작 시 3개의 파일 이름을 자동으로 변경했지만, 1.9.0은 파일 이름을 변경하지 않습니다. 따라서 1.8.x를 거치지 않은 상태 디렉터리에는 1.7.0 이름이 그대로 남아 있으며, 1.9.0 빌드는 crew 이름만 읽습니다. 시작 시 이 내용이 표시되고 변경할 두 항목을 안내하며, 디렉터리를 적용하는 대신 단독 상태를 유지합니다. 시작하기 전에 다음 작업을 먼저 수행하십시오:

cd ~/.local/state/collie
mv pack-trust.json crew-trust.json
mv pack-ops.json crew-ops.json
mv pack-runtime.json crew-runtime.json

그런 다음 crew-trust.json 내부의 키 이름 두 개를 변경하십시오. "pack" 블록은 "crew"가 되고, 그 안의 모든 "packId"는 "crewId"가 됩니다. 세 파일의 나머지 내용은 변경되지 않습니다. 이전 이름으로 남겨진 파일이 있어도 데이터는 손실되지 않으며 crew에만 영향을 줍니다. 이름을 바꿀 때까지 해당 collie는 단독으로 실행됩니다.

확인

bin/collie update --status
herdr plugin action invoke version --plugin herdr.collie
bin/collie version

최신 태그가 필요합니다.

모바일 자체 번들는 별개의 항목입니다. PWA는 자체적으로 새 빌드를 확인하고 약 1분 이내에 다시 로드하며, 업데이트 실행 중에는 해당 다시 로드를 보류합니다. 작업 중간인 경우 "탭하여 업데이트" 배너를 표시하고 사용자의 탭을 기다립니다.

Windows 환경

소스 체크아웃 환경에서는 Windows에서 소스 체크아웃은 자체 업데이트를 수행하지 않지만, zip 설치본은 자체 업데이트를 수행합니다. collie update 및 휴대폰의 업데이트 버튼에 한 문장으로 안내가 표시되며 아무것도 변경되지 않습니다. zip 설치본으로 전환하는 작업은 1회성 수동 절차입니다.

collie uninstall
powershell -ExecutionPolicy Bypass -File .\install.ps1

그 후에는 터미널과 휴대폰에서 collie update이(가) 작동합니다. 해당 절차는 릴리스 파일의 로컬 복사본을 대상으로 Windows 11 VM에서 사전 검증되었으나, 이동 작업 자체는 검증되지 않았습니다. v1.15.0 이하의 릴리스는 실행 중인 collie.exe을(를) 교체할 수도 없었습니다. Windows 환경의 Collie을(를) 참조하십시오.

버전이 변경되지 않은 경우

collie update은(는) 실행할 때마다 GitHub에 직접 요청합니다. 체크아웃의 경우 git ls-remote을(를), 바이너리 설치의 경우 GitHub 태그 API를 사용합니다. 릴리스 목록을 캐시하지 않습니다. GitHub 자체에서 반영하는 데 시간이 걸릴 수 있으므로 방금 게시된 릴리스라도 표시되는 데 1분 정도 걸릴 수 있습니다. 그다음에 collie doctor을(를) 실행하십시오. 그래도 해결되지 않으면 collie가 실행되지 않을 때을(를) 참조하십시오.

GitHub에서 릴리스 확인 속도를 제한하는 경우

바이너리 설치 환경의 collie update은 GitHub API를 통해 릴리스 목록을 조회하며, 휴대폰의 업데이트 배너와 install.sh도 마찬가지입니다. GitHub는 익명 호출자에게 네트워크 주소당 시간당 60회의 API 호출을 허용하므로, 하나의 라우터 뒤에 있는 모든 머신이 이 한도를 공유합니다. 한도가 소진되면 검사는 안전 모드로 실패하며 아무것도 변경하지 않습니다.

error: GitHub rate-limited the release check (HTTP 403). Wait an hour, or set GH_TOKEN
       to a GitHub token with no scopes, so the limit is yours (docs/upgrading.md).
       Nothing was changed.

토큰을 사용하면 한도가 사용자 전용으로 적용됩니다. Collie는 환경 변수에서 토큰을 읽으며 이를 직접 요청하지 않습니다.

이름	설정 주체
`COLLIE_GITHUB_TOKEN`	서비스용 직접 설정: 인스턴스의 `.env`, 또는 `config.toml`의 `[update]` 아래에 있는 `github_token`
`GH_TOKEN`	`gh` CLI 자체 이름
`GITHUB_TOKEN`	GitHub Actions

먼저 설정된 값이 적용됩니다. 태그 목록은 공개되어 있으므로 토큰에 권한 없음만 있으면 됩니다. 저장소 접근 권한이 Public repositories (read-only)로 설정되고 아무 권한도 선택되지 않은 세분화된 개인 액세스 토큰이거나, 아무 스코프도 선택되지 않은 클래식 토큰이어야 합니다. 어떤 항목이든 쓰기 권한이 있는 토큰은 사용하지 마십시오.

터미널에서 1회 실행하는 경우 gh CLI의 자격 증명을 빌려 사용합니다. 이 값은 명령줄이나 셸 기록에 절대 남지 않습니다.

GH_TOKEN=$(gh auth token) collie update

서비스의 경우, Collie가 모드 600으로 유지하는 인스턴스 .env에 넣거나 [update] 아래의 config.toml에 넣고 다시 시작하십시오. 브리지는 시작될 때 토큰을 읽으므로 휴대폰의 배너는 collie restart 이후에만 새로 설정되거나 변경된 토큰을 사용합니다. collie config에는 이 값이 set 또는 unset로 표시되며 실제 값은 절대 출력되지 않습니다. 토큰은 api.github.com에만 전송됩니다. 릴리스 다운로드는 이러한 한도가 없는 github.com에서 이루어지며 토큰을 전달하지 않습니다. 토큰을 언급하는 메시지에는 토큰이 제공된 변수 이름만 표시되며 실제 값은 절대 표시되지 않습니다. GitHub에서 거부된 토큰은 HTTP 401 및 해당 이름과 함께 검사에 실패하므로, 잘못된 토큰을 요청 한도 초과로 오인하지 않습니다. 브리지는 로그에 이 내용을 한 번 기록한 다음 마지막으로 확인된 릴리스를 유지하므로, 토큰 만료 후 배너가 갱신되지 않는 현상은 해당 로그 라인을 의미합니다. collie update --check 명령으로 언제든 이를 확인할 수 있습니다.

collie update --check는 upstream 아래에 동일한 세 가지 사례를 보고합니다. 체크아웃 환경은 대신 git ls-remote를 사용하여 태그 목록을 가져오며, 이는 API 한도에 포함되지 않습니다. crew 내에서는 모든 머신이 자체 토큰을 읽습니다. 멤버는 자체 .env에서 자체 collie update를 실행하여 업데이트합니다.

메이저 버전 업그레이드

update은(는) 메이저 버전을 자동으로 넘기지 않습니다.

herdr plugin action invoke update-major --plugin herdr.collie     # Herdr-managed
bin/collie update --major                                         # Standalone

한 메이저 버전을 올려 해당 버전의 가장 최신 릴리스로 진행합니다. 프리릴리스(ADR 0020)는 대상으로 하지 않습니다. 참고: 0.x에서 1.0으로 업그레이드.

"You are not currently on a branch" 오류가 발생하며 실패하는 경우

0.23.1 이전 GitHub 설치본에는 브랜치 추적 ref(#63)가 없습니다. 업데이트 기능을 복원하려면 다시 설치하십시오.

# replaces the checkout, rebuilds the UI
herdr plugin install AltanS/collie --yes
# reinstall doesn't restart the service
herdr plugin action invoke restart --plugin herdr.collie
# expect 0.23.1 or newer
herdr plugin action invoke version --plugin herdr.collie

Herdr의 플러그인 설정 디렉터리에 있는 설정(관례상 ~/.config/herdr/plugins/config/herdr.collie)은 유지됩니다.

나머지 크루 업데이트

collie crew update <member>…      # on the lead
collie crew update --all

이것이 휴대폰에서 동기화할 수 없는 피어를 위한 터미널 경로입니다. 휴대폰에서는 탭 한 번과 한 번의 확인으로 전체 크루를 업데이트할 수 있습니다. 리드에서 설정 → 시스템 → 업데이트을 열고 크루를 <version> 버전으로 업데이트을 선택하십시오. 버튼 위의 사전 점검은 리드뿐만 아니라 모든 멤버를 대상으로 합니다. 어느 곳에서든 점검 결과가 빨간색이면 버튼이 비활성화되고 실패한 머신과 이유가 표시됩니다.

리드가 자체 헬스 게이트에 따라 먼저 업데이트됩니다. 리드가 안정화된 후에만 첫 번째 피어가 시작됩니다. 1.7.0부터는 이러한 순서가 표기 측면에서도 중요합니다. 1.7.0 미만의 리드는 첫 번째 출력 라인으로 멤버의 상태를 읽는데, 1.6.0 멤버가 pack …을 출력하던 위치에 1.7.0 멤버는 crew …을 출력하므로 업데이트되지 않은 리드는 이를 읽을 수 없습니다. 1.7.0 리드는 둘 다 읽습니다. 그런 다음 각 피어는 자체 방식으로 버전을 맞춥니다. 즉, 리드가 실행 중인 릴리스를 읽고, GitHub에서 정확히 일치하는 태그를 가져와 자체 사전 점검, 헬스 게이트 및 롤백을 실행합니다. 피어는 한 번에 하나씩 처리됩니다. 업데이트 페이지는 멤버당 한 줄씩 상태를 유지합니다: waiting, checking, staging, restarting, verifying, updated, rolled back 또는 unreachable.

멤버는 최대 한 시간에 한 번 자체 업데이트를 수행합니다. 예를 들어 수동으로 한 시간 이내에 업데이트된 멤버는 라인 아래에 rate-limited, retries in about N min 표시가 뜬 채 대기하며, 해당 시간이 지나면 실행이 계속됩니다. 리드 자체의 업데이트가 롤백되면 멤버는 변경되지 않고 라인에 해당 상태가 표시됩니다. 새 업데이트는 크루 실행이 끝날 때까지 대기하며, 최대 대기 시간은 2시간입니다.

1.7.0에서 1.8.0으로. 두 번째 이유로 인해 다시 lead를 먼저 진행합니다. 1.8.0은 wire 경로, 두 환경 변수 키, 세 상태 파일 및 저널 접두사를 crew로 바꿉니다. 1.8.0 lead는 한 릴리스 동안 이전 /pack/v1/* 경로에 응답하므로, 여전히 1.7.0에 있는 member는 이미 보유한 링크를 통해 롤아웃을 따릅니다. 두 이전 표기는 1.9.0에서 제거됩니다. 해당 이름들과 각 이름이 시스템에서 수행하는 작업은 1.7.0 또는 1.8.x에서 1.9.0으로 업데이트에 있습니다. lead를 1.9.0으로 이동하기 전에 모든 member를 1.8.x로 전환하십시오. 1.9.0은 이전 경로에 응답하지 않으며, 여전히 1.7.0에 있는 member는 lead의 사전 점검에서 빨간색으로 표시되어 두 버전과 해당 시스템에서 실행할 명령을 보여줍니다. 릴리스가 게시하는 collie-release.json 에셋은 상단 띠, Updates 카드, 일일 푸시 알림의 안내 문구를 제공하며, 업데이트가 수행하는 작업을 절대 변경하지 않습니다. 또한 확인 작업에 릴리스가 출시되었음을 알립니다. 에셋이 여전히 404를 반환하는 태그는 제공되지 않으며 다음 확인 시 다시 요청합니다.

peer가 따라갈 수 있는지 여부는 두 가지 요구 사항에 따라 결정됩니다.

peer에는 github.com로 향하는 아웃바운드 HTTPS가 필요합니다. 해당 머신의 코드가 제공되는 위치입니다. 해당 접근 권한이 없으면 피어는 뒤처진 상태로 보고되며, 위의 명령을 사용하여 터미널에서 대신 동기화됩니다.
-dev+ 빌드는 절대로 따라가지 않습니다. 개발 빌드를 사용하는 머신은 lead가 무엇을 실행하고 있든 해당 빌드를 유지합니다.

롤백된 peer는 Updates 페이지에 해당 사실을 표시하며 자체적으로 재시도하지 않습니다. 두 가지 경로를 통해 다시 시도할 수 있습니다.

휴대전화에서 실행하는 경우. lead가 최신 상태이고 peer가 뒤처지면 버튼에 크루 업데이트 재시도이 표시됩니다. peer만을 대상으로 하는 새 실행을 시작하며, 이 새 실행을 통해 각 peer에 한 번 더 시도할 기회가 부여됩니다.
lead의 터미널에서 실행하는 경우. 휴대전화로 전혀 수준을 맞출 수 없는 peer에 사용합니다. 명령어는 동일합니다.

collie crew update <member>…      # on the lead
collie crew update --all

lead에서 실행하면 사용자의 SSH를 통해 일련의 과정이 진행됩니다. 먼저 모든 머신에 대해 사전 검사를 수행하고, SSH를 통해 받은 응답 옆에 각 피어의 자체 보고서를 함께 출력하여 불일치 사항을 평균화하지 않고 명확하게 드러냅니다. 한 번의 동의를 요청합니다. 그런 다음 lead가 배포 중인 빌드를 아직 실행하고 있지 않다면 lead 자체를 먼저 업데이트합니다. 다음으로 각 피어를 차례대로 처리합니다. 피어에 git bundle 형태로 lead의 커밋이 푸시되고, 다시 빌드된 후 다시 시작되며, 동일한 30초 예산 내에서 새 빌드로 응답할 때까지 상태를 확인합니다. 독립 실행형 설치나 패키지 설치로 인해 git 체크아웃이 없는 lead는 푸시할 커밋이 없으므로, 동일한 ssh를 통해 자신이 실행 중인 릴리스를 해당 태그로 고정하여 각 피어에 대신 설치합니다. 이때 git 체크아웃에서 실행 중인 피어는 건너뛰며 해당 행에 collie update --to-tag v<version>가 표시됩니다.

첫 번째 실패가 발생하면 실행이 중단됩니다. 그 뒤의 모든 멤버는 수정되지 않은 채 "시도되지 않음"으로 보고되며, 요약에는 실패를 해결하는 단일 명령어가 표시됩니다. 자체 업데이트를 적용하지 못한 리드는 어떤 피어도 건드리지 않습니다. 크루는 버전 불일치(CREW_PROTOCOL.md §7.1)를 허용하므로 여기서 중단하는 것이 안전합니다. 즉, 절반만 업데이트된 크루는 지원되는 상태이지만 무리하게 계속 진행하는 것은 지원되지 않습니다.

휴대전화로 해결할 수 없는 한 가지 사례. peer들이 동기화된 후 git을 사용하거나 파일을 복사하여 lead를 수동으로 롤백하면, peer들은 lead보다 앞선 상태로 남습니다. Collie는 롤백을 감지하지 못하므로 어떤 member도 다운그레이드되지 않습니다. 휴대폰의 롤백 또는 collie update --rollback로 수행한 롤백과 Stable로의 복귀는 member를 다운그레이드합니다. 릴리스 라인 아래의 "The crew follows the lead"를 참조하십시오. member를 하위 버전으로 이동하는 것은 이 두 실행뿐입니다. peer를 임의로 다운그레이드할 수 있는 lead는 peer를 어떤 버전으로든 이동할 수 있기 때문입니다. 수동 롤백으로 인한 불일치는 무해하며, 해결책은 lead에서 collie crew update <member>를 실행하는 것입니다.

코드는 사용자의 SSH를 통해 피어에 도달하며 크루 링크를 통해서는 전달되지 않습니다(ADR 0016, 2026-09-04 부록). 피어가 자체적으로 레벨을 맞출 때, 해당 코드는 익명 HTTPS를 통해 GitHub에서 가져오며 피어가 직접 결정합니다. 리드는 자신이 실행 중인 버전과 어떤 피어가 진행해도 되는지만 명시합니다.

업데이터 자체가 종료되는 경우

업데이터가 사라지면 위의 내용 중 어떤 것도 도움이 되지 않습니다. 이는 터미널만 사용 가능하다고 가정하는 경로입니다.

업데이터는 하나의 레코드인 <state dir>/update.json(기본값은 ~/.local/state/collie/update.json, 또는 $COLLIE_STATE_DIR 하위)을 기록합니다. 먼저 이 파일을 읽으십시오. 상태, 실행 시작 버전, 목표 버전, 업데이터의 pid가 명시되어 있으며, 실패 시 서비스 로그의 마지막 부분과 복구 명령어가 포함되어 있습니다.

휴대폰에서 시작한 업데이트는 터미널에 전혀 출력되지 않습니다. systemd 사용자 관리자가 있는 Linux에서는 collie-api-update-<stamp>라는 이름의 자체 임시 유닛 아래에서 실행되며, 종료되는 즉시 --collect이(가) 해당 유닛을 제거하므로 실행 기록은 저널에만 남습니다.

journalctl --user -u 'collie-api-update-*' --since '30 min ago'

macOS를 포함한 다른 모든 환경에서는 업데이트 도구 자체의 출력이 상태 디렉터리 내 파일로 저장됩니다.

cat ~/.local/state/collie/update-runner.log

휴대폰에서 업데이트를 시작할 때마다 해당 파일을 비우고 이전 실행 기록을 update-runner.log.1(으)로 유지합니다. systemd 환경에서 이 파일에는 systemd-run이(가) 출력하는 한 줄만 저장되며, 나머지 내용은 위의 저널에 남습니다.

crew 업데이트 후에도 crew 멤버가 이전 버전에 남아 있을 수 있습니다. 이때 해당 checkout에는 새 태그가 표시되지만, /standby/health 또는 바닥글에는 여전히 이전 빌드가 표시됩니다. systemctl --user list-units 'collie-api-update-*' 명령으로 실행 중인 업데이트 프로세스가 없는지 확인하십시오. 실행 중인 프로세스가 없다면 해당 머신에서 collie update 명령을 실행하십시오. 빌드가 완료되지 않은 checkout을 다시 빌드합니다.

전환 전에 중단된 실행(예: 이 머신에서 시작되지 않는 새 버전)은 디스크의 어떤 내용도 변경하지 않습니다. 업데이트를 시작한 휴대폰에는 해당 머신에서 업데이트가 실패했다는 메시지와 이유가 표시되며, 동일한 이유가 update.json의 reason 필드에 기록됩니다.

휴대폰에서 성공을 보고했으나 다운스트림에서 작업이 진행되지 않았을 때 확인해야 할 위치입니다. 예를 들어 실행 기록을 쓸 수 없다는 경고가 발생했다면, 이는 리드가 자체 업데이트되었으나 크루의 레벨을 맞추지 않는 경우입니다. 브리지 자체 저널에는 나머지 절반이 기록됩니다. 리드가 기록을 가져올 때 실행당 하나의 [crew] update <run id>: levelling peers to <version> 줄이 남습니다. 1.8.0 이전에는 해당 접두사가 [pack]였습니다. 해당 줄이 없다면 턴이 전혀 시작되지 않은 것입니다.

bunx에서 멈추는 1.5.4 이전 버전의 업데이트

1.5.4 이전 버전에서는 휴대전화에서 시작된 업데이트가 사용자의 PATH가 없는 임시 systemd 사용자 유닛에서 실행됩니다. 체크아웃 설치 환경에서 Bun이 ~/.bun/bin에만 존재하는 경우, 체크아웃은 진행되지만 다시 빌드할 때 bunx: command not found 오류가 발생하며 실패합니다. Bun이 PATH에 있는 터미널에서 collie update을(를) 한 번 실행하거나, 심이 직접 Bun을 찾는 Herdr 액션을 실행하여 이를 해결하십시오. 두 방법 모두 진행된 체크아웃을 다시 빌드합니다. 1.5.4 버전부터는 업데이터가 Bun을 직접 찾습니다.

그 옆에는 pid와 타임스탬프를 담고 있는 <state dir>/update.lock이 있습니다. 한 번에 하나의 실행만 허용됩니다. 상태가 여전히 preflight, staging, restarting, verifying 중 하나로 기록되어 있고, 10분 동안 변경되지 않았으며, 해당 pid가 프로세스 테이블에 더 이상 없다면 종료된 상태입니다. 이는 interrupted로 간주되며 새 실행이 락을 획득할 수 있습니다.

이전 버전을 수동으로 복원하려면 current이 이전 버전을 가리키도록 설정하고 재시작하십시오.

cd ~/.local/share/collie        # or $COLLIE_DIR, or the checkout root
ls versions/
ln -sfn versions/<previous> current
collie restart

또는 이전 버전이 동일한 작업을 자동으로 수행하도록 할 수도 있습니다. 이는 stuck 레코드에 포함된 명령어입니다.

~/.local/share/collie/versions/<previous>/bin/collie update --rollback

collie 대신 전체 경로를 사용하십시오. PATH에 있는 이름은 current을 통해 확인되며, 문제가 발생한 대상이 바로 current일 수 있습니다.

상태 게이트가 감지하지 못하는 항목

게이트는 한 가지만 검증합니다. 서비스가 다시 시작되었고 설치된 버전으로 /api/health에 응답했다는 점입니다. 이는 제한된 보증이며 "절대 벽돌이 되지 않음"을 의미하지 않습니다. 게이트가 성공을 보고하더라도 다음 네 가지 문제가 발생할 수 있습니다.

휴대폰의 오래된 웹 번들. 호스트는 새 버전이지만 휴대폰은 서비스 워커에서 이전 JavaScript를 계속 실행하고 있습니다. PWA는 자체 일정에 따라 자체 번들을 교체하므로 상태 게이트는 이를 파악할 수 없습니다.
설정 또는 스키마 마이그레이션. Collie는 이 주기에서 마이그레이션을 제공하지 않으며 업데이터도 실행하지 않습니다. 게이트는 서비스의 응답 여부만 확인하며 데이터 형식이 올바른지는 확인하지 않습니다.
상호작용 시에만 중단되는 mux 드라이버. 브리지가 시작되어 상태 검사에는 응답하지만, 어댑터가 최초의 실제 연결이나 전송 시 실패합니다. 상태 검사는 활성 상태 프로브일 뿐 적합성 테스트가 아닙니다.
이전 버전의 코드를 실행하는 업데이터. 분리된 업데이터는 교체 대상 버전에서 실행됩니다. 업데이터는 작고 안정적으로 유지되며 레코드에는 버전이 지정되므로, 이전 업데이터와 새 브리지가 여전히 서로를 인식할 수 있지만 이는 완화책일 뿐 완전한 보증은 아닙니다.

스크립트에서 최신 릴리스 확인

git 태그를 조회하고 semver 기준으로 정렬합니다. 사전 릴리스를 제외하는 GET /repos/AltanS/collie/releases/latest은(는) 피하십시오.

# newest stable release
git ls-remote --tags --refs https://github.com/AltanS/collie | \
  sed 's#.*refs/tags/##' | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1

릴리스 라인

각 시스템은 두 릴리스 라인 중 하나에 속합니다. 기본값은 Stable입니다.

Stable 라인은 최종 릴리스만 받습니다(예: 1.23.0).
Edge 라인은 Edge 빌드도 받습니다(예: 1.23.0-edge.2). Edge 빌드는 GitHub 프리릴리스로, 최종 릴리스 며칠 전에 동일한 트리에서 생성됩니다. 자원자에게 먼저 전달되므로 모든 사용자에게 배포되기 전에 회귀 결함을 발견할 수 있습니다.

휴대폰에서 라인을 설정하십시오: 설정 → Updates → 릴리스 라인. 전환 시 아무것도 설치되지 않습니다. 라인을 저장하고 영수증을 표시합니다. 그런 다음 Updates 카드에서 일반 업데이트 화면을 통해 새 라인이 제공하는 항목을 제안합니다.

Edge에서는 현재 실행 중인 빌드보다 최신인 빌드를 제안하며, Edge 빌드와 최종 릴리스가 동일한 메이저 버전 내에서 함께 제공됩니다. 최종 릴리스는 두 라인 모두에서 해당 버전의 Edge 빌드를 대체합니다.
해당 시스템에서 롤백된 빌드는 두 라인 모두에서 다시 제공되지 않습니다.
Edge에서는 새 빌드에 대한 푸시 알림이 다음 다이제스트가 아닌 다음 확인 시 발송됩니다. 단, 현지 시간 09:00까지 대기합니다. Stable은 다이제스트 주기를 유지합니다.

Edge에서 예상되는 주기. Edge 빌드는 하루에 최대 약 1회 제공되며, 각 빌드에는 확인할 수 있는 변경 사항이 포함됩니다. 브리지는 6시간마다 새 빌드를 확인합니다. 빌드당 한 번의 푸시 알림을 받으며, 호스트 현지 시간 09:00 이전에는 전송되지 않습니다. 한 번의 확인에서 여러 새 빌드가 발견되면 하나의 푸시 알림으로 통합됩니다. 업데이트 알림 띠는 빌드당 한 번 요청하며 빌드를 건너뛸 수 있습니다. 다음 업데이트 시 최신 빌드가 적용됩니다. 알림 띠를 닫는 동작은 해당 버전에만 적용되므로 다음 빌드에서 다시 요청합니다.

Stable로 돌아가기. Edge 빌드를 실행 중인 시스템에서 Stable로 전환하면 페이지에 세 가지 경우 중 하나가 표시됩니다.

현재 빌드 이상의 최종 릴리스가 출시되었습니다. Updates 카드에서 일반 업데이트로 제공합니다.
Edge 빌드가 모든 최종 릴리스보다 앞서 있습니다. 페이지에서 두 가지 선택지를 제공합니다: - 지금 돌아가기은 확인 절차를 거쳐 현재 빌드 미만의 최신 최종 릴리스를 설치합니다. 이 시스템이 보관한 Stable 빌드가 있으면 이를 사용하고, 없으면 다운로드합니다. 현재 빌드의 상태 파일을 해당 릴리스에서 읽을 수 없는 경우 페이지의 버튼 앞에 파일 이름이 표시됩니다. - Stable 대기은 현재 빌드를 유지합니다. 더 이상 Edge 빌드가 제공되지 않으며 다음 최종 릴리스가 출시되는 날 제공됩니다.
이미 최종 릴리스를 실행 중입니다. 수행할 작업이 없습니다.

보관된 빌드. 시스템이 Edge에 있는 동안에는 실행 중인 빌드, 이전 빌드, 마지막 Stable 빌드를 유지합니다. 마지막 Stable 빌드는 시스템이 다시 Stable로 돌아갈 때까지 정리되지 않으므로 "지금 돌아가기"는 다운로드가 아닌 전환으로 처리됩니다.

롤백. Edge 빌드에서 롤백하면 시스템이 Stable로 설정되고 해당 빌드는 롤백된 것으로 표시됩니다. 이는 휴대폰의 롤백 및 collie update --rollback에 적용됩니다. 자체 헬스 체크에 실패한 Edge 빌드는 업데이트 관리자에 의해 롤백되고 동일하게 표시되어 다시 제공되지 않습니다. 라인은 Edge로 유지되며 다음 Edge 빌드가 정상적으로 제공됩니다.

crew는 lead를 따릅니다. lead의 라인이 crew의 라인입니다. lead가 Edge에 있으면 member는 lead를 따라 Edge 빌드로 이동하고 lead의 라인을 자신의 라인으로 채택합니다. member는 lead가 롤백되었거나 Stable로 돌아간 경우에만 다운그레이드됩니다. member가 하위 버전을 설치하는 경우는 이 두 가지뿐입니다. Crew 페이지에 member들이 따르는 라인이 표시됩니다.

터미널에서 실행합니다. 휴대폰에서 라인을 설정합니다. 각각 1회 실행을 위한 두 개의 플래그가 있습니다:

collie update --line edge                     # resolve this one run on Edge; the saved line stays
collie update --to-tag v1.22.6 --downgrade    # go down to a lower final release

--to-tag은(는) --downgrade 없이는 더 낮은 태그를 적용하지 않습니다. Edge 환경의 머신에서만 더 높은 Edge 태그를 가져옵니다. Herdr로 관리되는 설치 환경에서는 두 라인과 복구 경로 모두 동일한 인플레이스 업데이트를 거칩니다. 업데이트 프로그램이 태그를 체크아웃하고 버전 파일에 Edge 접미사를 직접 기록합니다.

시험판

Stable 설치본은 프리릴리스를 받지 않습니다. Edge 빌드는 예외로, Edge 라인에서 적용됩니다(릴리스 라인 참조). 프리릴리스를 선택하면 최종 릴리스가 나올 때까지 해당 메이저 버전의 프리릴리스를 추적합니다(ADR 0020).

# Standalone — the install script's opt-in flag takes the newest prerelease
curl -fsSL https://colliepwa.dev/install.sh | sh -s -- --beta

# Herdr-managed — install the tag; that is the whole opt-in
herdr plugin install AltanS/collie --ref <tag> --yes
# a reinstall does not restart the service
herdr plugin action invoke restart --plugin herdr.collie

스크립트에서 최신 릴리스 확인을(를) 사용하여 <tag>을(를) 확인하십시오.

안정 릴리스로 돌아가려면 다음을 실행하십시오.

herdr plugin install AltanS/collie --yes
herdr plugin action invoke restart --plugin herdr.collie

1.24.0으로 업그레이드하기

버전 1.24.0에는 사용량 점 표시, 정지 버튼, 대형 화면 레이아웃이 추가되었습니다. 1.23.4에서 업그레이드하는 경우 당일 별도로 작업할 내용은 없습니다. 변경 사항은 다음과 같습니다.

Collie는 사용자의 statusLine을 변경하지 않습니다. 줄바꿈 적용은 collie hooks install claude --statusline 옵션으로 선택할 수 있습니다. Edge 빌드에서 가져온 줄바꿈 설정을 제거하려면 collie hooks uninstall claude을(를) 실행한 다음 collie hooks install claude을(를) 실행하십시오(Collie는 Claude 자체 설정에 훅을 작성합니다).
컨텍스트 점에는 새 훅이 필요하지 않습니다. 1.23.4에서 설치된 훅에는 이미 SessionStart이(가) 포함되어 있으며, 동일한 명령을 실행합니다. 새 Collie는 해당 훅을 사용해 세션 파일을 읽습니다. collie hooks install claude을(를) 실행한 적이 없다면 한 번 실행하십시오. 이미 실행 중인 Claude 세션은 창 크기가 세션 시작 시점에 결정되므로 다시 시작하거나 재개, 초기화 또는 압축하기 전까지 점이 표시되지 않습니다.
5시간 및 7일 점 표시는 로컬 로그인 정보를 읽습니다. Claude의 경우 Collie가 이 머신의 로그인 파일을 읽고 api.anthropic.com에 요청합니다. Codex의 경우 Codex 세션 파일을 읽으며 외부 요청을 보내지 않습니다. 둘 다 기본적으로 켜져 있습니다. 끄려면 .env에서 COLLIE_ACCOUNT_WINDOWS=0을(를) 설정하거나 [bridge] 아래에서 account_windows = false을(를) 설정하십시오. OpenCode Go와 Grok은 직접 지정할 때까지 꺼진 상태를 유지합니다(사용량 창).
정지 버튼, 지우기 버튼 및 조향 기능. 정지는 두 번 탭해야 작동하며 에이전트 자체 정지 키를 누릅니다(턴 중지). 지우기는 입력 상자를 비우며, 복원은 2분 동안 텍스트를 다시 입력합니다(입력창 비우기). pi, Codex, OMP에서 실행 중인 턴의 방향을 제어하려면 전송을 길게 누르십시오(Steer 또는 대기열 등록).
pane-active을(를) 설정하는 테마는 버전 3입니다. 1.24.0 미만 버전의 Collie는 해당 버전을 명시하는 메시지와 함께 해당 파일을 거부합니다. 다른 테마는 기존 버전을 유지합니다(버전).
넓은 화면에서는 사이드바가 표시됩니다. 너비 600px, 높이 480px 이상에서는 창 화면에 여러 창이 나란히 표시됩니다. 한 기기에서 모바일 레이아웃을 유지하려면 설정에서 대형 화면 레이아웃을(를) 꺼짐으로 설정하십시오.

1.19.0으로 업그레이드

버전 1.19.0에서는 실행 관련 기능이 단일 페이지로 통합되었으며, 각 휴대폰이 자체 Keys와 실행기를 구성할 수 있습니다. 업그레이드 당일에 별도로 수행할 작업은 없습니다. 변경된 사항은 다음과 같습니다.

New 시트가 페이지로 변경되었습니다. 대시보드의 + New을(를) 누르면 머신, Agent 또는 Command 선택 목록, 폴더 및 새 worktree 스위치가 포함된 /new이(가) 열립니다. new-space 시트, 해당 space 라벨 및 기존 worktree 목록은 제거되었습니다. 머신에서 herdr worktree open을(를) 사용하여 기존 worktree를 여십시오(휴대폰에서 에이전트 또는 셸 시작).
이름으로 에이전트를 시작하려면 crew member를 업데이트해야 합니다. 이전 버전의 Collie를 실행 중인 member는 선택 항목이 비활성화된 상태로 페이지에 표시됩니다. lead를 먼저 업데이트하면 member도 이어서 업데이트할 수 있습니다(시스템에서 작업 시작하기).
휴대폰에서 실행기를 추가할 수 있습니다. 기본값인 [phone] adds = true을(를) 사용하면 페어링된 휴대폰이 머신에 최대 20개의 행을 추가할 수 있으며, 이는 launchers-added.json에 보관됩니다. 이 기능을 끄려면 launchers.toml에서 adds = false을(를) 설정하십시오(휴대전화에서 추가된 실행기).
Keys 패드가 보드 형태로 변경되었습니다. 기존에 사용하던 패드 형태로 시작하며, 브라우저마다 고유한 배치를 유지합니다(사용자 정의 키 패드). keys.toml의 프리셋은 변경되지 않습니다.
경로 없는 폴더 이름은 홈 디렉터리 하위의 폴더를 의미합니다. 이제 Folder 필드의 projects은(는) ~/projects을(를) 의미하며, 존재하지 않는 폴더는 안내 메시지와 함께 거부됩니다.

1.18.0 버전으로 업그레이드

버전 1.18.0부터는 쓰기뿐만 아니라 읽기에도 페어링이 필수가 됩니다(ADR 0086). 업그레이드 당일 변경 사항:

페어링된 휴대폰은 계속 작동합니다. 저장된 토큰이 이미 새 규칙을 충족합니다. 수행할 작업이 없습니다.
페어링되지 않은 브라우저에는 페어링 화면이 표시됩니다. 이전에 읽기가 가능했던 페어링되지 않은 데스크톱 브라우저는 이제 403 device not paired을 받습니다. 호스트에서 collie pair를 실행한 다음 해당 브라우저의 Settings에 코드를 입력하십시오(기기 페어링).
설치된 앱은 한 번 더 로드할 때까지 이전 화면을 유지할 수 있습니다. 설치된 앱은 한 번 더 로드될 때까지 이전 버전의 화면을 계속 표시할 수 있습니다. 1.18 이상으로 업데이트한 후 "Sign in"이 표시되면 앱을 새로고침하거나 닫았다가 다시 여십시오. 그런 다음 위와 같이 페어링하십시오.
스크립트는 한 번 페어링해야 합니다. 토큰 없이 API를 읽던 스크립트는 이제 403을 받습니다. collie pair --expires 30d를 실행한 후 {"code": "...", "label": "script"} 및 동일 출처 Origin 헤더를 포함하는 POST를 /api/pair에 전송하여 코드를 요청하십시오. 토큰은 해당 응답에서 한 번 반환됩니다. 이후의 모든 호출에 Authorization: Bearer <token>으로 전송하십시오. 비밀번호처럼 저장하십시오.
호스트 CLI는 아무것도 필요하지 않습니다. collie doctor, collie history 및 크루 업데이트 스윕은 bridge가 상태 디렉터리에 쓰는 로컬 자격 증명을 사용하여 자체 bridge를 읽습니다.
1.18.0 미만으로 롤백하면 토큰 만료를 무시합니다. 이전 버전의 bridge는 expiresAt 필드를 인식하지 못하므로, 만료된 기기도 bridge가 업데이트될 때까지 다시 작동합니다. 필요한 경우 collie devices revoke <label>로 취소하십시오(기기에 만료 시간 설정).
이전 감사 파일에 입력된 문자가 남아 있을 수 있습니다. 1.18.0 이전에 작성된 파일에는 휴대폰에 입력된 문자가 나열될 수 있습니다. 업데이트 이전의 audit.log 파일을 교체하거나 삭제하십시오.
마스킹이 방해가 될 수 있습니다. 이제 Files의 파일 본문과 Changes의 diff가 창 텍스트와 동일한 시크릿 마스크를 통과합니다. 필요한 내용이 숨겨진 경우 .env에서 COLLIE_REDACT=off을 설정하고 다시 시작하십시오(구성).
1.18.0 리드는 멤버의 텍스트도 마스킹합니다. 1.17.x 버전에 머물러 있는 멤버는 마스킹하지 않으므로 휴대폰이 수신하기 전에 리드가 해당 멤버의 텍스트를 마스킹합니다. 마스킹되지 않은 멤버의 텍스트를 보려면 멤버뿐만 아니라 리드에서도 COLLIE_REDACT=off을 설정하십시오.

0.x에서 1.0으로 업그레이드

BUN_INSTALL이(가) .env에만 정의되어 있다면 셸 프로필이나 서비스 환경에서 대신 export 하십시오. 그런 다음 실행하십시오.

# Herdr-managed
herdr plugin action invoke update-major --plugin herdr.collie

# Linked clone
bin/collie update --major

bin/collie version 또는 herdr plugin action invoke version --plugin herdr.collie을(를) 통해 확인하십시오.

crew 설정의 경우: 리드를 먼저 업데이트한 다음 collie crew update <member>…을(를) 실행하십시오 (나머지 크루 업데이트). 참고:

join은(는) 일반 http:// 리드에 --insecure이(가) 필요합니다.
1.0 이전의 초대 토큰은 crew invite을(를) 사용하여 다시 생성해야 합니다.
이전 멤버 레코드는 reconnect이(가) 필요합니다.
업그레이드되지 않은 피어는 crew status에서 warn:(으)로 표시됩니다 (CREW_PROTOCOL §7.1).

1.0에서 변경되는 사항

Herdr 액션 ID 및 scripts/collie-ctl.sh 경로는 변경되지 않습니다 (ADR 0006).

CLI 동사는 <checkout>/bin/collie에 컴파일됩니다 (명령어). collie을(를) PATH에 추가하려면 bin/collie link을(를) 사용하십시오 (PATH에 collie 추가, ADR 0021).

새로운 기능:

pair / devices: 기기별 쓰기 자격 증명 (기기 페어링).
crew … / join / promote: 다중 호스트 클러스터링 (crew 명령).
doctor: 구성 진단.
stt setup: 음성 작성기 구성 (음성 입력).
hooks install claude / beacon emit: 에이전트 활동 비콘 (에이전트 비콘).
COLLIE_MUX: herdr(기본값), tmux, 또는 zellij을(를) 선택하십시오 (tmux 및 zellij).

무리(herd)가 실제라면 나란히

보조 인스턴스 구성은 단일 호스트에서의 다중 Collie 인스턴스에 설명되어 있습니다.

롤백

마지막 0.x 태그를 체크아웃하고 다시 빌드합니다.

last0x=$(git ls-remote --tags --refs origin | sed 's#.*refs/tags/##' | \
  grep -E '^v0\.[0-9]+\.[0-9]+$' | sort -V | tail -1)
git fetch --depth 1 origin tag "$last0x"
git checkout --detach --force "$last0x"
rm -f bin/collie    # 1.0's binary otherwise survives the rollback

bash scripts/collie-ctl.sh build을(를) 사용하여 다시 빌드하고 Herdr의 restart 액션을 호출합니다. 상태 파일(crew-trust.json, crew-runtime.json, paired-devices.json, pairing-pending.json)은 유지할 수 있습니다. 롤백하면 기기 페어링 적용이 제거됩니다. 쓰기 보호가 필요한 경우 COLLIE_DEVICE_HEADER을(를) 구성하십시오.

정상 작동 확인

version이(가) 1.0.0 이상으로 보고되는지 확인합니다. 업그레이드된 설치본은 기기를 자동으로 페어링하지 않습니다. 전화기에 쓰기 자격 증명을 발급하려면 pair을(를) 실행하고, 해당 전화기를 분실한 경우 devices revoke을(를) 실행하십시오(기기 페어링).

중지 또는 제거

서비스 일시 중지:

herdr plugin action invoke stop --plugin herdr.collie     # Herdr-managed
bin/collie stop                                           # standalone

서비스 정의 및 포트 매핑을 제거합니다(.env 및 체크아웃은 유지됨):

herdr plugin action invoke uninstall --plugin herdr.collie   # Herdr-managed
bin/collie uninstall                                         # standalone

프로그램과 사용자 파일까지 모두 삭제하려면 패키지를 포함한 설치 유형별 절차가 안내된 설치 → 제거의 세 단계를 따르십시오.

collie가 실행되지 않을 때

바이너리 설치(~/.local/share/collie 또는 $COLLIE_DIR)의 경우, 이전 바이너리를 직접 실행하십시오:

ls ~/.local/share/collie/versions/
~/.local/share/collie/versions/<previous>/bin/collie update --rollback

특정 버전을 직접 설치하려면:

curl -fsSL https://colliepwa.dev/install.sh | COLLIE_TAG=v1.0.0 sh

체크아웃 또는 Herdr 설치의 경우, git checkout <tag> 또는 herdr plugin install AltanS/collie --ref vX.Y.Z --yes을(를) 실행하십시오.

포크를 사용하는 경우

collie update은(는) origin을(를) COLLIE_UPDATE_REPO(기본값 AltanS/collie)와(과) 대조하여 확인하고 다를 경우 중단합니다. 포크가 자체 태그를 릴리스하는 경우 COLLIE_UPDATE_REPO=you/collie을(를) 설정하십시오.

업스트림 업데이트를 포크에 수동으로 병합하려면:

git remote add upstream https://github.com/AltanS/collie.git
git fetch upstream --tags
git merge v1.0.0                                            # the tag you decided to take
# resolve the conflicts, commit the merge, then rebuild and restart:
bash scripts/collie-ctl.sh build
# Herdr-managed: invoke the `restart` action instead
bin/collie restart

포크에서는 update --major을(를) 사용하지 마십시오. v1.* 태그를 수동으로 병합하십시오. 활성 COLLIE_UPDATE_REPO을(를) 확인하려면 collie doctor을(를) 실행하십시오.

재부팅 후에도 유지하기

Linux에서는 무인 사용자 서비스를 위해 lingering을 활성화합니다:

loginctl enable-linger $USER

systemctl --user status collie 명령으로 상태를 확인합니다.

macOS에서는 start이(가) ~/Library/LaunchAgents/herdr.collie.plist을(를) 자동으로 관리합니다. 사용자 로그인 시 실행됩니다. launchctl print gui/$(id -u)/herdr.collie 명령으로 상태를 확인하십시오.

GitHub에서 이 페이지 수정하기