본문 바로가기
ColliePWA

04/Documentation

Windows 환경의 Collie

Herdr 환경의 Windows 11: 지원 범위, install.ps1 설치, 서명되지 않은 바이너리, 업데이트, 긴 경로 및 테스트되지 않은 항목

Windows 11에 Collie를 설치하고 휴대폰에서 연 뒤 발생할 수 있는 문제를 해결하는 방법입니다. 먼저 보안을(를) 읽으십시오. Collie는 설계상 시스템에 원격 셸 접근 권한을 부여합니다.

Linux 및 macOS에서 collie start은(는) Tailscale Serve를 사용하여 휴대폰에 Collie를 대신 공개할 수 있습니다. Tailscale은 보유한 기기들을 tailnet이라는 사설 네트워크로 연결해 주는 서비스입니다.

Windows에서는 Collie가 자동으로 자신을 공개하지 않습니다. Tailscale Serve는 tailnet에서 Collie에 HTTPS 주소를 부여하며, Windows에서는 이 단계를 수동으로 실행해야 합니다. 휴대폰에서 접속하기에 방법이 나와 있습니다.

실험적 기능입니다. 실험적이란 메인테이너가 Windows 코드를 소유하고 테스트하지만, 아래 항목들이 아직 모두 검증되지는 않았음을 의미합니다. 전체 현황은 다음과 같습니다: 테스트 완료 - 릴리스 파일의 로컬 사본을 대상으로 한 Windows 11 가상 머신에서의 25단계 설치, 업데이트 및 롤백 리허설. - Windows 11 가상 머신에서 공개 v1.16.0 릴리스를 통한 실제 설치: install.ps1이(가) 릴리스를 찾았고 sha256이 일치했으며 collie.exe이(가) 실행되었습니다. 그런 다음 collie start, collie status, collie doctor, collie stop이(가) 작동했습니다. - Headscale tailnet 환경에서 Tailscale Serve를 통한 HTTP 기반 휴대폰 접속: Host 검사, collie url, 페어링 및 쓰기 게이트. 아직 테스트되지 않음 - Windows 환경에서 실제 두 릴리스 간의 업데이트. - Windows 환경의 Tailscale Serve HTTPS 방식 및 이를 통한 홈 화면 설치, Web Push, 마이크 기능. - Windows 10, Windows Server, Windows on ARM 및 테스트되지 않은 항목의 기타 항목. 이제부터 릴리스 검사에는 Windows zip 파일이 필수입니다. Linux 핫픽스(세부 정보)의 경우에만 메인테이너가 이를 무시할 수 있습니다.

제공되는 기능

Collie는 휴대폰에 터미널의 에이전트를 표시하므로, 어떤 에이전트에 사용자의 입력이 필요한지 확인하고 응답할 수 있습니다.

에이전트는 Herdr 창에서 실행됩니다. 창은 Herdr 내부의 터미널 창 하나를 의미합니다. Herdr는 터미널 멀티플렉서로, 창 안에서 에이전트가 계속 실행되도록 유지하는 프로그램입니다. Windows에서는 Herdr가 유일하게 지원되는 멀티플렉서입니다.

Collie는 Claude Code, Codex, OpenCode, pi, omp와 같은 에이전트를 인식합니다. 에이전트 자체는 Windows에서 실행되어야 합니다. 어떤 에이전트가 지원되는지는 Collie가 아닌 해당 에이전트에 달려 있습니다.

시작하기 전에

다음 항목이 필요합니다:

  • x64 기반 Windows 11. 여기서 WSL은 Windows에 해당하지 않습니다. WSL 내부에서는 설치의 Linux 설치를 따르십시오.
  • PowerShell. Windows 11에 기본 제공되는 Windows PowerShell 5.1로 충분합니다.
  • Windows용 Herdr 0.9.3 이상. 아래 1단계에서 설치합니다. Herdr 프로젝트에서 Windows 빌드를 제작하며 Collie는 이에 의존합니다.
  • 휴대폰 브라우저가 있는 iPhone 또는 Android 휴대폰.
  • 무료 Tailscale 계정. Tailscale 앱에 처음 로그인할 때 생성합니다. PC와 휴대폰이 동일한 계정에 로그인되어 있어야 합니다. 휴대폰은 이를 통해 PC에 접속하며, 6단계에서 설정합니다.

Smart App Control이 collie.exe을(를) 차단할 수 있으므로 활성화되어 있는지 확인하십시오. Windows 보안을 열고 앱 및 브라우저 컨트롤, Smart App Control 설정 순으로 이동하십시오. 세 가지 상태가 있습니다:

State이 설치 환경에서 의미하는 바
끔아무것도 차단하지 않습니다.
평가Windows가 활성화 여부를 아직 결정하는 중입니다. 테스트 VM에서는 Collie를 차단하지 않았습니다.
켬파일이 서명되지 않았고 파일별 허용 목록이 없으므로 collie.exe을(를) 차단할 수 있습니다.

켜져 있다면 먼저 서명되지 않은 바이너리을(를) 읽으십시오. 선택할 수 있는 방법들이 나열되어 있습니다.

설치부터 휴대폰 연결까지

다음 단계를 순서대로 진행하십시오. 목록 다음에 각 단계 후 표시되어야 하는 내용이 나옵니다. 설치 스크립트를 실행하기 전에 읽어보려면 설치을(를) 확인하십시오.

  1. 자체 설치 프로그램으로 Herdr를 설치한 다음 버전을 확인하십시오.
    irm https://herdr.dev/install.ps1 | iex
herdr --version
  1. 설치 프로그램으로 Collie를 설치하십시오.
    irm https://colliepwa.dev/install.ps1 | iex
  1. 새 터미널을 열고, 거기서 Herdr를 시작한 뒤 그대로 열어 두십시오.
    herdr
  1. 두 번째 터미널이나 새 Herdr 창을 연 다음, Collie를 시작하고 주소를 출력하십시오.
    collie start
