Installer Collie

Prérequis de l'hôte, les deux modes d'accès et première configuration. Lisez d'abord Sécurité : par conception, Collie expose un accès shell distant à votre machine.

Prérequis

Hôtes pris en charge : Linux et macOS. Windows est expérimental ; voir Windows.

Remarque. Aucune version minimale de tmux ou zellij n'est imposée. Les adaptateurs ont été testés avec tmux 3.4, tmux 3.6b et zellij 0.44.2. Un cas particulier de tmux est pris en charge : sur un serveur utilisant window-size manual, tmux plantait avant la version 3.7 lors de la création d'une fenêtre ; Collie bloque donc la requête et vous indique d'exécuter tmux set -g window-size latest.

Dépendances optionnelles, nécessaires uniquement pour les fonctionnalités associées :

Installer

Trois méthodes d'installation :

• —
  Nouvelle installation : le script d'installation, ou le même résultat depuis les sources.
• —
  Via Herdr : Collie s'installe en tant que plugin Herdr, piloté par les actions du plugin.
• —
  À partir d'un paquet : votre gestionnaire de paquets installe Collie et gère ses mises à jour.

Herdr est l'un des trois multiplexeurs que Collie peut répliquer, pas une dépendance du programme. Le choix du multiplexeur à répliquer constitue l'étape suivante.

Nouvelle installation

Le script d'installation télécharge la dernière version dans ~/.local/share/collie (COLLIE_DIR) et crée un lien vers le binaire dans ~/.local/bin/collie :

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

Il récupère la version stable la plus récente et refuse de modifier une installation existante ; c'est le rôle de collie update. La source de référence est scripts/install.sh dans le dépôt : une seule page de sh POSIX, sans jamais demander sudo.

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

Si ~/.local/bin n'est pas dans votre PATH, exécutez directement le binaire :

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

