Configurer

Par défaut, Collie s'exécute en mode mono-utilisateur ouvert : toute personne présente sur votre tailnet pouvant accéder à l'URL dispose d'un contrôle total. Cela déclenche l'avertissement TRUSTED_USER. Restreignez l'accès :

# in your .env
COLLIE_TRUSTED_USER=you@example.com           # your tailnet login — Collie rejects anyone else
COLLIE_PUBLIC_HOSTS=myhost.tail1234.ts.net    # only behind your OWN proxy; on a tailnet `collie
                                              # start` discovers this for you

Collie charge la configuration depuis un fichier .env situé dans ~/.config/collie. Si Herdr gère l'installation, le CLI interroge Herdr pour obtenir le répertoire de configuration du plugin (généralement ~/.config/herdr/plugins/config/herdr.collie). Les deux chemins se résolvent de manière cohérente dans les commandes du CLI, le service lit donc le fichier initialisé ici :

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

# on a Herdr-managed install, seed Herdr's plugin config dir instead:
cp .env.example "$(herdr plugin config-dir herdr.collie)/.env"

Les chemins ci-dessous utilisent ~/.config/collie/…. Sur une installation gérée par Herdr, remplacez ce préfixe par $(herdr plugin config-dir herdr.collie).

Collie lit .env uniquement au démarrage. Exécutez collie restart après l'avoir modifié.

Le fichier .env.example répertorie toutes les options.

Il inclut COLLIE_PORT, COLLIE_SERVE_MODE=http (pour Headscale ou les domaines .internal) et COLLIE_SERVE_PORT (pour exposer HTTPS sur un autre port que :443 ; voir docs/deployment.md → Plusieurs instances de Collie sur un même hôte). Le CLI lit les paramètres de serve pour configurer tailscale serve, au lieu de les transmettre au bridge.

Pour lire l'historique de plusieurs répertoires personnels d'agents, fournissez une liste séparée par des virgules dans COLLIE_TRANSCRIPT_ROOT.

docs/deployment.md couvre les domaines personnalisés et les proxys inverses. Collie applique une politique de même origine (same-origin policy) ; tout nom d'hôte personnalisé ou terminateur TLS externe doit donc figurer explicitement dans la liste d'autorisation :

COLLIE_ALLOWED_ORIGINS=https://collie.example.com

Sans ce paramètre, l'interface utilisateur se chargera sous la forme d'une page blanche. Consultez Dépannage pour plus de détails.

Vos propres commandes slash

Placez les commandes spécifiques à la machine, comme un /fork-in-herdr de plugin Herdr ou un /deploy personnalisé, dans commands.toml. C'est l'un des quatre fichiers de configuration qui partagent le même lecteur et modèle de chargement :

Toute ligne comportant l'indicateur activé requiert une confirmation en deux étapes avant son exécution. Les modifications apportées à l'un de ces fichiers prennent effet sans redémarrer le service. Si Collie rejette une ligne, journalctl --user -u collie -n 20 affiche le numéro de la ligne et l'erreur.

cp commands.toml.example ~/.config/collie/commands.toml

[[commands]]
scope = "omp"                # optional; omit for every pane
command = "/fork-in-herdr"
description = "Fork this conversation into a new herdr tab"

Un volet correspondant à vos lignes configurées affiche uniquement ces lignes. La ligne la plus spécifique l'emporte, comme documenté dans ADR 0018.

Pour vérifier, ouvrez un volet et appuyez sur / ; vos lignes apparaissent sur le premier écran.

Vos propres préréglages de touches

Vous pouvez remplacer la ligne Préréglages du tiroir Keys dans keys.toml, situé à côté de commands.toml :

cp keys.toml.example ~/.config/collie/keys.toml

[[keys]]
scope = "claude"             # optional; omit for every pane
label = "Yes"
keys = ["Down", "Enter"]     # several chords go out as one batch

Lorsqu'un volet correspond à vos lignes définies, il affiche uniquement vos préréglages à la place des boutons par défaut Ctrl C/D/U/R/L/Z (ADR 0018). Le reste de la barre (Échap, touches fléchées, Entrée/Tab/Espace, modificateurs, chiffres, F1–F12) est fixe.