collie url
  1. Herdr 창에서 에이전트(예: Claude Code)를 시작하십시오.
    claude
  1. 휴대폰에서 접속하기을(를) 사용하여 휴대전화에서 접근할 수 있는 경로를 만드십시오. Windows에서는 프로젝트가 HTTP로만 실행되었습니다. tailscale serve 명령 전에는 이 PC만 Collie에 접근할 수 있으며, 명령 후에는 페어링할 때까지 tailnet에 있는 모든 장치가 접근할 수 있습니다.
  1. 휴대전화의 브라우저에 해당 주소를 입력하거나 자신에게 전송한 다음, 휴대폰에서 열기에 표시된 대로 Collie를 홈 화면에 추가하십시오.
  1. PC에서 다음을 실행하여 휴대전화를 페어링하십시오.
    collie pair

각 단계 후 표시되어야 하는 내용:

  1. Herdr가 설치 프로그램 출력을 표시합니다. herdr --version은(는) 0.9.3 이상을 출력합니다. 설치 관리 권한이 Herdr 프로젝트에 있으므로 이 페이지에는 자체 Herdr 명령이 없습니다. 설치에 실패하면 herdr.dev을(를) 열고 Windows용 단계를 따르십시오.
  2. 스크립트가 각 단계를 출력합니다. OK Collie 로 시작하는 줄과 Next steps. This script does not take them for you:, 1. Open a NEW terminal window., 3. Start Collie, then print its address: 순으로 이어지는 다음 단계 목록으로 끝납니다. 스크립트를 먼저 읽어보려면 설치을(를) 확인하십시오.

    아무런 서비스도 시작되지 않으며 계속 실행되는 것도 없습니다. 스크립트는 Windows에서 실행을 허용하는지 확인하기 위해 collie.exe version을(를) 한 번 실행할 뿐입니다.

  3. Herdr가 열리고 해당 터미널을 차지합니다. Windows는 설치 후에 열린 창에만 새 PATH를 적용하므로 새 터미널이 필요합니다.
  4. Herdr가 첫 번째 터미널을 점유하므로 두 번째 터미널이 필요합니다. collie start은(는) Collie가 실행 중입니다 배너와 Collie가 여기에 front door를 게시하지 않는다는 알림을 출력합니다. front door는 휴대전화가 여는 Collie 앞단의 HTTPS 주소입니다. 이 알림은 Windows에서 정상적으로 나타납니다. 6단계에서 해당 부분을 직접 수동으로 처리합니다. Tailscale이 설치되기 전에는 stderr에 다음 줄도 출력됩니다: error: 'tailscale status' named no host for this node. 이 줄은 현재 단계에서 정상이며, 6단계 후에 사라집니다.
  5. 창에서 에이전트가 시작됩니다. Collie가 대시보드에 에이전트를 표시합니다.
  6. tailscale serve status에 tailnet 주소가 표시되고, collie url이(가) 이를 출력합니다. 이 단계 전에는 collie url에 이 PC에서만 열 수 있는 루프백 주소(127.0.0.1)가 출력될 수 있습니다. 대시보드를 확인하려면 이 PC의 브라우저에서 해당 주소를 열면 됩니다.
  7. 휴대전화에 Collie 대시보드가 표시됩니다. 사용자를 대기 중인 창이 먼저 표시됩니다.
  8. collie pair이(가) 8자리 코드를 출력한 다음 single-use · expires <time> (10 minutes) 같은 줄과 QR 코드를 차례로 출력합니다. 휴대전화에서 홈 화면을 통해 연 Collie 앱에 코드를 입력하십시오. 그러면 휴대전화가 페어링됩니다.

설치

install.ps1의 동작 방식과 변경 가능한 항목.

irm https://colliepwa.dev/install.ps1 | iex

스크립트를 실행하기 전에 읽어보려면 저장하고 연 다음 파일로 실행하십시오.

Invoke-WebRequest -OutFile install.ps1 https://colliepwa.dev/install.ps1
notepad install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1

install.ps1에는 Bun, Git, bash이 필요하지 않습니다. 최신 5개 릴리스를 확인하고, Windows zip 파일이 있는 첫 번째 릴리스를 가져와 sha256을 검사한 후 일치하지 않으면 중단합니다. sha256은 파일의 지문입니다. 스크립트는 각 단계를 출력하며, 관리자 권한을 요청하지 않습니다. zip 파일이 포함된 릴리스가 없으면 아래에 설명됨 상태로 중단됩니다.

기본 실행 정책인 Restricted(실행 가능한 스크립트에 대한 Windows 규칙)은 다운로드한 스크립트 파일을 거부합니다. "먼저 읽어보기" 변형의 마지막 줄은 해당 단일 실행에 대해 Bypass을 설정합니다. Unblock-File .\install.ps1은 다른 방법입니다. irm ... | iex 형식은 스크립트 텍스트를 직접 실행하므로 이 작업이 필요하지 않습니다.

스크립트는 릴리스를 %LOCALAPPDATA%\collie\versions\<version>에 배치하고, current junction이 이를 가리키도록 설정하며, current\bin을 사용자 PATH에 추가합니다. junction은 Windows 폴더 링크이며, current은 항상 실행되는 버전을 가리킵니다. 스크립트는 Windows가 실행을 허용하는지 확인하기 위해 collie.exe version을 한 번 실행합니다. 그 외에는 아무것도 시작하지 않습니다. 두 번째 실행에서는 아무것도 변경되지 않으며 collie update을 가리킵니다.

변수효과
COLLIE_DIR설치할 위치입니다. 기본값은 %LOCALAPPDATA%\collie입니다. 짧게 유지하십시오.
COLLIE_TAG예를 들어 v1.16.0과(와) 같이 정확한 릴리스 하나를 설치합니다.
COLLIE_UPDATE_REPO다운로드할 GitHub 저장소입니다. 기본값은 AltanS/collie입니다.
COLLIE_NO_PATH_EDIT=1PATH를 그대로 둡니다. <COLLIE_DIR>\current\bin\collie.exe을(를) 실행하십시오.

