Collie 설치

시스템에 Collie를 설치하고 시작한 다음 스마트폰에 추가합니다. 먼저 보안을 읽으십시오. Collie는 설계상 시스템에 대한 원격 셸 접근을 노출합니다.

시작하기 전에

Collie에는 프런트 도어가 필요합니다. HTTPS를 통해 서비스를 제공하고 사용자 본인만 접근하도록 제한하는 수단입니다.

기본 프런트 도어는 Tailscale입니다. collie start이(가) 대신 tailscale serve을(를) 실행하며, 스마트폰은 비공개 Tailscale 네트워크인 tailnet을 통해 Collie에 접속합니다. 이 문서의 나머지 내용은 Tailscale을 기준으로 설명합니다. ID 인식 프록시, 리버스 프록시, Cloudflare Tunnel 또는 NetBird를 대신 사용하는 방법은 프런트 도어 제품별 설정을(를) 참조하십시오.

Tailscale을 사용하는 경우 다음 세 가지를 준비하십시오.

1. 01
   호스트에 Tailscale을 설치하고 tailscale up을(를) 실행하여 tailnet에 추가합니다.
2. 02
   관리 콘솔을(를) 열고 Enable HTTPS을(를) 선택하여 tailnet에 HTTPS 인증서를 활성화합니다.
3. 03
   스마트폰에 Tailscale 앱을 설치하고 동일한 계정으로 로그인하여 동일한 tailnet에 추가합니다.

HTTPS가 꺼져 있으면 collie start이(가) 오류를 내며 종료됩니다. 또한 스마트폰에서 Collie를 홈 화면에 설치하고 Web Push를 수신하려면 HTTPS가 필요합니다.

두 가지 실행 방법

모든 Collie는 두 가지 유형 중 하나이며, 이 페이지의 모든 명령어는 각 유형별로 한 번씩 표기되어 있습니다. 해당하는 열을 선택하고 문서의 나머지 부분에서도 그대로 따르십시오.

collie doctor은(는) 이 설치 환경에서 실제로 읽는 설정 파일을 config-file 줄 아래에 표시합니다.

Herdr 플러그인도 동일한 collie 바이너리입니다. 액션이 바이너리로 전달됩니다(Herdr 작업). 플러그인 설치 환경에서는 PATH에 collie이(가) 없으므로 액션이 없는 동사(pair, qr, logs, link, devices, stt, config)는 플러그인 디렉터리에서 bin/collie <verb> 형식으로 실행합니다.

Herdr는 Collie가 미러링할 수 있는 5개 멀티플렉서(Herdr, tmux, zellij, tuios, tern) 중 하나이기도 합니다. 어떤 대상을 미러링할지는 별개의 선택 사항입니다 (멀티플렉서 지정). 독립형 Collie는 Herdr를 미러링할 수 있고, Herdr 플러그인은 tmux를 미러링할 수 있습니다.

요구 사항

Collie는 Linux 및 macOS에서 실행됩니다. Herdr 환경의 x64 Windows 11은 지원되는 호스트이지만 아직 실험 단계로 표시되어 있습니다. Windows 지원을 참고하십시오.

참고. Collie는 최소 tmux 또는 zellij 버전을 강제하지 않습니다. 어댑터는 tmux 3.4, tmux 3.6b 및 zellij 0.44.2를 기준으로 테스트되었습니다. 한 가지 tmux 예외 사항이 처리되어 있습니다. window-size manual을(를) 사용하는 서버에서 3.7 미만의 tmux는 윈도우 생성 시 비정상 종료됩니다. Collie는 요청을 차단하고 tmux set -g window-size latest을(를) 실행하도록 안내합니다.

해당 기능에만 필요한 선택적 의존성:

설치

아래에서 사용 중인 시스템을 찾고 명령어를 실행한 다음 시작(으)로 이동하십시오.

Linux

curl -fsSL https://colliepwa.dev/install.sh | sh
collie start

스크립트가 x86_64 또는 arm64용으로 사전 빌드된 바이너리를 설치합니다. 스크립트의 동작 방식과 특정 버전을 고정하는 방법은 독립형에서 설명합니다.

collie start는 브릿지를 systemd --user 서비스로 실행합니다. 로그아웃하면 중지됩니다. SSH로 접속하는 서버에서 로그아웃 및 재부팅 후에도 계속 실행되도록 유지하려면 다음을 실행하십시오:

loginctl enable-linger $USER

자세한 내용은 재부팅 후에도 유지하기을(를) 참조하십시오.

Arch Linux 및 Omarchy

git clone https://github.com/AltanS/collie.git && cd collie/packaging/aur
makepkg -si
collie start

collie-bin는 아직 AUR이나 Omarchy의 저장소에 없습니다. 지금은 이 저장소의 PKGBUILD에서 빌드하십시오. 컴파일 없이 사전 빌드된 바이너리를 다운로드합니다. 패키지가 게시되면 sudo pacman -S collie-bin(Omarchy) 또는 paru -S collie-bin(AUR)가 클론을 대체합니다.