Les accords utilisent la syntaxe de herdr, pas celle de tmux :

Pour vérifier, ouvrez un volet et appuyez sur Touches → Préréglages pour afficher les nouveaux boutons. Si Collie rejette une ligne, consultez journalctl --user -u collie -n 20 pour le détail de l'erreur.

Vos propres réponses rapides

Vous pouvez personnaliser les phrases du dock Rapide dans quick-replies.toml :

cp quick-replies.toml.example ~/.config/collie/quick-replies.toml

[[replies]]
scope = "claude"             # optional; omit for every pane
title = "confirm"
items = ["yes", "no"]        # sent verbatim, one per button

Lorsqu'un volet correspond à vos règles, vos groupes remplacent ceux par défaut (ADR 0018). Les phrases par défaut sont en anglais (yes, commit and push).

Utilisez ce fichier pour travailler dans d'autres langues, ou pour envoyer des mots comme approve à des environnements de test spécifiques. Définir scope = "shell" cible les volets shell standards, qui ne reçoivent sinon que y/n.

Pour vérifier, ouvrez un volet et appuyez sur Rapide pour voir vos groupes. Si le chargement d'une ligne échoue, journalctl --user -u collie -n 20 affiche l'erreur.

Vos propres lanceurs

Un appui exécute une commande que vous avez déclarée, dans launchers.toml à côté de keys.toml :

cp launchers.toml.example ~/.config/collie/launchers.toml

[[launchers]]
command = "htop"             # required; the shell line, typed verbatim into the fresh shell
label = "Top"                # optional; defaults to the first word of command
# cwd = "~/dev/collie"       # optional; absent means "here" — see below

L'endroit où s'ouvre l'appui dépend de l'endroit où vous appuyez, pas de la ligne. Depuis le tableau de bord, un appui crée un nouvel Espace nommé d'après la ligne. Depuis un volet (le volet de sélection accessible en glissant vers le haut), un appui ouvre un nouvel onglet dans le propre Espace de ce volet, à côté.

Dans les deux cas, le pont saisit command dans le nouveau shell et envoie Entrée. La commande gère sa propre durée de vie : une commande qui se ferme d'elle-même emporte le Space ou l'onglet avec elle, et htop reste actif jusqu'à ce que vous le quittiez.

cwd correspond à l'endroit où ce nouveau Space ou onglet s'ouvre. Épinglez-en un (comme le fait htop ci-dessus) et il aura la priorité, peu importe où vous appuyez sur la ligne.

Si vous l'omettez, cela signifie « ici » : le tableau de bord l'ouvre dans votre dossier personnel, un volet l'ouvre dans celui de ce volet cwd. Une ligne sans cwd vous suit d'un checkout à l'autre au lieu de toujours s'ouvrir à la racine de l'un d'eux.

Ce fichier sert de liste d'autorisation. POST /api/launch n'accepte qu'un command correspondant exactement à une ligne présente ici ; un téléphone ne peut donc rien lancer qui ne figure pas dans le fichier. Les modifications s'appliquent immédiatement sans redémarrage, mais un onglet déjà ouvert ne relit les lignes qu'à son rechargement suivant.

Vos lignes s'affichent à deux endroits : une section Lancer sur le tableau de bord, qui se replie comme Spaces et Recent, et une section Lancer dans le volet du sélecteur (glissez vers le haut depuis un volet). Une ligne épinglée affiche son dossier, raccourci sous home ; une ligne sans cwd indique « ici » dans le sélecteur (le tableau de bord sous-entendant déjà home, il n'affiche rien à cet endroit). Si vous ne déclarez aucune ligne, aucune de ces sections n'apparaît.

Dans une crew (plusieurs machines, un lead relié au téléphone), chaque machine lit sa propre copie de ce fichier : une ligne se lance sur la machine dont vous avez touché le tableau de bord ou le volet, pas sur le lead.

Pour vérifier, rechargez le tableau de bord et regardez sous le herd. Si le chargement d'une ligne échoue, journalctl --user -u collie -n 20 affiche l'erreur.

Vos propres polices

La police de l'interface est un paramètre propre à chaque appareil. Sous Settings → Typeface, vous pouvez choisir entre System, Space Grotesk (par défaut) et Aldrich. Vous pouvez ajouter des polices personnalisées dans theme.toml, le quatrième fichier de configuration :