zip 파일은 GitHub의 각 릴리스 페이지에서 .sha256 파일 옆에도 있습니다. zip을 수동으로 설치하지 말고 스크립트를 사용하십시오.

collie start은 herdr.collie이라는 이름의 작업 스케줄러 작업을 등록합니다. 작업 스케줄러는 정해진 시간이나 이벤트에 작업을 실행하는 Windows 프로그램입니다. 이 작업은 로그온 시 제한된 토큰으로, 즉 관리자 권한 없이 Collie를 시작합니다.

이 작업은 브릿지가 오류로 종료될 경우 브릿지를 다시 시작하는 작은 프로그램인 시작 도구를 실행합니다. 브릿지는 PC에서 실행되며 휴대폰으로 웹 페이지를 제공하는 Collie 프로그램입니다.

휴대폰에서 접속하기

휴대폰 설정 완전 정복의 6단계 전문입니다. 이는 Linux 및 macOS에서 수행하는 단계와 동일하며 수동으로 진행됩니다. 이 프로젝트는 Windows 환경, HTTP 연결, Headscale tailnet(Headscale은 자체 호스팅 Tailscale 서버입니다) 상에서 데스크톱 브라우저를 휴대폰 크기로 설정하여 한 번 실행되었습니다. 아래의 HTTPS 형식은 실행되지 않았으며, 실제 휴대폰이나 에이전트는 사용되지 않았습니다. 단계가 실패하면 보고하십시오(위치).

주의. tailscale serve 명령(아래 3단계) 이후부터 기기를 페어링할 때까지 Collie는 tailnet의 모든 기기에 열려 있으며, 해당 기기들이 창을 읽고 입력할 수 있습니다. 해당 명령을 실행하기 전에는 이 PC에서만 Collie에 접근할 수 있습니다. 직후에 휴대폰 단계와 collie pair을 진행하십시오. 다른 사람이 tailnet을 공유하는 경우 즉시 페어링하고, Collie에 접근할 수 있는 대상을 제한하는 방법은 보안을 읽어보십시오.
  1. PC와 휴대폰에 Tailscale을 설치하고 둘 다 동일한 계정으로 로그인하십시오: tailscale.com/download.
  1. Tailscale 관리 콘솔에서 DNS을 열고 MagicDNS를 켠 다음 Enable HTTPS을 선택하십시오.
  1. PC의 새 터미널에서 Collie의 로컬 포트(기본값 8787)를 tailnet에 게시하십시오.
    tailscale serve --bg --set-path=/ 8787
  1. Collie 설정 폴더가 없으면 생성한 다음, 해당 폴더의 .env 파일을 여십시오.
    New-Item -ItemType Directory -Force "$env:APPDATA\herdr\plugins\config\herdr.collie"
notepad "$env:APPDATA\herdr\plugins\config\herdr.collie\.env"
  1. 파일 끝에 3단계에서 확인한 본인의 이름을 포함하여 다음 두 줄을 추가하고 저장하십시오.
    COLLIE_PUBLIC_HOSTS=myhost.tail1234.ts.net
COLLIE_PUBLIC_URL=https://myhost.tail1234.ts.net
  1. 브릿지를 다시 시작한 다음 주소를 출력하십시오.
    collie restart
collie url

Collie는 이 PC에서만 접근할 수 있는 루프백 주소를 통해 이 PC에서만 수신 대기합니다. Linux 및 macOS에서는 collie start이 대신 Tailscale Serve를 실행합니다. 이것이 "관리형 프런트 도어"의 의미입니다. 즉, Collie가 주소를 직접 게시합니다. Windows에서는 collie start이 이를 수행하지 않으므로 사용자가 Tailscale Serve를 직접 실행해야 합니다.

3단계에서 Tailscale은 https://myhost.tail1234.ts.net과 같은 주소가 포함된 줄을 출력합니다. 이름은 https:// 뒤에 오는 부분입니다. 이를 복사하십시오. tailscale serve status에도 동일한 주소가 표시됩니다.

https://myhost.tail1234.ts.net (tailnet only)
|-- / proxy http://127.0.0.1:8787

이 명령은 Linux 및 macOS에서 collie start이 대신 실행하는 명령과 동일합니다. --set-path=/은 이 PC가 tailnet의 /에서 이미 제공 중인 모든 것을 대체합니다.

참고. Headscale tailnet에서는 Headscale이 HTTPS 인증서를 발급하지 않으므로 3단계의 HTTPS 명령이 error enabling https feature: error 501 Not Implemented 오류로 실패합니다. 게시하기 전까지 collie doctor은 front-door 줄에서 경고를 표시합니다: this tailnet has no HTTPS certificates, so an https front door cannot be published. 이 경우 프로젝트가 Windows에서 실행했던 형태인 HTTP를 통해 게시하십시오: tailscale serve --bg --http=80 --set-path=/ 8787. 이는 tailnet 포트 80에 게시되므로 주소는 포트 번호가 없는 http://<name>이 됩니다. COLLIE_PUBLIC_URL에서 해당 http:// 주소를 사용하십시오. 이 명령을 실행한 후에는 front-door 줄이 통과됩니다. 1.16.0에서는 경고가 유지됩니다. Tailscale이 tailnet 기기 간의 트래픽을 암호화하고(WireGuard) HTTP 홉이 tailnet 내부에 유지되므로 여기서는 일반 HTTP를 사용해도 괜찮습니다. tailscale funnel은 절대로 사용하지 마십시오. HTTP를 사용하면 홈 화면 설치, Web Push, 마이크 기능이 꺼진 상태로 유지됩니다. Linux 및 macOS에서 Collie 자체 HTTP 모드는 대신 브릿지 포트에 게시합니다(COLLIE_SERVE_MODE). Collie는 Windows에서 Serve를 실행하지 않으므로 해당 변수는 여기서 게시에 영향을 주지 않습니다.

