Collie installieren

Host-Anforderungen, die zwei Zugangswege und die Ersteinrichtung. Lesen Sie zuerst Sicherheit: Collie gewährt bauartbedingt Remote-Shell-Zugriff auf Ihren Rechner.

Anforderungen

Unterstützte Hosts: Linux und macOS. Windows ist experimentell; siehe Windows.

Hinweis. Es wird keine Mindestversion für tmux oder zellij erzwungen. Die Adapter wurden mit tmux 3.4, tmux 3.6b und zellij 0.44.2 getestet. Ein tmux-Sonderfall wird abgefangen: Auf einem Server mit window-size manual stürzt tmux vor Version 3.7 beim Erstellen eines Fensters ab. Collie blockiert die Anfrage daher und fordert Sie auf, tmux set -g window-size latest auszuführen.

Optionale Abhängigkeiten, die nur für die daneben stehenden Funktionen benötigt werden:

Installation

Drei Installationswege:

• —
  Neuinstallation – das Installationsskript oder dasselbe Ergebnis aus dem Quellcode.
• —
  Über Herdr – Collie wird als Herdr-Plugin eingebunden und über Plugin-Aktionen gesteuert.
• —
  Über ein Paket: Ihr Paketmanager installiert Collie und übernimmt dessen Aktualisierungen.

Herdr ist einer der drei Multiplexer, die Collie spiegeln kann, keine Abhängigkeit des Programms. Welchen Sie spiegeln, ist der Schritt danach.

Neuinstallation

Das Installationsskript lädt das neueste Release nach ~/.local/share/collie (COLLIE_DIR) herunter und verknüpft die Binärdatei mit ~/.local/bin/collie:

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

Es verwendet das neueste stabile Release und fasst eine bereits vorhandene Installation nicht an – dafür ist collie update da. Die kanonische Quelle ist scripts/install.sh im Repository: eine Seite POSIX-sh, die niemals nach sudo fragt.

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

Wenn ~/.local/bin nicht in Ihrem PATH liegt, führen Sie die Binärdatei direkt aus:

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

Um eine Version festzuschreiben oder eine bestehende Installation zu retten (siehe Wenn collie nicht startet):

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

Für Vorabversionen übergeben Sie --beta: Dies wählt die neueste Vorabversion aus, und die Installation folgt danach den Vorabversionen dieser Hauptversion bis zur finalen Veröffentlichung (Vorabversionen).

Dasselbe Ergebnis aus dem Quellcode

# 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

Starten Sie es anschließend. start erstellt ~/.config/collie/ und schreibt Ihre Multiplexer-Auswahl in die Datei .env, sodass Sie vorab nichts manuell anlegen müssen:

bin/collie start

Über Herdr

Starten Sie zuerst den Herdr-Server (herdr oder herdr server &).

Von GitHub:

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

Aus lokalem Quellcode:

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

Verwalten Sie über Herdr-Aktionen. Für eine Vorabversion installieren Sie den Tag mit herdr plugin install AltanS/collie --ref <tag> --yes, was bereits das gesamte Opt-in darstellt (Vorabversionen).

Über ein Paket

Wenn Collie für Ihr System paketiert ist, installieren Sie es wie jede andere Software. Das Paket enthält die kompilierte Binärdatei, die das Release bereits bereitstellt, sodass auf Ihrem Rechner nichts gebaut wird: kein Bun, kein git, keine Kompilierung. Der gesamte Release-Ordner landet unter einem Präfix, mit collie in Ihrem PATH als Symlink darauf.

Ein Paket ist kein Herdr-Plugin, und jedes collie-Verb in Ihrem PATH funktioniert in beiden Fällen gleich. Um die Schaltflächen von Collie in Herdr anzuzeigen, verknüpfen Sie den installierten Verzeichnisbaum einmalig:

herdr plugin link /opt/collie

Herdr durchsucht /opt nicht und findet das Paket daher niemals von selbst. Die Aktionen update und update-major des Plugins verweigern daraufhin die Ausführung und nennen stattdessen Ihre Paketverwaltung. Das ist korrekt und kein Fehler: Dieser Verzeichnisbaum wird von Ihrer Paketverwaltung aktualisiert.

Arch

collie-bin ist noch nicht im AUR. Das AUR hat die Registrierung neuer Konten pausiert, und das Paket wird über unser eigenes Konto veröffentlicht, sobald die Registrierung wieder geöffnet ist. Erstellen Sie es bis dahin aus einem Klon dieses Repositorys:

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

makepkg lädt das Release-Tarball für Ihre Architektur herunter, vergleicht dessen sha256 mit dem Integritätsmanifest des Releases und entpackt es. Kein Bun, kein git-Klon von Drittanbietern, keine Kompilierung.