cp theme.toml.example ~/.config/collie/theme.toml
mkdir -p ~/.config/collie/fonts
cp departure.woff2 ~/.config/collie/fonts/

[[font]]
family = "Departure Mono"    # the picker's label AND the CSS family
file   = "departure.woff2"   # a bare name inside fonts/, woff2 only
weight = "400 700"           # optional

Les polices personnalisées s'ajoutent à la liste intégrée plutôt que de la remplacer (ADR 0033), contrairement au comportement de commands.toml et des autres fichiers de configuration. Comme les polices ne déclenchent pas d'actions, il n'y a rien à masquer.

Elles apparaissent sous les trois entrées par défaut, et chaque appareil client sélectionne la sienne.

Trois comportements à noter :

• —
  Décalage de mise en page au premier chargement. Les polices personnalisées ne disposent pas de polices de secours ajustées aux métriques, ce qui provoque un léger décalage de mise en page au chargement initial. Les polices intégrées évitent cela, car leurs polices de secours sont générées au moment du build.
• —
  Délai de chargement à froid. Un chargement à froid récupère le fichier avec un court délai ; un client en cache effectue le rendu immédiatement.
• —
  Interface uniquement. La police sélectionnée s'applique uniquement à l'interface de Collie. Le miroir du terminal, la transcription et le markdown rendu conservent leur propre typographie.
• —
  Actif au prochain rechargement. Les modifications ne nécessitent pas de redémarrage et prennent effet au rechargement suivant de la page. Les configurations non valides consignent des erreurs consultables via journalctl --user -u collie -n 20.

Pièces jointes

Le trombone à côté de la zone de message téléverse un fichier sur l'hôte et insère son chemin dans votre message.

# in your .env
COLLIE_MAX_UPLOAD_MB=25              # default 10, floor 1, ceiling 512
COLLIE_UPLOAD_EXTRA_TYPES=rb,ex,zig  # bare extensions, no dot

Collie enregistre le fichier sous <state-dir>/uploads avec des permissions réservées au propriétaire et ajoute son chemin absolu à votre brouillon. L'agent le lit depuis ce chemin, car un terminal ne peut pas recevoir de fichier collé. Les fichiers téléversés sont supprimés 48 heures après leur écriture.

Deux types de fichiers sont acceptés et ils sont vérifiés différemment.

Les images sont identifiées par leurs octets de signature, jamais par leur nom ni leur type déclaré : png, jpg, gif et webp. Le format SVG est refusé délibérément, car il s'agit d'un balisage pouvant exécuter des scripts plutôt que d'une image.

Le texte est identifié par son extension, avec les octets en guise de veto : un fichier dont les 4 premiers Ko contiennent un octet NUL ou de contrôle parasite est refusé quel que soit son nom. La liste fournie comprend md, markdown, txt, json, jsonl, yaml, yml, toml, csv, tsv, log, xml, html, htm, css, js, jsx, mjs, cjs, ts, tsx, py, go, rs, sh, bash, sql, diff et patch.

Remarque. COLLIE_UPLOAD_EXTRA_TYPES ajoute uniquement des types de texte. Une image nécessite une signature pour être vérifiée ; aucun format binaire ne peut donc être ajouté de cette manière.

Augmenter COLLIE_MAX_UPLOAD_MB augmente deux autres limites. Le bridge lit l'intégralité d'un téléversement en mémoire avant de pouvoir le mesurer : un plafond élevé combiné à plusieurs téléversements simultanés consomme autant de mémoire. De plus, la limite de corps de requête du runtime s'applique à chaque route, pas seulement à celle du téléversement ; un plafond élevé permet donc à un corps volumineux d'atteindre n'importe quel gestionnaire, qui le refusera ensuite selon sa propre limite. Rien n'est supprimé avant l'expiration des 48 heures : le répertoire des téléversements contient au maximum ce qui a été envoyé en deux jours. N'augmentez ce nombre que par nécessité, pas par défaut.

Dans un crew, les deux paramètres sont propres à chaque machine, et la machine qui stocke le fichier est celle qui les applique. Le lead refuse un corps trop volumineux avant de le relayer pour préserver votre liaison montante, mais il le refuse selon son propre seuil. Définissez les mêmes valeurs sur chaque membre, sinon un pair refusera ce que son lead a laissé passer.