HTTPS가 켜진 tailnet에서 Tailscale은 휴대폰이 신뢰하는 인증서를 주소에 부여합니다. Headscale의 경우 위의 참고 사항을 확인하십시오. 홈 화면에 설치, Web Push(휴대폰 알림), 마이크를 사용하려면 HTTPS가 필요합니다. 일반 HTTP에서는 해당 기능이 꺼진 상태로 유지됩니다(음성 입력 및 Web Push).

4단계에서 메모장은 파일이 없는 경우 파일을 만들지 묻습니다. 예을 클릭하십시오. 해당 폴더는 herdr.collie용 Herdr 플러그인 설정 폴더이며, 기본값은 %APPDATA%\herdr\plugins\config\herdr.collie입니다. Collie가 Herdr에 이를 요청하므로 herdr plugin config-dir herdr.collie이 해당 경로를 출력합니다.

COLLIE_PUBLIC_HOSTS은 Host 검사입니다. Collie는 각 요청에서 웹사이트 이름을 읽고 이 목록에 없는 모든 이름을 거부하여 웹 페이지가 DNS 리바인딩을 통해 접근하는 것을 차단합니다. COLLIE_PUBLIC_URL은 collie url 및 collie pair의 QR 코드가 출력하는 주소입니다. 전체 이름으로 Collie를 여십시오. Host 검사는 tailnet IP 주소와 짧은 이름을 거부합니다. Collie는 시작 시 tailnet 이름을 직접 찾으려고도 시도합니다. 이 두 줄을 통해 확실하게 설정할 수 있습니다.

Collie는 Windows에서 이 매핑을 관리하지 않습니다. collie stop 및 collie uninstall을 실행해도 매핑은 유지됩니다. tailscale serve status은 매핑을 표시하고, tailscale serve reset은 PC의 모든 Serve 매핑을 지웁니다. tailscale funnel은 절대로 사용하지 마십시오. Funnel은 Collie를 공용 인터넷에 노출합니다.

Collie로 웹 요청을 전달하는 프로그램인 리버스 프록시나 다른 터널을 선호하는 경우 배포에서 변형을 설명합니다. 이는 변형 C이며, COLLIE_PUBLIC_HOSTS은 휴대폰에서 여는 이름으로 설정됩니다. Collie는 이 머신에서만 수신 대기하므로 첫 번째 collie start에서는 방화벽 프롬프트가 표시되지 않습니다.

휴대폰에서 열기

  1. collie url의 주소를 휴대폰으로 가져오십시오. 직접 입력하거나 본인에게 전송하십시오. iPhone에서는 Safari로 주소를 여십시오. Android 휴대폰에서는 Chrome으로 여십시오. 휴대폰에는 tailnet에 로그인된 Tailscale 앱이 필요합니다.
  2. 앱처럼 전체 화면으로 열리도록 Collie를 홈 화면에 추가하십시오: - iPhone: Safari에서 공유을 탭하고 홈 화면에 추가를 탭한 다음 추가을 탭하십시오. - Android: Chrome에서 Collie Settings을 열고 상단 카드에서 설치을 탭하십시오.
  3. 새 아이콘에서 Collie를 엽니다.
  4. 앱에서 Settings을 연 다음 System, Paired devices을 차례로 여십시오.
  5. PC에서 collie pair을(를) 실행하고 코드와 이름을 입력한 다음 이 기기 페어링을(를) 탭합니다.

아이콘을 눌러 연 앱에 코드를 입력합니다. collie pair이(가) 출력하는 QR 코드를 스캔하지 마십시오. 카메라로 스캔하면 브라우저 탭에서 열리며, iPhone의 홈 화면 앱은 Safari와 분리된 자체 저장소를 사용하므로 브라우저 탭에서 완료한 페어링이 연계되지 않습니다.

코드는 10분 동안 유효하며 한 번만 사용할 수 있습니다. 만료되었다면 collie pair을(를) 다시 실행하십시오. 페어링이 완료되면 위의 주의 사항(기기 페어링)에 명시된 개방 접근 상태가 종료됩니다.

일상적인 명령어

아무 터미널에서나 다음 명령어를 실행하십시오. 아래의 Windows 관련 참고 사항을 제외하면 Linux 및 macOS에서와 동일하게 동작합니다.

명령어Windows에서의 동작
collie start필요한 경우 herdr.collie 작업을 등록하고 bridge를 시작합니다.
collie stop작업을 비활성화하고, 실행 중인 bridge와 bridge 실행기를 종료한 뒤 bridge stopped을(를) 출력합니다. Collie는 collie start을(를) 실행할 때까지 다음 로그인 시에도 비활성 상태를 유지합니다.
collie restartbridge만 다시 시작합니다.
collie status작업 이름과 상태를 표시하고 Collie가 실행 중입니다 배너를 표시합니다.
collie doctor설치 상태, Herdr, 긴 경로 및 비밀 파일을 확인하고 각 문제에 대한 해결 방법을 출력합니다.
collie url휴대폰에서 열 주소를 출력합니다.
collie logs로그 파일의 마지막 몇 줄을 출력합니다.
collie update최신 릴리스로 업데이트합니다(업데이트).
collie update --rollback이전 버전으로 되돌립니다(업데이트).
collie uninstall작업을 제거합니다(제거).

업데이트

Linux 및 macOS와 마찬가지로 터미널이나 휴대폰에서 업데이트하십시오:

collie update

업데이트 시 릴리스를 가져오고, collie.exe을(를) 교체하며, bridge를 다시 시작한 뒤 응답하는지 확인합니다. 응답하지 않으면 Collie는 약 1분 15초 이내에 정상 동작하던 버전으로 롤백합니다. 휴대폰의 Update 버튼도 동일한 절차를 실행합니다.

수동으로 되돌리려면 이 명령을 실행하십시오. 네트워크가 필요하지 않습니다. 디스크에 남아 있는 이전 버전 중 가장 최신 버전을 current이(가) 가리키도록 설정하고 bridge를 다시 시작합니다. 해당 버전이 실행되지 않으면 Collie는 다시 최신 상태로 돌아가며 아무것도 변경하지 않습니다.