Sobald es im AUR verfügbar ist, ein AUR-Hilfsprogramm installiert dasselbe PKGBUILD:

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

Spätere Aktualisierungen erfolgen über paru -S collie-bin oder yay -S collie-bin, denselben Befehl, mit dem Sie installiert haben. sudo pacman -Syu collie-bin funktioniert nur dort, wo ein Repository das Paket führt, wie etwa bei Omarchy.

Das Paket installiert den Release-Baum nach /opt/collie und /usr/bin/collie als symbolischen Link dorthin. README.md, CHANGELOG.md und docs/ landen in /usr/share/doc/collie-bin/ und die Lizenz in /usr/share/licenses/collie-bin/. Es stellt collie bereit und steht damit in Konflikt, sodass dieses und ein zukünftiges Quellpaket nicht gleichzeitig installiert sein können. Es aktiviert keine systemd-Unit: collie start schreibt Ihre eigene --user-Unit, wie nach jeder Installation.

Hinweis. Führen Sie collie restart nach jedem Upgrade aus. pacman ersetzt die Dateien und startet nichts neu; der Dienst liefert also weiterhin den alten Build auf einer gelöschten Binärdatei aus, bis Sie ihn neu starten. collie doctor meldet dies als restart-pending, und das Smartphone zeigt "Collie was replaced on disk. Restart it." mit dem auszuführenden Befehl an.

Entfernen Sie es in drei Schritten:

collie uninstall
herdr plugin unlink herdr.collie   # only if you linked it
sudo pacman -Rns collie-bin

collie uninstall stoppt den Dienst, entfernt die systemd --user-Unit und deaktiviert Collies eigenes tailscale serve-Mapping; pacman entfernt anschließend /opt/collie und /usr/bin/collie und sonst nichts. Zwei Ihrer eigenen Verzeichnisse bleiben erhalten, die Sie manuell löschen, wenn Sie sie nicht mehr benötigen: der Zustand unter ~/.local/state/collie/ (oder $COLLIE_STATE_DIR) und das Konfigurationsverzeichnis mit Ihrem .env, das auf einem Host mit Herdr ~/.config/herdr/plugins/config/herdr.collie/ lautet.

Omarchy

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

Omarchy liefert sowohl tmux als auch Herdr aus, und Collie spiegelt einen Multiplexer pro Installation. Daher muss der erste Start festlegen, welcher verwendet werden soll; das Programm rät nicht zwischen zwei sichtbaren Optionen. start schreibt diesen Namen in Collies .env, was auf einem Host mit Herdr ~/.config/herdr/plugins/config/herdr.collie/.env ist, und spätere Starts lauten collie start.

Das funktioniert, sobald collie-bin im eigenen Paket-Repository von Omarchy enthalten ist; der Pull-Request dazu ist noch nicht zusammengeführt. Erstellen Sie dasselbe Paket bis dahin wie oben auf jedem Arch-Host aus packaging/aur mit makepkg -si.

Aktualisierungen erfolgen dann mit sudo pacman -Syu, dem Befehl, den Sie bereits zum Aktualisieren des Systems ausführen. Ein AUR-Hilfsprogramm wird nicht benötigt, da pkgs.omarchy.org ein echtes pacman-Repository ist. Es ist in beiden Fällen dasselbe PKGBUILD und dieselbe /opt/collie-Struktur.

Hinweis. Aktualisierungen kommen von Ihrer Paketverwaltung, und Collie aktualisiert sich hier nicht selbst. collie update lehnt stattdessen ab. Die Statusleiste auf dem Smartphone zeigt "Collie x.y.z available via pacman.", und die Updates-Seite zeigt den zu kopierenden Befehl anstelle einer Update-Schaltfläche, da die Paketverwaltung diesen Ordner verwaltet. Collie nennt die sudo pacman -Syu collie-bin-Form, also den Namen im Repository; führen Sie bei einer AUR-Installation stattdessen Ihr Hilfsprogramm aus. Führen Sie collie restart nach dem Upgrade aus, aus dem oben genannten Grund: pacman startet nichts neu.

In einem pack übernimmt dieser Rechner niemals eine Aktualisierung vom Telefon: Das Pack listet ihn als "wartet auf die Paketverwaltung", und er wird erst angeglichen, wenn Sie Ihren Helper darauf ausführen.

Entfernen Sie es mit denselben drei Schritten wie oben unter Arch beschrieben.

Nix

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

Das Flake exportiert packages.<system>.collie für x86_64-linux, aarch64-linux und aarch64-darwin. Es ruft das Release-Tarball dieser Plattform anhand der sha256 im Integritätsmanifest des Releases ab, patcht den Interpreter der Binärdatei unter Linux und installiert den Release-Baum nach <store-path>/lib/collie mit bin/collie als Symlink darauf. Führen Sie es einmalig ohne Installation mit nix run github:AltanS/collie#collie -- doctor aus.