Multi-session

Par défaut, une instance de Collie sert toutes les sessions Herdr qu'elle trouve.

COLLIE_MULTI_SESSION=on (valeur par défaut) découvre et sert chaque session Herdr nommée sous votre racine de configuration, accessible depuis l'en-tête. Définir COLLIE_MULTI_SESSION=off ne sert que la session principale. Chaque session découverte est accessible via la même URL, y compris les sessions privées ou bac à sable. Sécurité signale ce comportement comme un point de vigilance.

Mode sombre / mode clair

Remarque. Collie s'aligne par défaut sur l'apparence de votre téléphone.

Pour la figer, ouvrez Paramètres → Apparence et choisissez Système, Clair ou Sombre. Le paramètre est stocké par appareil dans le navigateur plutôt que sur le bridge. Votre téléphone peut rester en mode sombre pendant qu'un ordinateur portable suit le système d'exploitation. La préférence persiste après les rechargements et les réinstallations de la PWA sur le même appareil.

Le miroir du terminal est délibérément différent

Le miroir s'affiche toujours sur un fond sombre. Le mode clair inverse l'élément entier au lieu de recolorer les balises individuelles.

Les agents émettent des codes de couleur 24 bits absolus (38;2;r;g;b) conçus pour des fonds sombres, que les analyseurs en aval ne peuvent pas réassigner de manière fiable. Rendu directement sur du blanc, la plupart des sorties d'agents tombent sous un rapport de contraste de 3:1. L'inversion préserve le contraste prévu. Les mesures sont documentées dans l'ADR 0002.

Cette implémentation a deux conséquences pratiques :

• —
  Laissez vos agents configurés avec des thèmes sombres. Il s'agit de la configuration par défaut pour Claude Code, codex, opencode et pi. Si un agent utilise un thème clair, il émet des valeurs sombre sur clair qui deviennent illisibles dans Collie sous les deux modes. Cela provient de la sortie de l'agent et non de Collie lui-même.
• —
  Les diffs et les lignes surlignées s'affichent sous forme de blocs sombres en mode clair. Le contraste reste intact, mais le poids visuel est inversé.

Remarque. Installé sur iOS, en mode clair, le texte de la barre d'état reste blanc et peut se fondre dans l'arrière-plan. iOS ne permet pas aux applications web de modifier cette valeur de manière dynamique. Exécutez Collie directement dans le navigateur plutôt que sous forme de PWA installée pour contourner cette limitation.

Mode Zen

Remarque. Le mode Zen est désactivé par défaut.

Activez-le dans Paramètres → Mode Zen (enregistré par appareil dans le navigateur). Cela ajoute une option Mode Zen au menu du panneau, sous le ⋮ à côté de Rechercher et Historique. Cliquez dessus pour masquer tous les éléments d'interface de Collie : l'en-tête, les bandeaux d'onglets et de panneaux, la ligne d'état de l'agent et les docks du compositeur. Seul le miroir du terminal reste visible. Un bouton flottant dans le coin supérieur droit ou la touche Échap restaure l'interface.

Le mode Zen est temporaire. La configuration persiste, mais l'état actif est réinitialisé lorsque vous changez de panneau ou rechargez la page. Les panneaux s'ouvrent toujours avec l'habillage standard.

Le miroir du terminal continue les requêtes périodiques en mode Zen, et les éléments interactifs du tampon restent fonctionnels. Les boutons de prompt ainsi que les commandes "Charger les éléments plus anciens" et "Afficher tout l'historique" restent disponibles car ils font partie du flux de contenu plutôt que de l'habillage.

Langue

L'interface de Collie est disponible en six langues. Configurez ce paramètre sous Paramètres → Langue.

• —
  English
• —
  Deutsch
• —
  Español
• —
  한국어
• —
  日本語
• —
  中文

La sélection est enregistrée localement dans le navigateur par appareil. Le miroir du terminal n'est pas traduit : il affiche la sortie brute de l'agent, tandis que les réponses rapides, les libellés de menus et les touches correspondent aux noms de l'écran ou du clavier sous-jacents.