collie update --rollback

실행 중인 프로그램이 잡고 있는 폴더는 Windows에서 삭제되지 않으므로, 론처가 다시 시작될 때까지 이전 버전 폴더가 versions\에 남아 있을 수 있습니다. 다음 업데이트 시 제거됩니다.

주의. Windows에서는 소스 체크아웃이 자체적으로 업데이트되지 않습니다. collie update 및 휴대폰 버튼에 해당 내용이 한 줄로 표시되며 아무것도 변경되지 않습니다. 최초 zip 버전 이전에 설치된 모든 Windows 환경은 소스 체크아웃입니다. zip 설치로 전환하는 것은 1회성 수동 절차입니다. collie uninstall을(를) 실행하여 기존 작업을 제거한 다음 install.ps1을(를) 실행하십시오. 그 후에는 collie update이(가) 정상 동작합니다.

Collie는 Windows 머신당 하나의 설치만 허용하며, collie start은(는) 다른 설치 환경을 실행하는 작업을 거부합니다. 따라서 기존 작업을 먼저 제거해야 합니다. 소스 체크아웃 상태를 유지하며 수동으로 업데이트할 수도 있습니다. 최신 태그를 가져온 뒤 bun run build을(를) 실행하고, 이어서 collie restart을(를) 실행하십시오. 빌드에는 Git for Windows의 bash이(가) 필요합니다.

v1.15.0 이하의 릴리스는 실행 중인 collie.exe을(를) 교체할 수 없으며 EPERM 오류와 함께 실패합니다. 수정 사항(PR 309)은 v1.15.1에서 처음 제공되었습니다. Windows에서의 휴대폰 Update 버튼과 같은 후속 Windows 업데이트 작업은 v1.16.0에서 처음 제공됩니다.

제거

collie uninstall

collie uninstall은(는) bridge를 중지하고 작업 스케줄러 작업을 제거합니다. 모든 설치가 파일을 유지하는 것과 마찬가지로 설치 폴더, 사용자의 .env 및 사용자 PATH 항목은 유지됩니다. 그런 다음 PowerShell용 명령어 두 줄을 추가로 출력합니다. 첫 번째는 설치 폴더를 제거합니다. 두 번째는 레지스트리를 통해 사용자 PATH에서 current\bin만 제거합니다. Collie는 실제 폴더 경로를 포함하여 두 줄을 각각 한 줄씩 출력합니다. 너비에 맞추어 줄바꿈된 형태는 다음과 같습니다.