Es gibt absichtlich keinen Quell-Build: Die Installation der Abhängigkeiten erfordert das Netzwerk und eine Nix-Derivation hat keines, daher verpackt das Paket die Binärdatei, die das Release bereits veröffentlicht und mit einer Prüfsumme versieht.

Es gibt noch kein NixOS-Modul, nur das Flake-Paket, daher ist nix profile der Pfad: Installieren Sie es wie oben in Ihr Profil oder fügen Sie die Flake-Ausgabe selbst zu einer home-manager- oder environment.systemPackages-Liste hinzu.

Hinweis. Aktualisierungen kommen von nix, und Collie aktualisiert sich hier nicht selbst. collie update lehnt ab und nennt stattdessen nix profile upgrade collie, und das Telefon zeigt die neue Version mit diesem Befehl an der Stelle an, an der sich die Aktualisierungsschaltfläche befinden würde.

In einem pack übernimmt dieser Rechner niemals eine Aktualisierung vom Telefon: Das Pack listet ihn als "wartet auf die Paketverwaltung", und er wird erst angeglichen, wenn Sie nix darauf ausführen.

Entfernen Sie es zuerst mit collie stop, dann:

nix profile remove collie

Das entfernt den Store-Pfad aus Ihrem Profil und sonst nichts. Ihre eigenen Dateien bleiben erhalten: Zustand in ~/.local/state/collie (oder $COLLIE_STATE_DIR), Konfiguration in ~/.config/collie und die systemd --user-Unit unter ~/.config/systemd/user/collie.service, die collie start geschrieben hat. Führen Sie collie uninstall vor dem Entfernen des Pakets aus, um diese Unit und die Portzuordnung zu verwerfen.

mise

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

mise use -g schreibt das Werkzeug in ~/.config/mise/config.toml und legt bin/ des Releases in Ihren PATH. Das Backend github ruft das Release-Tarball der jeweiligen Plattform ab, sodass dies unter Linux und macOS ohne Bun und ohne Kompilierung funktioniert. Der gesamte Baum landet unter ~/.local/share/mise/installs/github-altan-s-collie/<version>/, einschließlich web/dist und herdr-plugin.toml, und collie löst das eigene Stammverzeichnis von dort aus auf.

Installieren Sie eine neue Version mit derselben mise use-Zeile und einem neueren Tag oder lassen Sie mise die neueste Version auswählen:

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

--bump ist die entscheidende Option. Ein festgelegtes 1.5.6 ist ein Bereich von genau einer Version, daher meldet ein einfaches mise upgrade das Werkzeug als aktuell und ändert nichts.

Der Neustart ist erforderlich. Jede Version erhält ihr eigenes Verzeichnis, und collie start verankert das Verzeichnis, aus dem es ausgeführt wurde, in der Dienstdefinition. Der Dienst liefert also weiterhin die alte Version aus dem alten Verzeichnis aus, bis Sie ihn neu starten. collie restart schreibt diese Definition mit dem neuen Pfad neu: die systemd --user-Unit unter Linux, die ~/Library/LaunchAgents-plist unter macOS. Ein Befehl auf beiden Systemen.

Hinweis. Ein Mac, der ausschließlich über SSH verwaltet wird, hat keine gui/<uid>-Domäne, in die ein Agent geladen werden kann. Dort weist collie start darauf hin und führt stattdessen eine unbeaufsichtigte Hintergrund-Bridge aus, ohne Neustart bei Fehlern und ohne Start bei der Anmeldung. collie restart wechselt dennoch in das neue Verzeichnis.

Hinweis. collie update lehnt hier ab und nennt keine Paketverwaltung, sondern meldet cannot tell how this Collie was installed. Ein mise-Verzeichnisbaum liegt in Ihrem Home-Verzeichnis, enthält kein eigenes .git und hat keine übergeordnete versions/-Struktur, sodass Collie ihn weder als Checkout noch als Paket interpretiert. mise verwaltet Aktualisierungen bei dieser Installation, und die beiden obigen Befehle führen sie durch.

Entfernen Sie es zuerst mit collie uninstall, dann:

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

uninstall löscht das Verzeichnis dieser Version, unuse entfernt die Zeile aus der Konfiguration. Geben Sie das Werkzeug für beides mit seinem vollständigen Namen github: an; die Kurzform collie funktioniert für upgrade, aber nicht für uninstall. Ihre eigenen Dateien bleiben erhalten: Zustand in ~/.local/state/collie (oder $COLLIE_STATE_DIR) und Konfiguration in ~/.config/collie.

Das PKGBUILD, der Nix-Ausdruck und deren Notizen befinden sich in packaging/ in diesem Repository. macOS hat noch kein Paket; die Flake-Ausgabe aarch64-darwin kommt dem am nächsten.