Omarchy에는 tmux와 Herdr가 포함되어 있습니다. 처음 시작할 때 미러링할 대상을 지정해야 합니다(예: COLLIE_MUX=herdr collie start). 패키지 세부 정보 아래의 Arch 및 Omarchy에서 레이아웃, 업데이트, 제거를 다룹니다.

NixOS 및 Nix

nix profile install github:AltanS/collie#collie
collie start

이는 NixOS 및 x86_64-linux, aarch64-linux, aarch64-darwin 환경에서 Nix를 사용하는 모든 시스템에서 작동합니다. 아직 NixOS 모듈은 없습니다. 나머지 내용은 패키지 세부 정보의 Nix에 있습니다.

macOS

curl -fsSL https://colliepwa.dev/install.sh | sh
collie start

배포된 Mac 바이너리는 Apple Silicon(macos-arm64) 및 Intel(macos-x64)을 지원하며, Bun 빌드가 링크하는 최소 버전인 macOS 13 이상 이상이 필요합니다. Intel 바이너리는 Bun의 baseline 타깃을 사용하므로 AVX2가 없는 Mac에서도 실행됩니다.

collie start는 ~/Library/LaunchAgents에 launchd 에이전트를 등록합니다. 로그인 시 Collie를 시작하고 실패 시 다시 시작합니다. 또한 tailscale serve을(를) 실행하므로 tailscale 명령이 PATH에 있어야 합니다. Mac용 Tailscale 앱의 설정에서 해당 명령을 설치할 수 있습니다.

참고. SSH로만 접속한 Mac에는 launchd용 로그인 세션이 없습니다. collie start는 이를 보고하고 감시 없이 백그라운드에서 브릿지를 실행합니다. 실패 시 재시작되지 않으며 로그인 시에도 실행되지 않습니다.

macOS에는 아직 패키지가 없습니다. Mac에서는 mise이(가) 작동하며, aarch64-darwin Nix 출력도 작동합니다.

Windows 지원 (실험 단계)

실험적 기능입니다. 설치 테스트는 Windows 11 가상 머신에서 공개 v1.16.0 릴리스를 대상으로 진행되었으며, 업데이트는 릴리스 파일의 로컬 사본을 대상으로 리허설되었습니다. Tailscale Serve를 통한 HTTP 기반 휴대폰 접속도 실행되었습니다. 실제 두 릴리스 간의 업데이트와 HTTPS 방식의 휴대폰 접속은 아직 테스트되지 않았습니다. 이제부터 릴리스 검사에는 Windows zip 파일이 필수입니다. Linux 핫픽스의 경우에만 메인테이너가 이를 무시할 수 있습니다. "지원됨"은 메인테이너가 코드를 소유하고 테스트함을 의미하며, "실험적" 상태는 Windows 페이지의 조건이 모두 충족될 때까지 유지됩니다. Windows 환경의 Collie에 전체 페이지가 있습니다.

install.ps1을(를) 실행하십시오. Bun, Git 또는 bash이(가) 필요하지 않습니다:

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

그런 다음 새 터미널을 열고 Herdr를 시작하십시오. Herdr가 해당 터미널을 차지하므로, 두 번째 터미널이나 Herdr 창을 열고 거기서 collie start을(를) 실행하십시오. 설치부터 휴대폰 연결까지에 휴대폰에서 Collie를 여는 방법을 포함한 모든 단계가 나와 있습니다.

시작하기 전에 알아두어야 할 사항:

• —
  x64 환경의 Windows 11만 지원하며, Herdr 환경에서만 동작합니다. tmux, zellij, Windows 10 및 Windows on ARM은 지원 대상이 아닙니다.
• —
  바이너리가 서명되지 않았습니다. 실행 전에 SmartScreen 안내가 표시될 수 있으며, Smart App Control이 실행을 차단할 수 있습니다. Windows 페이지.
• —
  주소는 직접 공개합니다. Linux 및 macOS에서는 collie start이(가) 대신 tailscale serve을(를) 실행합니다. Windows에서는 실행되지 않으므로 수동으로 실행해야 합니다. 휴대폰에서 접속하기에는 Tailscale 관련 단계가 나와 있고, 변형 C에서는 리버스 프록시를 다룹니다.
• —
  이번 릴리스에서는 Windows 머신이 crew에 참여할 수 없습니다.
• —
  소스 코드 빌드에는 Git for Windows의 bash이 필요합니다. zip 설치에는 툴체인이 필요하지 않습니다.
• —
  Windows에서는 소스 체크아웃이 자체 업데이트되지 않습니다. zip 설치로 전환하는 작업은 일회성 수동 절차입니다. collie uninstall을 실행한 다음 install.ps1를 실행하십시오. 이후에는 collie update 명령이 작동합니다. 자세한 내용은 업데이트에 있습니다.