cmd /c rmdir /s /q "<install folder>"
$k = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Environment', $true)
$k.SetValue('Path', (($k.GetValue('Path', '', 'DoNotExpandEnvironmentNames') -split ';' |
  Where-Object { $_.TrimEnd('\') -ne '<install folder>\current\bin' }) -join ';'),
  $k.GetValueKind('Path'))
$k.Close()

가능하면 Collie의 출력 결과에서 해당 줄을 복사하십시오. Collie는 사용자가 직접 수동으로 생성한 tailscale serve 매핑(휴대폰에서 접속하기)을 제거하지 않습니다.

문제가 발생했을 때

먼저 collie doctor을(를) 실행한 다음, 아래에서 문제를 확인하십시오.

collie doctor은(는) 설치 상태를 확인하고 발견된 각 문제의 해결 방법을 출력합니다. 그런 다음 화면에 나타난 내용과 일치하는 아래 섹션을 읽으십시오. 일치하는 내용이 없다면 로그에 설명된 로그를 확인하십시오.

문제를 보고하려면 github.com/AltanS/collie/issues에서 이슈를 등록하십시오. Windows를 사용 중임을 명시하고, collie version에서 확인한 Collie 버전을 기재한 뒤, collie doctor 출력 결과와 로그의 마지막 줄들을 붙여넣으십시오. 개인 정보는 먼저 삭제하십시오. 로그에는 창 텍스트가 포함될 수 있습니다.

서명되지 않은 바이너리: SmartScreen 및 Smart App Control

collie.exe에 서명되지 않았으므로 Windows는 게시자를 알지 못합니다. 설치 프로그램을 실행하기 전에 이 내용을 읽으십시오.

서명되지 않은 프로그램을 중단할 수 있는 두 가지 Windows 기능:

  • SmartScreen은(는) 인터넷에서 다운로드한 프로그램을 실행하기 전에 확인을 요청합니다. 브라우저에서 다운로드한 파일의 경우 추가 정보을(를) 클릭한 다음 실행을(를) 클릭하십시오.
  • Smart App Control에는 파일별 허용 기능이 없습니다. 이 기능이 켜져 있고 Collie를 차단하는 경우, 해당 파일 하나만 허용하도록 지정할 수 없습니다. install.ps1이(가) collie.exe version을(를) 실행할 때 차단 사실이 표시되며, 성공 메시지가 출력되지 않습니다.

Smart App Control이 Collie를 차단하는 경우 다음 순서대로 선택할 수 있습니다.

  1. 활성화 여부를 확인하십시오. Windows 보안을 열고 앱 및 브라우저 컨트롤을(를) 선택한 다음 Smart App Control 설정을(를) 선택하십시오.
  2. 소스에서 빌드하여(소스에서 빌드) 로컬 컴퓨터에서 collie.exe을 생성합니다. Smart App Control이 켜진 컴퓨터에서는 테스트되지 않았습니다.
  3. Smart App Control이 꺼진 PC를 사용하거나 차단 현상을 이슈로 제보하십시오.
  4. 마지막으로 Smart App Control을 끄는 방법이 있습니다. 이는 되돌리기 어렵습니다. Microsoft 문서에 따르면 다시 켜려면 Windows 초기화가 필요할 수 있으므로 최신 Microsoft 문서를 먼저 확인하십시오.

install.ps1의 sha256 검사는 손상되거나 변조된 다운로드를 감지합니다. 해시가 zip 파일과 함께 제공되고 둘 중 하나를 바꿀 수 있는 주체는 다른 하나도 바꿀 수 있으므로 파일 게시자가 누구인지는 알려주지 않습니다. 바이너리 서명은 추후 진행될 수 있는 작업이며 확정된 일정은 없습니다.

긴 경로

표시되는 내용: 창이 열리지 않고 Herdr에 The directory name is invalid (os error 267)이(가) 표시됩니다. collie doctor이(가) 먼저 경고합니다: LongPathsEnabled is 0 on this machine.

Windows 긴 경로가 활성화되어 있지 않으면 Herdr는 경로가 260자를 초과하는 폴더에서 창을 시작할 수 없습니다. collie doctor은(는) 설치 폴더 자체가 너무 길 때도 경고합니다.

관리자 권한으로 실행된 PowerShell에서:

Set-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' `
  -Name LongPathsEnabled -Value 1

이미 실행 중인 프로그램이 이를 인식하려면 Windows를 다시 시작해야 할 수 있습니다. 어떤 경우든 작업 폴더를 짧게 유지하십시오.

작업 스케줄러가 표준 사용자를 거부함

표시되는 내용: collie start이(가) error: schtasks /Create /TN herdr.collie failed 오류로 실패하고, Windows에서 0x80070569을(를) 보고하며, Collie는 계정에 "Log on as a batch job" 권한이 없다고 표시합니다.

이 문제는 해당 권한이 없었던 표준 사용자 계정에 영향을 줍니다. 관리자 계정은 대개 이 권한을 가지고 있습니다.

관리자가 권한을 부여합니다:

  1. secpol.msc을(를) 실행하십시오.
  2. 로컬 정책을 연 다음 사용자 권한 할당을 여십시오.
  3. Log on as a batch job을(를) 열고 계정을 추가하십시오.
  4. collie start 명령을 다시 실행하십시오.

Windows Home에는 secpol.msc이 포함되어 있지 않습니다.

보안 파일

표시되는 내용: collie doctor 명령은 해결 방법과 함께 secrets-private 줄(예: can be read by other accounts)을 출력합니다.

Collie는 보안 파일을 읽을 수 있는 대상을 사용자 계정, SYSTEM, Administrators로 제한합니다. Windows에는 0600 모드가 없으므로, Collie는 상태 및 설정 폴더의 접근 제어 목록(ACL)을 설정합니다.

collie doctor

secrets-private 줄에는 세 가지 상태가 있습니다:

상태의미
Private폴더는 사용자 계정, SYSTEM, Administrators 전용으로 보호됩니다.
Loose다른 계정이 폴더나 보안 파일을 읽을 수 있습니다. 이는 오류이며, doctor 명령이 해결 방법을 출력합니다.
Not checkedCollie가 목록을 읽을 수 없으므로 cannot confirm 상태를 표시합니다. 이는 경고입니다.

네트워크 공유 폴더나 FAT 또는 exFAT 볼륨에 있는 폴더는 읽을 수 있는 목록이 없으므로 "not checked" 상태가 됩니다. 상태 및 설정 폴더는 이 PC의 NTFS 드라이브에 보관하십시오.

bridge는 시작 시 loose 상태인 폴더를 복구하지만, Collie가 방금 생성한 폴더, 사용자 프로필의 기본 폴더, 비어 있거나 Collie 자체 파일만 포함된 폴더만 복구합니다. 다른 모든 폴더는 검사 후 경고를 표시하며, 문제를 해결하는 icacls 명령을 안내합니다. collie doctor 및 기타 명령은 아무것도 변경하지 않습니다.

복구를 취소하려면: 복구 전에 bridge가 상태 폴더의 acl-backups에 이전 목록을 저장하고 취소 명령 줄을 출력합니다. 관리자 권한으로 실행한 터미널에서 다음을 실행하십시오:

icacls <folder> /restore <backup file>

COLLIE_NO_ACL_REPAIR=1 플래그는 모든 변경을 끕니다. Collie는 여전히 검사하고 경고합니다. 규칙에 대한 자세한 설명은 Windows에서의 보안 파일에 있습니다.

로그

브리지 로그는 플러그인 설정 폴더의 collie.log입니다(기본값은 %APPDATA%\herdr\plugins\config\herdr.collie\collie.log). collie logs는 로그의 마지막 줄들을 출력합니다. Collie는 파일 끝에 내용을 추가하기만 하고 로그를 교체(rotate)하지 않으므로 브리지가 실행되는 동안 파일 크기가 계속 커집니다. 파일을 비우려면 collie stop을 실행하고 파일을 삭제한 다음 collie start를 실행하십시오.

소스에서 빌드

릴리스 zip 파일은 툴체인이 필요하지 않습니다. 소스에서 빌드할 때는 여전히 Bun, Git, 그리고 PATH에 Git for Windows의 bash이(가) 있어야 합니다. bun run build이(가) bash을(를) 호출하기 때문입니다. bash 없는 빌드는 계획되어 있으나 아직 완료되지 않았습니다.

지원 대상

지원 호스트 1개: x64 기반 Windows 11, 멀티플렉서로 Herdr 사용.

crew은 각각 Collie를 실행하는 여러 대의 컴퓨터로 구성되며 하나의 URL(crew) 뒤에 표시됩니다.

지원됨지원되지 않음, 작동할 수 있음, 테스트되지 않음
WindowsWindows 11, x64Windows 10, Windows Server 및 Windows on ARM
멀티플렉서Windows용 Herdr 0.9.3 이상 버전tmux, zellij 및 tuios: 모두 네이티브 Windows 빌드가 없습니다.
서비스작업 스케줄러, 머신당 Collie 1개Windows 서비스, winget 및 MSI
Crew단일 머신의 Colliecrew에 합류하는 Windows 머신
현관문수동으로 직접 게시합니다Collie가 관리하는 프런트 도어
바이너리collie.exe, 서명되지 않음, sha256 포함서명된 바이너리

다음 제한 사항도 적용됩니다:

  • Collie는 Windows 컴퓨터당 하나의 설치만 허용합니다. 작업 이름은 항상 herdr.collie입니다.
  • Collie는 collie.log(로그)을 교체(rotate)하지 않습니다.
  • herdr plugin install은 Windows 설치 경로가 아닙니다. install.ps1을 사용한 다음 collie start를 사용하십시오.
  • Herdr의 작업 버튼은 bash이 필요하므로 Windows에는 존재하지 않습니다.
  • Herdr의 Windows 빌드는 Herdr 프로젝트에서 제작합니다. Collie는 여기에 의존하며 이를 제어하지 않습니다.

crew

이 릴리스에서는 Windows 컴퓨터가 crew에 참여할 수 없습니다. collie crew invite, crew join, crew add, crew deputy, crew approve-promote, collie promote는 Windows에서 거부되며 한 줄의 안내 메시지를 출력하고 아무것도 변경하지 않습니다. 단일 Windows 컴퓨터의 Collie는 독립적으로 작동합니다.

커뮤니티 스크립트에서 전환하기

커뮤니티 스크립트를 실행한 경우 변경되는 항목 및 이전되지 않는 항목.

이번 릴리스 이전에는 Windows에서 커뮤니티가 작성한 스크립트인 contrib/windows/collie-ctl.ps1 아래에서 실행되었습니다. 이제 Collie가 작업을 직접 실행하며, 해당 스크립트의 모든 동사는 같은 이름의 collie 동사로 제공됩니다. 업데이트한 후 collie restart 명령을 한 번 실행하십시오. 스크립트가 herdr.collie 이름의 작업을 실행했던 경우, Collie가 동일한 이름으로 작업을 인계합니다. 다시 시작하기 전까지는 collie status 및 collie doctor 명령에 작업이 여전히 이전 스크립트를 실행 중이라고 표시됩니다.

두 가지 사항은 인계되지 않습니다:

  • 사용자 지정 작업 이름. 해당 스크립트에서는 COLLIE_TASK_NAME을 설정할 수 있었습니다. Collie는 이를 읽지 않으며, 작업 이름은 항상 herdr.collie입니다. 다른 이름으로 등록한 작업은 그대로 유지되며 Collie가 이를 중지하거나 제거하지 않습니다. collie start 명령을 실행하기 전에 이를 삭제하십시오. 그렇지 않으면 두 관리자가 bridge를 시작하게 됩니다. PowerShell 명령어: schtasks /Delete /TN "<your task name>" /F.
  • 충돌 로그 사본. 해당 스크립트는 bridge가 실패했을 때 로그 사본을 보관했습니다. Collie는 보관하지 않습니다. 이전 사본은 삭제할 때까지 디스크에 유지됩니다.

테스트 방식 및 experimental 단계 종료 시점

근거를 확인하려는 독자를 위한 Collie에 experimental이 표시되는 이유. Collie 사용에 반드시 필요한 내용은 아닙니다.

이 페이지에 사용된 두 단어는 정해진 의미를 갖습니다.

  • 지원됨은 유지 관리자가 Windows 코드를 직접 관리하고 테스트함을 의미합니다. 매 푸시마다 CI가 실행되고, 각 릴리스 태그 전에 Windows 11 가상 머신에서 사전 검증(ADR 0075)을 수행합니다. CI는 GitHub에서 실행되는 자동 테스트입니다. ADR은 저장소에 보관되는 짧은 결정 기록입니다.
  • 실험적 기능은 두 실제 릴리스 간의 업데이트와 HTTPS 모바일 경로가 아직 검증되지 않았음을 의미합니다.

지원의 기반:

  • CI 워크플로인 windows.yml 워크플로는 모든 풀 리퀘스트 및 main에 대한 모든 푸시마다 windows-latest에서 bridge, cli, scripts 테스트를 실행합니다. 아직 필수 점검 항목은 아닙니다. 유지 관리자는 약 10회 연속 성공한 후 필수 항목으로 지정할 계획입니다.
  • 각 릴리스는 .sha256 파일과 함께 collie-<version>-windows-x64.zip을 빌드합니다.
  • 각 릴리스 태그 전에 유지 관리자는 사전 검증인 make win-rehearse을 실행합니다. 빈 Windows 11 VM에 릴리스를 설치하고 터미널과 스마트폰 엔드포인트에서 업데이트를 수행하며 헬스체크 실패를 유도하여 롤백을 확인합니다. 업데이트는 로컬에 복사된 릴리스 파일을 사용합니다. VM을 사용할 수 없으면 태그 생성을 보류합니다.
  • CI 실행 환경이 Windows Server이므로 CI 외에 Windows 11이 두 번째 검증 기준이 됩니다.
  • 공개된 v1.16.0 릴리스의 실제 설치는 Windows 11 VM에서 실행되었습니다. install.ps1이 릴리스를 찾고 zip을 다운로드했으며 sha256이 일치했고 collie.exe이 1.16.0으로 실행되었습니다. collie start가 작업을 등록하고 브리지를 시작했습니다. collie status에 running이 표시되었고 collie doctor는 종료 코드 0으로 종료되었으며 collie stop가 이를 중지했습니다. https://colliepwa.dev/install.ps1의 스크립트는 활성 상태이며 v1.16.0 릴리스의 스크립트와 바이트 단위까지 동일합니다.
  • 모바일 접속은 Headscale tailnet 환경의 Windows 11 VM에서 HTTP를 통해 실행되었습니다. tailscale serve --bg --http=80 --set-path=/ <port>이 Collie를 게시했습니다. 두 개의 .env 줄과 collie restart로 인해 collie url 및 collie start 배너에 tailnet 이름이 출력되었습니다. 다른 tailnet 컴퓨터에서 페이지, /api/health, /api/snapshot이 전체 이름으로 응답했으며 tailnet IP 주소나 짧은 이름으로 보낸 요청은 거부되었습니다. 모바일 인터페이스에서의 페어링이 정상 작동했고 그 후 자격 증명 없이 쓰기를 시도하자 403 "device not paired"가 반환되었습니다. 스마트폰 크기로 조정한 데스크톱 브라우저를 스마트폰 대신 사용했습니다.
  • 테스트 VM의 Smart App Control은 평가 모드로 설정되어 있으며 Smart App Control과 SmartScreen 모두 해당 환경에서 Collie를 차단하지 않았습니다. 이 페이지는 실제 발생한 차단 사례가 아니라 Windows 문서에 명시된 내용을 설명합니다.

experimental 표시는 다음 조건이 모두 동시에 충족될 때만 제거됩니다:

  1. 릴리스에 Windows zip이 포함되고 install.ps1이 colliepwa.dev에 등록되며 실제 릴리스를 대상으로 설치 1회와 업데이트 1회가 실행되어야 합니다. 앞의 세 가지는 완료되었습니다. v1.16.0에 zip이 포함되어 있고 주소가 활성 상태이며 설치가 실행되었습니다. 두 실제 릴리스 간의 업데이트는 zip이 포함된 두 번째 릴리스가 필요하므로 아직 완료되지 않았습니다.
  2. Windows 검사는 브랜치 보호의 필수 검사입니다. 브랜치 보호는 지정된 검사를 통과할 때까지 병합을 차단하는 GitHub 설정입니다.
  3. 릴리스 게이트는 Windows 워크플로를 읽습니다. 게이트는 배포 전에 테스트를 기다리는 릴리스 워크플로의 첫 번째 단계입니다.
  4. Windows zip 누락에 대한 허용 설정이 꺼져 있습니다. 다음 섹션에 설명된 대로 지금은 꺼져 있습니다.

Windows zip이 없는 릴리스

릴리스 검사는 이제부터 Windows zip을 요구합니다. Linux 핫픽스를 위해 메인테이너만 이를 재정의할 수 있습니다. 릴리스 작업은 scripts/windows-asset.ts에서 이를 확인합니다. zip을 포함하는 이전 안정 릴리스(초안이나 사전 릴리스가 아님)를 검색하며, v1.16.0이 그중 하나입니다. 2026-11-15부터는 어떤 경우에도 zip이 필수이며, GitHub의 릴리스 목록이 응답하지 않을 때도 필수입니다. 유일한 예외는 Windows 빌드가 깨진 동안 Linux 핫픽스를 위해 메인테이너가 설정할 수 있는 스위치인 저장소 변수 COLLIE_WINDOWS_ASSET_OVERRIDE입니다. 해당 스위치 아래에서 생성된 릴리스에는 Windows zip이 포함되지 않습니다.

v1.16.0 이전 릴리스에는 Windows zip이 없습니다. 최신 릴리스에 zip이 없을 때 표시되는 내용은 다음과 같습니다.

  • install.ps1은(는) 최신 5개 릴리스를 확인합니다. 각 릴리스에 대해 <tag> has no Windows build. Trying the next older release.을(를) 출력합니다. 그런 다음 collie install: none of the newest 5 releases of AltanS/collie carries a Windows build yet. Nothing was installed.을(를) 출력하고 Install failed. 및 zip이 있는 릴리스를 고정하라는 안내 줄로 끝납니다. 시스템의 어떤 것도 변경하지 않습니다. 릴리스를 고정하려면 COLLIE_TAG을(를) 설정하십시오.
  • Windows 환경에서 collie update을(를) 실행하면 error: release <version> has no Windows build; try again after the next release. Nothing was changed.이(가) 출력됩니다.

확인하려면 GitHub의 릴리스 페이지를 열고 이름이 collie-<version>-windows-x64.zip인 파일을 찾으십시오.

테스트되지 않은 항목

어떤 항목도 확답으로 받아들여지지 않도록 단순 목록으로 제공합니다.

  • Windows에서 두 개의 실제 릴리스 간 업데이트입니다. 사전 점검에는 릴리스 파일의 로컬 복사본을 사용했습니다.
  • Windows에서 Tailscale Serve의 HTTPS 형태(Headscale이 501 Not Implemented을(를) 반환함)와 홈 화면 설치, Web Push 및 마이크입니다. 또한 Tailscale Serve 대신 실제 휴대폰, Herdr 창에서 실행되는 에이전트, 역방향 프록시를 사용했습니다.
  • Windows에서의 수동 collie update --rollback입니다. 업데이트 실패 후의 자동 롤백을 사전 점검했습니다.
  • 소스 체크아웃에서 zip 설치로 전환하고 소스 체크아웃을 수동으로 업데이트합니다.
  • install.ps1 없이 수동으로 zip 설치하기.
  • Windows 10, Windows Server, Windows on ARM, tmux, zellij 및 Windows 환경의 tuios.
  • 실제 스마트 앱 제어(Smart App Control) 차단 환경, 그리고 install.ps1을(를) 위한 PowerShell 7.
  • 스마트 앱 제어가 켜져 있는 머신에서의 소스 빌드.
  • Windows Home의 작업 스케줄러 수정 사항입니다. 이름에 공백과 비 ASCII 문자가 포함된 표준 사용자로 경로를 확인했습니다.
  • 실제 하드웨어를 사용한 FAT 볼륨입니다. "확인되지 않음" 응답은 단위 테스트로 검증되었습니다.
  • 두 번째 Collie 작업이 거부되는 경우이며, 단위 테스트로만 검증되었습니다.
  • 로그아웃 없이 탐색기(Explorer)가 새 PATH를 인식하는지 여부, 그리고 표준 사용자의 PATH 편집입니다.
  • 실제 엔진을 사용한 local-cli 음성 제공자입니다. 정리 기능은 테스트 명령으로 테스트되었습니다. Collie는 해당 명령의 프로세스 트리를 종료하지만, 이미 종료된 도우미가 시작한 프로세스는 더 오래 유지될 수 있습니다(음성 입력 및 Web Push).

GitHub에서 이 페이지 수정하기

The rest of the documentation