Multiplexer angeben

Collie spiegelt ein Backend: COLLIE_MUX=herdr (Standard), tmux oder zellij.

Hinweis. Sie müssen dies nicht vorher einrichten.

Beim ersten Aufruf sucht start nach einem aktiven Herdr-Socket, einem laufenden tmux-Server und zellij-Sitzungen, gibt die Funde aus und schreibt Ihre Antwort in die Konfigurationsdatei .env, wodurch diese erstellt wird. Ohne Terminal für Rückfragen wählt es das einzige gefundene Backend und gibt dieses an; wird keines oder werden mehrere gefunden, verweigert es den Start und verweist auf COLLIE_MUX.

Um die Wahl stattdessen vorab festzulegen, befüllen Sie diese Datei vor dem ersten Start. Der Pfad lautet ~/.config/collie/.env (eigenständig) oder entspricht der Ausgabe von herdr plugin config-dir herdr.collie:

mkdir -p ~/.config/collie
cp .env.example ~/.config/collie/.env

Legen Sie anschließend das Backend und dessen Endpunkt fest:

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

Achtung. Führen Sie dieses cp nicht nach einem Start aus: Es überschreibt die Datei COLLIE_MUX, die der Start gerade geschrieben hat, mit .env.example.

Bearbeiten Sie die Datei anschließend. Siehe Collie auf einen Multiplexer ausrichten.

Starten

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

start führt folgende Schritte aus:

1. 01
   web/dist erstellen, falls nicht vorhanden.
2. 02
   Die Bridge unter systemd --user (oder launchd/nohup) starten.
3. 03
   Führen Sie tailscale serve --bg 8787 aus (HTTPS :443 → 127.0.0.1:8787). In Ihrem Tailnet muss dafür HTTPS aktiviert sein (Admin-Konsole → "Enable HTTPS"); Collie weist darauf hin und bricht ab, falls dies nicht der Fall ist.
4. 04
   Das Verbindungsbanner ausgeben.

Erster Start: Was Sie sehen

Ausgabe von bin/collie start (Herdr-Ausführungen geben JSON zurück; Protokolle mit herdr plugin log list --plugin herdr.collie anzeigen):

$ bin/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

Wenn die Funktionsprüfung fehlschlägt (⚠ Collie isn't answering on :8787 yet), siehe Fehlerbehebung.

stop stoppt den Dienst; uninstall entfernt Dienst und Proxy. Die Bridge läuft als systemd --user-Dienst, unter macOS als launchd-Agent, der bei der Anmeldung startet und bei Fehlern neu startet (ARCHITECTURE.md §3); unter Linux sorgt loginctl enable-linger $USER dafür, dass er einen Neustart übersteht (Neustarts überstehen).

Konfigurieren Sie den Benutzerzugriff in Konfiguration und den Gerätezugriff über Koppeln (bin/collie pair).

Auf dem Smartphone öffnen

Öffnen Sie die tailnet-URL aus dem Banner (jederzeit mit bin/collie url abrufbar oder per QR-Code mit bin/collie qr erstellbar). Ihr Client muss sich im selben Tailnet befinden.

1. 01
   Gerät koppeln: Führen Sie bin/collie pair auf dem Host aus. Scannen Sie den ausgegebenen QR-Code, um Einstellungen → Gekoppelte Geräte auf dem Client mit bereits ausgefülltem Code zu öffnen, oder öffnen Sie Einstellungen → Gekoppelte Geräte auf dem Client und tippen Sie den Code ein (Ein Gerät koppeln).
2. 02
   PWA installieren: Tippen Sie in Safari (iOS) oder Chrome (Android) auf Zum Home-Bildschirm.

Die Installation der PWA erfordert HTTPS; COLLIE_SERVE_MODE=http deaktiviert Service-Worker, sodass das Telefon in diesem Modus nur den Browser-Tab nutzen kann.

Funktioniert es tatsächlich?

Status und Protokolle prüfen:

$ bin/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

$ bin/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 gets full write access. Set it to your tailnet login (see README → Variant A).

Um den Zugriff einzuschränken, setzen Sie COLLIE_TRUSTED_USER=you@example.com in .env und führen Sie bin/collie restart aus (Konfiguration). Bei fehlenden Dashboard-Inhalten siehe Fehlerbehebung.

Auf dem neuesten Stand halten

Ein einziger Befehl aktualisiert die aktuelle Hauptversion.

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

Aktualisierungen gelten für die aktuelle Hauptversion; ein Wechsel der Hauptversion erfordert collie update --major oder die Aktion update-major bei einer über Herdr verwalteten Installation. Informationen dazu sowie zu Rollbacks und zur Deinstallation finden Sie unter Verwaltung und Aktualisierung.