독립형

설치 스크립트는 최신 릴리스를 ~/.local/share/collie(COLLIE_DIR)에 다운로드하고 바이너리를 ~/.local/bin/collie에 링크합니다.

curl -fsSL https://colliepwa.dev/install.sh | sh
collie start

최신 안정 릴리스를 가져오며 기존 설치본은 그대로 둡니다. 업데이트하려면 collie update을(를) 사용하십시오. 공식 소스는 저장소의 scripts/install.sh입니다. sudo을(를) 호출하지 않는 한 페이지짜리 POSIX sh 스크립트입니다. 실행하기 전에 읽어보십시오:

curl -fsSL https://raw.githubusercontent.com/AltanS/collie/main/scripts/install.sh | less
curl -fsSL https://raw.githubusercontent.com/AltanS/collie/main/scripts/install.sh | sh

~/.local/bin이 PATH에 없으면 바이너리를 직접 실행하십시오:

~/.local/share/collie/current/bin/collie version

버전을 고정하거나 기존 설치본을 수정하려면(collie가 실행되지 않을 때 참조):

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

이 스크립트는 GitHub API에 릴리스 정보를 쿼리하며, IP 주소당 속도 제한이 적용됩니다. HTTP 403이(가) 반환되면 위와 같이 버전을 고정하거나 GH_TOKEN을(를) 범위가 없는 토큰으로 설정하십시오. GitHub에서 릴리스 확인 속도를 제한하는 경우을(를) 참조하십시오.

시험판의 경우 --beta을(를) 전달하십시오. 최신 시험판을 선택하며, 설치 후 정식 릴리스가 나올 때까지 해당 메이저 버전의 시험판을 계속 추적합니다(시험판).

소스에서 동일한 결과 빌드

# 1. Clone and checkout latest stable tag
git clone https://github.com/AltanS/collie.git ~/.local/share/collie
cd ~/.local/share/collie
git checkout --detach "$(git tag --list 'v*' | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)"

# 2. Build runtime and UI
bash scripts/collie-ctl.sh build

# 3. Verify
bin/collie version

# 4. Optional: link to PATH
bin/collie link

소스 빌드에는 Bun과 git이 필요합니다. bin/collie start을(를) 실행하거나 링크한 후 collie start을(를) 실행하여 시작하십시오.

Herdr 플러그인

herdr plugin install AltanS/collie
herdr plugin action invoke start --plugin herdr.collie

먼저 Herdr 서버를 시작하십시오(herdr 또는 herdr server &). 이는 Linux와 macOS에서 작동합니다.

로컬 클론에서 대신 설치하려면:

git clone https://github.com/AltanS/collie.git && cd collie
herdr plugin link "$(pwd)"
herdr plugin action invoke start --plugin herdr.collie

시험판의 경우 herdr plugin install AltanS/collie --ref <tag> --yes을(를) 사용하여 태그를 설치하십시오. 이것으로 활성화가 완료됩니다(시험판).

패키지 사용

패키지는 패키지 관리자가 관리하는 독립형 설치본입니다. 설치, 업데이트 및 제거를 수행합니다. 각 관리자별 명령은 위쪽 및 패키지 세부 정보 아래에 나와 있으며, Linux 및 macOS용 mise도 함께 제공됩니다.

패키지는 Herdr 플러그인이 아닙니다. Herdr에 Collie의 버튼을 표시하려면 설치된 트리를 한 번 링크하십시오:

herdr plugin link /opt/collie

Herdr는 /opt을(를) 검색하지 않으므로 패키지를 자동으로 감지하지 않습니다. 플러그인의 update 및 update-major 작업은 실행을 거부하고 패키지 관리자를 안내합니다. 이는 의도된 동작입니다. 패키지 관리자가 이 트리를 관리하기 때문입니다.

멀티플렉서 지정

Collie는 세 가지 백엔드 중 하나를 미러링합니다: COLLIE_MUX=herdr(기본값), tmux, zellij.

처음 시작하기 전에 설정할 필요는 없습니다. start는 활성 Herdr 소켓, 실행 중인 tmux 서버, zellij 세션을 찾아서 발견한 항목을 출력하고 선택 사항을 설정 파일 .env에 작성하며, 필요한 경우 파일을 생성합니다.

터미널 프롬프트가 없으면 start는 발견된 단일 백엔드를 선택하여 보고합니다. 아무것도 찾지 못하거나 여러 개를 찾으면 시작을 거부하고 COLLIE_MUX을(를) 설정하라는 메시지를 표시합니다.

미리 선택하려면 처음 시작하기 전에 설정을 미리 채워 두십시오:

mkdir -p ~/.config/collie
cp ~/.local/share/collie/current/.env.example ~/.config/collie/.env

해당 경로는 설치 스크립트용입니다. 소스 체크아웃의 경우 루트에 .env.example이(가) 있습니다. Herdr 플러그인에서는 파일이 herdr plugin config-dir herdr.collie이(가) 가리키는 위치에 있습니다. 그런 다음 백엔드와 엔드포인트를 설정하십시오:

COLLIE_MUX=tmux                                           # or: zellij
# zellij instead: COLLIE_MUX_ENDPOINT_ZELLIJ=<session>
COLLIE_MUX_ENDPOINT_TMUX=/run/user/1000/collie-tmux.sock

주의. 시작한 후에 해당 cp 명령을 실행하지 마십시오. start에서 방금 기록한 COLLIE_MUX 값을 덮어씁니다.

설정이 변경되면 나중에 이 파일을 편집하십시오. Collie를 multiplexer로 지정하기을 참조하십시오.

시작

herdr plugin action invoke start --plugin herdr.collie   # Herdr plugin
collie start                                             # standalone

start은 다음 작업을 수행합니다:

1. 01
   누락된 경우 web/dist을 빌드합니다.
2. 02
   systemd --user(또는 launchd/nohup) 하에서 브리지를 실행합니다.
3. 03
   tailscale serve --bg 8787을 실행합니다(HTTPS :443 → 127.0.0.1:8787).
4. 04
   연결 배너를 출력합니다.

첫 실행: 표시되는 내용

collie start의 출력(Herdr 실행은 JSON을 반환하며, herdr plugin log list --plugin herdr.collie으로 로그를 확인합니다):

$ collie start
building web UI (first run)…                    # linked clone only; a GitHub install already built
…bun install · typecheck · vite build output…
bridge started (systemd --user: collie)
tailscale serve (https) → tailnet :443 -> 127.0.0.1:8787

  ✓ Collie is running  ·  v1.0.0+b158755
    service   systemd --user (collie) · active
    local     http://127.0.0.1:8787
    tailnet   https://myhost.tail1234.ts.net