Pour figer une version ou réparer une installation existante (voir Si collie ne s'exécute pas) :

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

Pour les préversions, passez --beta : la préversion la plus récente est installée, puis l'installation suit les préversions de cette version majeure jusqu'à la sortie de la version finale (Préversions).

Le même résultat, depuis les sources

# 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

Lancez-le ensuite. start crée ~/.config/collie/ et enregistre votre choix de multiplexeur dans son .env ; il n'y a donc rien à initialiser manuellement au préalable :

bin/collie start

Via Herdr

Démarrez d'abord le serveur Herdr (herdr ou herdr server &).

Depuis GitHub :

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

Depuis les sources locales :

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

Gérez via Actions Herdr. Pour une préversion, installez le tag avec herdr plugin install AltanS/collie --ref <tag> --yes, ce qui suffit pour l'activer (Préversions).

À partir d'un paquet

Si Collie est packagé pour votre système, installez-le comme n'importe quel autre paquet. Le paquet contient le binaire compilé déjà publié par la version, rien n'est donc compilé sur votre machine : ni Bun, ni git, aucune compilation. L'intégralité du dossier de version est installée sous un préfixe unique, avec collie dans votre PATH sous la forme d'un lien symbolique pointant dessus.

Un paquet n'est pas un plugin Herdr, et chaque sous-commande collie de votre PATH fonctionne de la même manière dans les deux cas. Pour afficher les boutons de Collie dans Herdr, liez l'arborescence installée une fois :

herdr plugin link /opt/collie

Herdr n'analyse pas /opt, il ne trouve donc jamais le paquet tout seul. Les actions update et update-major du plugin refusent alors de s'exécuter et indiquent à la place votre gestionnaire de paquets. C'est le comportement attendu et non une erreur : la mise à jour de cette arborescence revient à votre gestionnaire de paquets.

Arch

collie-bin n'est pas encore sur AUR. AUR a suspendu l'enregistrement de nouveaux comptes, et le paquet sera publié depuis notre propre compte dès la réouverture des inscriptions. D'ici là, compilez-le à partir d'un clone de ce dépôt :

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

makepkg télécharge l'archive tar de la version pour votre architecture, vérifie son sha256 avec le manifeste d'intégrité de la version, puis l'extrait. Ni Bun, ni clone git d'autre chose, aucune compilation.

Une fois disponible sur AUR, un helper AUR installe le même PKGBUILD :

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

Les mises à jour ultérieures s'effectuent avec paru -S collie-bin ou yay -S collie-bin, la commande utilisée pour l'installation. sudo pacman -Syu collie-bin fonctionne uniquement lorsqu'un dépôt héberge le paquet, comme celui d'Omarchy.

Le paquet installe l'arborescence de la version dans /opt/collie et /usr/bin/collie sous forme de lien symbolique pointant vers celle-ci. README.md, CHANGELOG.md et docs/ sont placés dans /usr/share/doc/collie-bin/, et la licence dans /usr/share/licenses/collie-bin/. Il fournit collie et entre en conflit avec lui, ce qui empêche d'installer à la fois ce paquet et un futur paquet source. Il n'active aucune unité systemd : collie start écrit votre propre unité --user, comme après n'importe quelle installation.

Remarque. Exécutez collie restart après chaque mise à jour. pacman remplace les fichiers sans rien redémarrer, le service continue donc de tourner sur l'ancienne version avec un binaire supprimé jusqu'à ce que vous le redémarriez. collie doctor le signale comme restart-pending, et le téléphone affiche « Collie was replaced on disk. Restart it. » avec la commande à exécuter.

Supprimez-le en trois étapes :

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

collie uninstall arrête le service, supprime l'unité systemd --user et désactive le mappage tailscale serve propre à Collie ; pacman supprime ensuite /opt/collie et /usr/bin/collie et rien d'autre. Deux de vos répertoires subsistent, à supprimer manuellement si vous voulez les effacer : l'état sous ~/.local/state/collie/ (ou $COLLIE_STATE_DIR), et le répertoire de configuration contenant votre .env, soit ~/.config/herdr/plugins/config/herdr.collie/ sur un hôte avec Herdr.

Omarchy

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

Omarchy intègre à la fois tmux et Herdr, et Collie reflète un multiplexeur par installation. Le premier démarrage doit donc nommer celui à piloter : il refuse de choisir à l'aveugle entre deux options détectées. start écrit ce nom dans le fichier .env de Collie, qui vaut ~/.config/herdr/plugins/config/herdr.collie/.env sur un hôte avec Herdr, et les démarrages suivants se font avec collie start.

Cela fonctionne dès que collie-bin est disponible dans le propre dépôt de paquets d'Omarchy, mais la pull request qui l'ajoute n'est pas encore fusionnée. En attendant, compilez le même paquet depuis packaging/aur avec makepkg -si, comme décrit ci-dessus pour n'importe quel hôte Arch.

Les mises à jour s'effectuent ensuite avec sudo pacman -Syu, la commande que vous utilisez déjà pour mettre à jour la machine. Aucun helper AUR n'intervient, car pkgs.omarchy.org est un véritable dépôt pacman. La disposition de PKGBUILD et de /opt/collie reste identique dans les deux cas.

Remarque. Les mises à jour proviennent de votre gestionnaire de paquets, et Collie ne se mettra pas à jour lui-même ici. collie update refuse l'opération. Le bandeau de mise à jour sur le téléphone indique "Collie x.y.z available via pacman.", et la page Updates affiche la commande à copier au lieu d'un bouton de mise à jour, car le gestionnaire de paquets possède ce dossier. Collie indique la forme sudo pacman -Syu collie-bin, qui correspond à l'orthographe du dépôt ; sur une installation AUR, utilisez plutôt votre helper. Exécutez collie restart après la mise à niveau, pour la raison mentionnée ci-dessus : pacman ne redémarre rien.

Dans un crew, cette machine ne reçoit jamais de mise à jour depuis le téléphone : le crew indique "waits for the package manager", et elle ne se met à niveau que lorsque vous y exécutez votre helper.

Supprimez-le en suivant les trois mêmes étapes que pour Arch ci-dessus.

Nix

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

Le flake exporte packages.<system>.collie pour x86_64-linux, aarch64-linux et aarch64-darwin. Il récupère l'archive tarball de la version pour la plateforme concernée selon le sha256 présent dans son propre manifeste d'intégrité, patche l'interpréteur du binaire sur Linux, et installe l'arborescence de la version dans <store-path>/lib/collie avec bin/collie sous forme de lien symbolique pointant vers celle-ci. Exécutez-le une fois sans l'installer avec nix run github:AltanS/collie#collie -- doctor.

Il n'y a pas de compilation depuis les sources, et c'est volontaire : l'installation des dépendances nécessite le réseau alors qu'une dérivation Nix n'y a pas accès. Le paquet encapsule donc le binaire que la version publie et vérifie déjà par checksum.

Il n'existe pas encore de module NixOS, seulement le paquet flake. L'approche consiste donc à suivre nix profile : installez-le dans votre profil comme indiqué ci-dessus, ou ajoutez vous-même la sortie du flake à une liste home-manager ou environment.systemPackages.

Remarque. Les mises à jour proviennent de nix, et Collie ne se mettra pas à jour lui-même ici. collie update refuse l'opération et indique nix profile upgrade collie à la place ; le téléphone affiche la nouvelle version avec cette commande à l'emplacement prévu pour le bouton de mise à jour.

Dans un crew, cette machine ne reçoit jamais de mise à jour depuis le téléphone : le crew indique "waits for the package manager", et elle ne se met à niveau que lorsque vous y exécutez nix.

Supprimez-le d'abord avec collie stop, puis :

nix profile remove collie

Cela retire uniquement le chemin du store de votre profil, rien d'autre. Vos propres fichiers restent en place : l'état dans ~/.local/state/collie (ou $COLLIE_STATE_DIR), la configuration dans ~/.config/collie, et l'unité systemd --user à l'emplacement ~/.config/systemd/user/collie.service écrite par collie start. Exécutez collie uninstall avant de supprimer le paquet pour supprimer cette unité ainsi que le mappage de port.

mise

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

mise use -g écrit l'outil dans ~/.config/mise/config.toml et place le bin/ de la version dans votre PATH. Le backend github récupère l'archive tarball de la version pour la plateforme concernée ; cela fonctionne donc sur Linux et macOS sans Bun et sans compilation. L'arborescence complète s'installe sous ~/.local/share/mise/installs/github-altan-s-collie/<version>/, y compris web/dist et herdr-plugin.toml, et collie résout sa propre racine à partir de cet emplacement.

Installez une nouvelle version avec la même ligne mise use et un tag plus récent, ou laissez mise choisir la dernière version :

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

--bump est le flag important. Un 1.5.6 épinglé correspond à une plage d'une seule version ; une simple commande mise upgrade indique donc que l'outil est à jour et ne modifie rien.

Le redémarrage n'est pas facultatif. Chaque version dispose de son propre répertoire, et collie start intègre le répertoire depuis lequel il a été exécuté dans la définition du service. Le service continue donc de servir l'ancienne version depuis l'ancien répertoire jusqu'à ce que vous le redémarriez. collie restart réécrit cette définition avec le nouveau chemin : l'unité systemd --user sur Linux, le fichier plist ~/Library/LaunchAgents sur macOS. Une seule commande pour les deux.

Remarque. Un Mac administré uniquement par SSH ne dispose d'aucun domaine gui/<uid> dans lequel charger un agent. Dans ce cas, collie start le signale et exécute à la place un pont non supervisé en arrière-plan, sans redémarrage en cas d'échec et sans exécution à la connexion. collie restart le bascule tout de même vers le nouveau répertoire.

Remarque. collie update refuse l'opération ici et ne mentionne aucun gestionnaire de paquets : il affiche cannot tell how this Collie was installed. Une arborescence mise se trouve dans votre répertoire personnel, ne comporte aucun .git propre et ne présente aucune structure versions/ parente ; Collie ne la reconnaît donc ni comme un clone git ni comme un paquet. mise gère les mises à jour sur cette installation, et les deux commandes ci-dessus permettent d'effectuer la migration.

Supprimez-le d'abord avec collie uninstall, puis :

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

uninstall supprime le répertoire de cette version, unuse retire la ligne de la configuration. Utilisez le nom complet du dépôt github: pour ces deux commandes ; la version courte collie fonctionne pour upgrade, mais pas pour uninstall. Vos propres fichiers restent en place : l'état dans ~/.local/state/collie (ou $COLLIE_STATE_DIR), et la configuration dans ~/.config/collie.

Le PKGBUILD, l'expression Nix et leurs notes se trouvent dans packaging/ au sein de ce dépôt. macOS ne dispose pas encore de paquet ; la sortie de flake aarch64-darwin est ce qui s'en rapproche le plus.

Nommez votre multiplexeur

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

Collie reproduit un backend : COLLIE_MUX=herdr (par défaut), tmux ou zellij. Préremplir le fichier ci-dessus avant le premier démarrage vous permet de choisir dès le départ ; il s'agit de ~/.config/collie/.env en autonome, ou du chemin affiché par herdr plugin config-dir herdr.collie. Définissez ensuite le backend et son point d'accès :

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

Remarque. Vous n'avez pas besoin de le configurer au préalable. Le premier start recherche un socket Herdr actif, un serveur tmux en cours d'exécution et des sessions zellij, affiche ce qu'il a trouvé et écrit votre réponse dans la configuration .env, en la créant. Sans terminal pour poser la question, il sélectionne l'unique backend trouvé et indique lequel ; s'il n'en trouve aucun, ou s'il en trouve plusieurs, il refuse de démarrer et indique COLLIE_MUX.

Attention. N'exécutez pas ce cp après un démarrage : il écrase .env.example sur le COLLIE_MUX que le démarrage vient d'écrire.

Modifiez ensuite le fichier. Consultez Pointer Collie vers un multiplexeur.

Démarrez-le

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

start va :

1. 01
   Compiler web/dist s'il est manquant.
2. 02
   Lancer le bridge sous systemd --user (ou launchd/nohup).
3. 03
   Exécuter tailscale serve --bg 8787 (HTTPS :443 → 127.0.0.1:8787). Votre tailnet doit avoir HTTPS activé pour cela (console d'administration → "Enable HTTPS") ; Collie le signale et s'arrête si ce n'est pas le cas.
4. 04
   Afficher la bannière de connexion.

Premier lancement : ce que vous verrez

Sortie de bin/collie start (les exécutions de Herdr renvoient du JSON ; consultez les journaux avec herdr plugin log list --plugin herdr.collie) :

$ 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

Si le health check échoue (⚠ Collie isn't answering on :8787 yet), consultez Dépannage.

stop arrête le service ; uninstall supprime le service et le proxy. Le bridge s'exécute en tant que service systemd --user, un agent launchd sur macOS, qui démarre à la connexion et redémarre en cas d'échec (ARCHITECTURE.md §3) ; sur Linux, loginctl enable-linger $USER lui permet de persister après un redémarrage (Persistance aux redémarrages).

Configurez l'accès utilisateur dans Configurer et l'accès appareil via association (bin/collie pair).

Ouvrez-le sur votre téléphone

Ouvrez l'URL tailnet depuis la bannière (récupérez-la à tout moment avec bin/collie url ou générez un code QR avec bin/collie qr). Votre client doit être sur le même tailnet.

1. 01
   Associer l'appareil : exécutez bin/collie pair sur l'hôte. Scannez le code QR affiché pour ouvrir Réglages → Appareils associés sur le client avec le code prérempli, ou ouvrez Réglages → Appareils associés sur le client et saisissez le code (Associer un appareil).
2. 02
   Installer l'application : appuyez sur Installer dans Réglages si le navigateur le propose, ou utilisez la feuille de partage sur iOS/iPadOS.

Remarque. Sur Android ou ordinateur : Chrome et Edge proposent un bouton d'installation dès qu'ils déterminent que l'application peut être installée, et Collie affiche cette proposition sous la forme d'une carte Installer en haut de Réglages.

Remarque. Sur iPhone ou iPad : Safari ne fait jamais cette proposition : l'installation s'y fait toujours via la feuille de partage ; la même carte affiche donc ces étapes à la place, précisément lorsqu'elles s'appliquent.

L'installation de la PWA nécessite HTTPS ; COLLIE_SERVE_MODE=http désactive les service workers, donc le téléphone ne peut utiliser que l'onglet du navigateur dans ce mode. Une version de dev (tout checkout ne correspondant pas à son tag de release) s'installe sous le nom Collie (dev) avec une icône orange, afin de ne jamais ressembler à une installation de release sur votre écran d'accueil.

Est-ce que cela fonctionne vraiment ?

Vérifiez l'état et les journaux :

$ 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).

Pour restreindre l'accès, définissez COLLIE_TRUSTED_USER=you@example.com dans .env et exécutez bin/collie restart (Configurer). Pour le contenu manquant du tableau de bord, consultez Dépannage.

Maintenez-le à jour

Une seule commande met à jour la version majeure actuelle.

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

Les mises à jour s'appliquent à la version majeure actuelle ; changer de version majeure nécessite collie update --major, ou l'action update-major sur une installation gérée par Herdr. Pour cela, les retours en arrière et la désinstallation, consultez Gérer et mettre à jour.