상태 확인에 실패하면(⚠ Collie isn't answering on :8787 yet), 문제 해결을 참조하십시오.

브릿지는 systemd --user 서비스 또는 macOS launchd 에이전트로 실행됩니다. 로그인 시 시작되며 오류 발생 시 재시작됩니다 (ARCHITECTURE.md §3). Linux에서는 loginctl enable-linger $USER가 재부팅 후에도 계속 실행되도록 유지합니다 (재부팅 후에도 유지하기).

설정에서 사용자 접근을 구성하고 페어링을(를) 통해 기기 접근을 구성하십시오(collie pair).

정상 작동 확인

상태 및 로그 확인:

$ collie status

  ✓ Collie is running  ·  v1.0.0+b158755
    service   systemd --user (collie) · active
    local     http://127.0.0.1:8787
    tailnet   https://myhost.tail1234.ts.net

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

$ collie logs        # journal timestamps trimmed here
[push] disabled (no VAPID keys configured)
[bridge] listening on http://127.0.0.1:8787  (poll 1500ms)
[bridge] WARNING: COLLIE_TRUSTED_USER is empty — any tailnet device/user that reaches the bridge is checked by its pairing token alone. Set it to your tailnet login (see README → Variant A).

접근을 제한하려면 .env 파일에 COLLIE_TRUSTED_USER=you@example.com을 설정하고 collie restart 명령을 실행합니다(설정). 대시보드 콘텐츠가 표시되지 않는 경우 문제 해결 문서를 참고합니다.

휴대폰에 추가하기

휴대폰에서 Collie를 열고, 휴대폰을 페어링한 다음, Collie를 홈 화면에 추가하십시오.

1. 01
   휴대폰의 Tailscale 앱이 호스트와 동일한 tailnet을 공유하는지 확인하십시오.
2. 02
   호스트에서 collie qr을 실행하고 코드를 스캔하거나, collie url에서 출력하는 URL을 여십시오.
3. 03
   호스트에서 collie pair을 실행하고 해당 QR 코드를 스캔하십시오.

collie pair의 QR 코드를 스캔하면 코드가 입력된 상태로 설정 → 시스템 → 페어링된 기기가 열립니다. 설정 → 시스템 → 페어링된 기기를 직접 열어 수동으로 입력할 수도 있습니다. Collie는 페어링되기 전까지 어떤 기기에도 응답하지 않으므로, 페어링 전에는 대시보드에 이 기기 페어링만 표시됩니다 (기기 페어링).

Collie는 웹 앱입니다. 브라우저가 앱 스토어 없이 홈 화면에 추가하여 독립형 아이콘과 전체 화면 보기를 제공합니다.

iPhone 및 iPad

1. 01
   Safari에서 Collie URL을 여십시오.
2. 02
   공유을 탭한 다음 홈 화면에 추가을 탭하십시오.
3. 03
   추가을 탭하십시오.

iOS 16.4 이상에서는 Chrome, Edge, Firefox도 공유 메뉴에서 홈 화면에 추가 항목을 제공합니다. 웹 앱으로 열기 옵션이 보이면 선택된 상태로 두십시오.

Safari는 설치 버튼을 제공하지 않습니다. 완료할 때까지 Collie의 설정에 이 절차가 포함된 설치 카드가 대신 표시됩니다.

참고. iPhone 또는 iPad의 경우 Web Push에는 iOS 16.4 이상이 필요하며 홈 화면 아이콘에서 실행할 때만 작동합니다. 해당 아이콘으로 Collie를 연 다음 설정에서 알림을 활성화하십시오.

Android

1. 01
   Chrome에서 Collie URL을 여십시오.
2. 02
   Collie의 설정으로 이동하여 상단 카드의 설치을 탭하십시오.

이 카드는 Chrome에서 설치를 제공하면 나타납니다. 나타나지 않으면 Chrome 메뉴(⋮)를 열고 홈 화면에 추가을 탭한 다음 설치을 탭하십시오. 일부 Chrome 빌드에서는 이 항목이 앱 설치로 표시됩니다. Firefox와 Samsung Internet은 기본 메뉴에서 홈 화면에 추가 항목을 사용합니다.

Android는 일반 브라우저 탭 내에서 Web Push를 지원합니다. 설치는 홈 아이콘과 전체 화면 모드만 추가합니다.

데스크톱

Chrome과 Edge는 주소 표시줄에 설치 아이콘을 표시하며, 설정의 설치 카드에도 표시합니다. macOS의 경우 Safari 17 이상 버전에서는 파일 → Dock에 추가을(를) 사용합니다.

모든 기기 관련 참고 사항

• —
  설치에는 HTTPS가 필요합니다. COLLIE_SERVE_MODE=http 환경에서 브라우저는 서비스 워커를 비활성화하므로 Collie가 일반 브라우저 탭으로 제한됩니다.
• —
  개발 빌드(릴리스 태그가 아닌 체크아웃)는 릴리스 버전과의 혼동을 피하기 위해 주황색 아이콘의 Collie (dev)(으)로 설치됩니다.
• —
  페어링은 단일 기기에 바인딩됩니다. 사용할 모든 스마트폰, 태블릿, 브라우저를 각각 페어링하십시오.
• —
  푸시 알림에는 호스트 키가 필요합니다: Web Push.

최초 실행

기기에서 Collie를 처음 열고 대시보드를 로드하면 인트로 화면에 현재 설정이 요약되어 표시됩니다. 활성 멀티플렉서, 미러링된 호스트, 실행 중인 창, 입력이 필요한 창, 크루 머신 수, 쓰기 권한이 나열됩니다.

그 아래에는 기기 페어링, 작업 시작, 알림 활성화, Collie를 홈 화면에 저장하기 등 최대 두 가지 작업이 제안됩니다. 마지막에는 실행할 수 있는 여섯 가지 핵심 작업이 표시됩니다.

앱은 로드 시 이 화면을 읽음으로 표시하므로 탭을 닫아도 다시 표시되지 않습니다. 나중에 설정에서 첫 화면 다시 보기을(를) 탭하여 확인할 수 있습니다.

업데이트

명령어 하나로 현재 메이저 버전의 최신 릴리스를 가져옵니다.

herdr plugin action invoke update --plugin herdr.collie   # Herdr plugin
collie update                                             # standalone

새 버전을 이전 버전 옆에 스테이징하고 전환한 후 bridge를 재시작하며, 새 버전이 응답하지 않으면 롤백합니다.

패키지 설치 환경은 자체 패키지 관리자로 업데이트한 후 재시작해야 합니다. 패키지 관리자는 파일만 교체할 뿐 아무것도 재시작하지 않기 때문입니다.

sudo pacman -Syu collie-bin                 # Omarchy; on the AUR: paru -S collie-bin
nix profile upgrade collie                  # Nix
mise upgrade --bump github:AltanS/collie    # mise
collie restart

패키지 설치 환경에서는 collie update 명령이 실행을 거부하고 대신 해당 명령어를 안내합니다. 휴대폰에서도 업데이트 버튼이 있어야 할 자리에 동일한 명령어가 표시됩니다.

메이저 버전을 올리는 작업은 사용자의 동의를 거치는 별도의 단계입니다.

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

휴대폰에서도 정기 업데이트를 수행할 수 있습니다. 설정 → 시스템 → 업데이트에서 한 번 탭하면 되며, crew lead에서는 한 번의 탭으로 모든 멤버를 동일하게 맞춥니다. 휴대폰 경로, 사전 점검, 롤백, crew 및 업데이트가 멈췄을 때의 대처 방법은 관리 및 업데이트을 참조하십시오.

제거

다음 순서대로 진행하는 세 단계입니다. 각 단계는 해당 레이어만 제거하고 다른 것은 건드리지 않습니다.

1. 서비스 및 포트 매핑을 제거합니다. 이렇게 하면 브리지가 중지되고, systemd --user 유닛(macOS의 경우 launchd 에이전트)이 삭제되며, Collie 자체의 tailscale serve 매핑이 해제됩니다. 프로그램 파일과 .env는 유지됩니다.

herdr plugin action invoke uninstall --plugin herdr.collie   # Herdr plugin
collie uninstall                                             # standalone

2. 프로그램을 제거합니다.

herdr plugin uninstall herdr.collie      # Herdr plugin, installed from GitHub
herdr plugin unlink herdr.collie         # Herdr plugin, a linked clone or a linked package

collie unlink                            # standalone: drop the ~/.local/bin/collie symlink
rm -rf ~/.local/share/collie             # standalone: the install script's tree, or $COLLIE_DIR

sudo pacman -Rns collie-bin              # package: Arch and Omarchy
nix profile remove collie                # package: Nix
mise uninstall github:AltanS/collie@1.14.2  # package: mise, the version
mise unuse github:AltanS/collie             # package: mise, the config line

연결된 클론은 사용자가 직접 체크아웃한 복사본입니다. unlink 명령은 Herdr 등록을 해제하며 디렉터리는 삭제하거나 유지할 수 있도록 그대로 남겨둡니다.

3. 직접 생성한 파일까지 완전히 제거하려면 해당 파일을 삭제합니다. 위의 작업은 이 파일들을 건드리지 않으므로, 다시 설치해도 페어링 정보와 설정을 다시 인식합니다.

아무것도 제거하지 않고 일시 중지하려면 stop 명령으로 충분합니다.

herdr plugin action invoke stop --plugin herdr.collie   # Herdr plugin
collie stop                                             # standalone

패키지 세부 정보

PKGBUILD, Nix 표현식 및 관련 설명은 이 저장소의 packaging/에 있습니다. 모든 패키지에는 릴리스에 이미 게시된 컴파일된 바이너리가 포함되어 있으므로 머신에서 아무것도 빌드하지 않습니다. Bun도, git도, 컴파일 작업도 필요하지 않습니다. 전체 릴리스 폴더는 단일 접두사 아래에 위치하며, PATH의 collie은(는) 해당 위치를 가리키는 심볼릭 링크로 설정됩니다. macOS용 패키지는 아직 없으며, aarch64-darwin flake 출력이 가장 가깝습니다.

Arch

collie-bin은(는) 아직 AUR에 없습니다. AUR의 신규 계정 등록이 일시 중지되었으며, 등록이 재개되면 당사 계정에서 패키지를 게시할 예정입니다. 그전까지는 이 리포지토리의 클론에서 빌드하십시오.

git clone https://github.com/AltanS/collie.git && cd collie/packaging/aur
makepkg -si
collie start

makepkg은(는) 사용자의 아키텍처에 맞는 릴리스 tarball을 다운로드하고, 릴리스의 무결성 매니페스트와 sha256을 대조하여 압축을 풉니다. Bun이나 다른 항목의 git 클론이 필요 없으며 컴파일도 하지 않습니다.

AUR에 등록된 후의 경우, AUR 헬퍼가 동일한 PKGBUILD을(를) 설치합니다.

paru -S collie-bin     # or: yay -S collie-bin
collie start

이후 업데이트는 설치 시 사용한 것과 동일한 명령인 paru -S collie-bin 또는 yay -S collie-bin입니다. sudo pacman -Syu collie-bin은(는) Omarchy와 같이 리포지토리에 패키지가 포함된 경우에만 작동합니다.

패키지는 릴리스 트리를 /opt/collie에 설치하고 /usr/bin/collie을(를) 그 안의 심볼릭 링크로 설치합니다. README.md, CHANGELOG.md, docs/은(는) /usr/share/doc/collie-bin/에 위치하며 라이선스는 /usr/share/licenses/collie-bin/에 위치합니다. collie을(를) 제공하고 이와 충돌하므로, 해당 패키지와 향후 소스 패키지를 동시에 설치할 수 없습니다. systemd 유닛은 활성화하지 않습니다. 다른 설치 후와 마찬가지로 collie start이(가) 자체 --user 유닛을 작성합니다.

참고. 업그레이드 후에는 항상 collie restart을(를) 실행하십시오. pacman은(는) 파일을 교체할 뿐 아무것도 재시작하지 않으므로, 서비스를 재시작할 때까지 삭제된 바이너리를 기반으로 이전 빌드를 계속 제공합니다. collie doctor은(는) 이를 restart-pending(으)로 보고하며, 휴대전화에는 실행할 명령과 함께 "Collie was replaced on disk. Restart it."이 표시됩니다.

제거의 세 단계로 제거하십시오. collie uninstall을(를) 실행한 다음, 링크한 경우에만 herdr plugin unlink herdr.collie을(를) 실행하고, 마지막으로 sudo pacman -Rns collie-bin을(를) 실행합니다. pacman은 /opt/collie 및 /usr/bin/collie만 제거하고 다른 것은 건드리지 않습니다.

Omarchy

sudo pacman -S collie-bin
COLLIE_MUX=herdr collie start

Omarchy에는 tmux와 Herdr가 모두 포함되어 있으며 Collie는 설치당 하나의 멀티플렉서만 미러링하므로, 최초 시작 시 제어할 대상을 지정해야 합니다. 인식 가능한 두 대상 중 하나를 임의로 추측하지 않습니다. start 명령은 해당 이름을 Collie의 .env에 기록하며(Herdr가 있는 호스트에서는 ~/.config/herdr/plugins/config/herdr.collie/.env), 이후 시작할 때는 collie start 명령을 사용합니다.

이 기능은 collie-bin이(가) Omarchy 자체 패키지 리포지토리에 포함된 후 작동하며, 이를 추가하는 풀 리퀘스트는 아직 병합되지 않았습니다. 병합되기 전까지는 위의 다른 Arch 호스트와 마찬가지로 packaging/aur에서 makepkg -si(으)로 동일한 패키지를 빌드하십시오.

그 후 업데이트는 머신을 업데이트할 때 이미 실행하는 명령어인 sudo pacman -Syu(으)로 진행됩니다. pkgs.omarchy.org은(는) 실제 pacman 저장소이므로 AUR 헬퍼가 개입하지 않습니다. 어느 쪽이든 동일한 PKGBUILD 및 동일한 /opt/collie 레이아웃을 사용합니다.

참고. 업데이트는 패키지 관리자에서 제공되며, Collie는 여기서 자체 업데이트를 수행하지 않습니다. 대신 collie update이(가) 거부됩니다. 휴대전화의 업데이트 표시줄에 "Collie x.y.z available via pacman."이 표시되고, 패키지 관리자가 해당 폴더를 관리하므로 업데이트 페이지에는 업데이트 버튼 대신 복사할 명령이 표시됩니다. Collie는 리포지토리 표기법인 sudo pacman -Syu collie-bin 형식을 지정합니다. AUR 설치에서는 헬퍼를 대신 실행하십시오. 위에서 언급한 이유로 업그레이드 후 collie restart을(를) 실행하십시오. pacman은 아무것도 재시작하지 않습니다.

crew 환경에서 이 머신은 휴대폰으로부터 업데이트를 직접 받지 않습니다. crew에서는 이를 "waits for the package manager" 상태로 표시하며, 해당 머신에서 도우미 스크립트를 직접 실행할 때만 업데이트됩니다.

위의 Arch와 동일한 세 단계로 제거하십시오.

Nix

nix profile install github:AltanS/collie#collie
collie start

이 flake는 x86_64-linux, aarch64-linux, aarch64-darwin 플랫폼용 packages.<system>.collie 패키지를 내보냅니다. 릴리스의 자체 무결성 매니페스트에 있는 sha256을 기반으로 해당 플랫폼의 릴리스 tarball을 가져오고, Linux에서는 바이너리의 인터프리터 경로를 패치하며, <store-path>/lib/collie 경로에 릴리스 트리를 설치하고 bin/collie 심볼릭 링크를 생성합니다. 설치하지 않고 일회성으로 실행하려면 nix run github:AltanS/collie#collie -- doctor 명령을 사용하십시오.

의도적으로 소스 빌드를 지원하지 않습니다. 종속 항목을 설치하려면 네트워크 연결이 필요하지만 Nix derivation에는 네트워크 접근 권한이 없으므로, 패키지는 릴리스에 이미 게시되어 체크섬 검증을 마친 바이너리를 래핑합니다.

아직 NixOS 모듈이 없으며 flake 패키지만 제공되므로 nix profile 경로를 사용해야 합니다. 위와 같이 프로필에 설치하거나, home-manager 또는 environment.systemPackages 목록에 flake 출력을 직접 추가하십시오.

참고. 업데이트는 nix를 통해 제공되며, Collie는 이 환경에서 자체 업데이트를 수행하지 않습니다. collie update 명령은 업데이트를 거부하고 대신 nix profile upgrade collie 명령을 안내하며, 휴대전화 화면에는 업데이트 버튼 대신 해당 명령과 함께 새 버전이 표시됩니다.

crew 환경에서 이 머신은 휴대폰으로부터 업데이트를 직접 받지 않습니다. crew에서는 이를 "waits for the package manager" 상태로 표시하며, 해당 머신에서 nix를 실행할 때만 업데이트됩니다.

먼저 collie uninstall 명령으로 제거한 다음, 아래를 실행하십시오.

nix profile remove collie

그러면 프로필에서 스토어 경로만 삭제되고 다른 것은 유지됩니다. 사용자의 고유 파일은 제거에 나열된 대로 유지됩니다.

macOS의 Home Manager 에이전트

collie status
launchctl print "user/$(id -u)/herdr.collie"

collie status은 gui/<uid> 및 user/<uid> 모두에서 인스턴스의 레이블을 검색하고 해당 도메인 및 프로세스 상태를 보고합니다. 두 도메인에 모두 레이블이 포함된 경우 둘 다 보고하며, 중지된 GUI 에이전트가 실행 중인 백그라운드 에이전트를 숨기지 않습니다. 환경 재정의는 필요하지 않습니다.

기존의 Home Manager 관리 Collie 에이전트의 경우 다음 설정을 통해 백그라운드 도메인을 선택합니다 (Home Manager 26.11 이상):

launchd.agents.collie = {
  domain = "user";
  config.Label = "herdr.collie";
};

이는 에이전트 정의에 추가되는 내용이며 완전한 서비스 모듈이 아닙니다. 명령, 환경 및 로그 경로는 계속 Home Manager에 구성해 두십시오. Collie가 관리 대상 plist를 다시 작성하지 않고 launchd가 브리지를 감독하도록 브리지를 collie start가 아닌 collie _exec-bridge으로 실행하십시오. 자격 증명과 페어링 상태는 Nix 저장소 외부에 보관하십시오. 프런트 도어는 collie serve을 사용하여 별도로 구성하거나 외부 프록시 설정를 사용하십시오.

이름이 지정된 인스턴스의 경우 에이전트와 CLI 환경에서 레이블 herdr.collie-<name>을 사용하고 동일한 COLLIE_INSTANCE, COLLIE_PORT 및 구성 디렉터리를 사용하십시오 (다중 인스턴스).

참고. Home Manager가 서비스 수명 주기를 소유합니다. collie start, stop, restart 또는 uninstall를 실행하는 대신 해당 선언을 업데이트하거나 제거하고 Home Manager를 활성화하십시오. 해당 명령은 여전히 Collie의 GUI 도메인 에이전트를 관리하며 상태 검색이 소유권을 이전하지는 않습니다. collie pair, devices, url 및 logs은 평소대로 계속 사용하십시오.

mise

mise use -g github:AltanS/collie@1.14.2
collie start

mise use -g은(는) 도구를 ~/.config/mise/config.toml에 작성하고 릴리스의 bin/을(를) PATH에 추가합니다. github 백엔드가 해당 플랫폼의 릴리스 tarball을 가져오므로 Linux 및 macOS에서 Bun과 컴파일 없이 작동합니다. 전체 트리는 web/dist 및 herdr-plugin.toml을(를) 포함하여 ~/.local/share/mise/installs/github-altan-s-collie/<version>/ 아래에 배치되며, collie은(는) 여기에서 자체 루트를 확인합니다.

동일한 mise use 라인과 최신 태그를 사용하여 새 버전을 가져오거나 mise가 최신 버전을 선택하도록 하십시오.

mise upgrade --bump github:AltanS/collie
collie restart

중요한 플래그는 --bump입니다. 고정된 1.14.2은(는) 단일 버전 범위이므로, 일반 mise upgrade은(는) 도구가 최신 상태라고 보고하며 아무것도 변경하지 않습니다.

재시작은 필수입니다. 모든 버전은 자체 디렉터리를 가지며, collie start은(는) 실행된 디렉터리를 서비스 정의에 기록하므로 재시작할 때까지 서비스가 이전 디렉터리에서 이전 버전을 계속 제공합니다. collie restart은(는) 해당 정의를 새 경로로 덮어씁니다. Linux에서는 systemd --user 유닛, macOS에서는 ~/Library/LaunchAgents plist입니다. 두 환경 모두 하나의 명령으로 처리됩니다.

참고. SSH로만 관리되는 Mac에는 에이전트를 로드할 gui/<uid> 도메인이 없습니다. 이 경우 collie start이(가) 이를 알리고 관리되지 않는 백그라운드 브리지를 대신 실행하며, 실패 시 재시작되지 않고 로그인 시에도 실행되지 않습니다. collie restart은(는) 여전히 새 디렉터리로 전환합니다.

참고. 여기서 collie update은(는) 거부되며, 패키지 관리자 이름을 지정하지 않고 cannot tell how this Collie was installed(이)라고 표시합니다. mise 트리는 홈 디렉터리 내에 위치하며 자체 .git이(가) 없고 상위에 versions/ 레이아웃도 없으므로, Collie는 이를 체크아웃이나 패키지로 인식하지 않습니다. 이 설치 환경에서는 mise가 업데이트를 관리하며, 위의 두 명령으로 전환합니다.

먼저 collie uninstall 명령으로 제거한 다음, 아래를 실행하십시오.

mise uninstall github:AltanS/collie@1.14.2
mise unuse github:AltanS/collie

uninstall은(는) 해당 버전의 디렉터리를 삭제하고, unuse은(는) 설정에서 해당 라인을 제거합니다. 두 경우 모두 도구의 전체 github: 이름을 입력하십시오. 짧은 collie 이름은 upgrade에서 작동하지만 uninstall에서는 작동하지 않습니다. 사용자의 고유 파일은 제거에 나열된 대로 유지됩니다.