Konfiguration

Standardmäßig läuft Collie im offenen Einzelbenutzermodus: Jeder in Ihrem Tailnet, der die URL erreichen kann, hat die volle Kontrolle. Dies löst die Warnung TRUSTED_USER aus. Zugriff einschränken:

# 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 lädt die Konfiguration aus einer Datei .env in ~/.config/collie. Wenn Herdr die Installation verwaltet, fragt das CLI Herdr nach dem Plugin-Konfigurationsverzeichnis (typischerweise ~/.config/herdr/plugins/config/herdr.collie). Beide Pfade lösen über alle CLI-Befehle hinweg einheitlich auf, sodass der Dienst die hier angelegte Datei liest:

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"

Die folgenden Pfade verwenden ~/.config/collie/…. Ersetzen Sie dieses Präfix bei einer von Herdr verwalteten Installation durch $(herdr plugin config-dir herdr.collie).

Collie liest .env nur beim Start. Führen Sie collie restart nach Änderungen daran aus.

Die Datei .env.example listet alle Optionen auf.

Sie enthält COLLIE_PORT, COLLIE_SERVE_MODE=http (für Headscale- oder .internal-Domains) und COLLIE_SERVE_PORT (um HTTPS auf einem anderen Port als :443 bereitzustellen; siehe docs/deployment.md → Mehrere Collies auf einem Host). Die CLI liest die Serve-Parameter, um tailscale serve zu konfigurieren, anstatt sie an die Bridge zu übergeben.

Um den Verlauf aus mehreren Agent-Heimatverzeichnissen zu lesen, geben Sie eine kommagetrennte Liste in COLLIE_TRANSCRIPT_ROOT an.

docs/deployment.md deckt eigene Domains und Reverse-Proxys ab. Collie erzwingt eine Same-Origin-Policy, daher muss jeder eigene Hostname oder externe TLS-Terminator explizit auf die Zulassungsliste gesetzt werden:

COLLIE_ALLOWED_ORIGINS=https://collie.example.com

Ohne diese Einstellung lädt die Benutzeroberfläche als leere Seite. Details finden Sie unter Fehlerbehebung.

Eigene Slash-Befehle

Legen Sie maschinenspezifische Befehle, wie ein Herdr-Plugin /fork-in-herdr oder ein benutzerdefiniertes /deploy, in commands.toml ab. Dies ist eine von vier Konfigurationsdateien, die denselben Reader und dasselbe Lademuster nutzen:

Jede Zeile mit gesetztem Flag erfordert eine Bestätigung durch zweifaches Antippen, bevor sie ausgeführt wird. Änderungen an diesen Dateien werden ohne Neustart des Dienstes wirksam. Wenn Collie eine Zeile ablehnt, gibt journalctl --user -u collie -n 20 die Zeilennummer und den Fehler aus.

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"

Ein Bereich, der Ihren konfigurierten Zeilen entspricht, zeigt nur diese Zeilen an. Die spezifischste Zeile hat Vorrang, wie in ADR 0018 dokumentiert.

Öffnen Sie zum Überprüfen einen Bereich und tippen Sie auf /; Ihre Zeilen erscheinen auf dem ersten Bildschirm.

Eigene Tasten-Voreinstellungen

Sie können die Zeile Presets der Tastenleiste in keys.toml ersetzen, die sich neben commands.toml befindet:

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

Wenn ein Bereich Ihren definierten Zeilen entspricht, zeigt er nur Ihre Voreinstellungen anstelle der standardmäßigen Strg-C/D/U/R/L/Z-Schaltflächen an (ADR 0018). Der Rest der Leiste (Esc, Pfeiltasten, Eingabe/Tab/Leertaste, Modifikatortasten, Ziffern, F1–F12) ist fest vorgegeben.

Tastenkombinationen verwenden die Syntax von herdr, nicht die von tmux:

Öffnen Sie zur Überprüfung ein Pane und tippen Sie auf Tasten → Presets, um die neuen Schaltflächen anzuzeigen. Wenn Collie eine Zeile ablehnt, prüfen Sie journalctl --user -u collie -n 20 auf Fehlerdetails.

Eigene Schnellantworten

Sie können die Formulierungen des Schnell-Docks in quick-replies.toml anpassen:

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

Wenn ein Pane Ihren Regeln entspricht, ersetzen Ihre Gruppen die Standardgruppen (ADR 0018). Die Standardphrasen sind auf Englisch (yes, commit and push).

Verwenden Sie diese Datei für andere Sprachen oder um Wörter wie approve an bestimmte Harnesses zu senden. Das Setzen von scope = "shell" zielt auf Standard-Shell-Panes ab, die sonst nur y/n empfangen.

Öffnen Sie zur Überprüfung ein Pane und tippen Sie auf Schnell, um Ihre Gruppen zu sehen. Wenn eine Zeile nicht geladen werden kann, gibt journalctl --user -u collie -n 20 den Fehler aus.

Eigene Starter

Ein Tippen führt einen definierten Befehl in launchers.toml neben keys.toml aus:

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

Wo das Antippen geöffnet wird, hängt vom Ort des Antippens ab, nicht von der Zeile. Im Dashboard erstellt ein Antippen einen neuen Space, der nach der Zeile benannt ist. In einem Pane (dem Umschalt-Sheet, das Sie durch Wischen nach oben erreichen) öffnet ein Antippen einen neuen Tab im eigenen Space dieses Bereichs daneben.

In beiden Fällen tippt die Bridge den command in die neue Shell ein und sendet Enter. Der Befehl bestimmt seine eigene Lebensdauer: Ein Befehl, der sich selbst beendet, schließt den Space oder Tab mit, und htop bleibt geöffnet, bis Sie es beenden.

cwd gibt an, wo dieser neue Space oder Tab geöffnet wird. Pinnen Sie einen Pfad an (wie htop oben), gilt dieser unabhängig davon, wo Sie die Zeile antippen.

Lassen Sie ihn weg, bedeutet dies „hier“: Das Dashboard öffnet ihn in Ihrem Home-Verzeichnis, ein Pane im cwd von diesem Bereich. Eine Zeile ohne cwd folgt Ihnen durch Ihre Checkouts, statt immer im Hauptverzeichnis eines bestimmten Checkouts zu landen.

Diese Datei ist die Positivliste. POST /api/launch akzeptiert nur ein command, das exakt mit einer Zeile hier übereinstimmt, sodass ein Smartphone nichts starten kann, was nicht in der Datei steht. Änderungen werden sofort ohne Neustart wirksam, aber ein bereits geöffneter Tab liest die Zeilen erst beim nächsten Laden neu ein.

Ihre Zeilen erscheinen an zwei Stellen: in einem Starten-Bereich auf dem Dashboard, der sich wie „Spaces“ und „Recent“ einklappen lässt, und in einem Starten-Bereich im Umschalt-Sheet (vom Pane nach oben wischen). Eine angepinnte Zeile zeigt ihren Ordner gekürzt unter Home an; eine Zeile ohne cwd zeigt im Umschalter „hier“ an (das Dashboard impliziert bereits Home und zeigt dort nichts an). Wenn Sie keine Zeilen deklarieren, wird keiner der beiden Bereiche angezeigt.

In einem pack (mehrere Rechner, ein Lead für das Smartphone) liest jeder Rechner seine eigene Kopie dieser Datei. Eine Zeile startet auf dem Dashboard oder Pane des Rechners, auf dem Sie sie angetippt haben, nicht auf dem Lead.

Laden Sie zur Überprüfung das Dashboard neu und sehen Sie unter der Herd nach. Wenn eine Zeile nicht geladen werden kann, gibt journalctl --user -u collie -n 20 den Fehler aus.

Eigene Schriftarten

Die Schriftart der Oberfläche ist eine gerätespezifische Einstellung. Unter Einstellungen → Schriftart können Sie zwischen System, Space Grotesk (Standard) und Aldrich wählen. Sie können eigene Schriftarten in theme.toml hinzufügen, der vierten Konfigurationsdatei:

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

Benutzerdefinierte Schriftarten werden an die integrierte Liste angehängt, statt sie zu ersetzen (ADR 0033), anders als in commands.toml und den übrigen Konfigurationsdateien. Da Schriftarten keine Aktionen auslösen, wird nichts überschattet.

Sie erscheinen unterhalb der drei Standardeinträge, und jedes Client-Gerät wählt seine eigene Schriftart.

Drei Verhaltensweisen sind zu beachten:

• —
  Layout-Verschiebung beim ersten Laden. Benutzerdefinierten Schriftarten fehlen metrisch angepasste Fallbacks, was beim ersten Laden zu einer leichten Layout-Verschiebung führt. Integrierte Schriftarten vermeiden dies, da ihre Fallbacks zur Build-Zeit generiert werden.
• —
  Verzögerung beim Kaltstart. Ein Kaltstart ruft die Datei mit einer kurzen Verzögerung ab; ein Client mit Cache rendert sofort.
• —
  Nur Chrome. Die gewählte Schriftart gilt nur für das Chrome von Collie. Das Terminal-Mirror, das Transkript und gerendertes Markdown behalten ihre eigene Typografie.
• —
  Live beim nächsten Neuladen. Änderungen erfordern keinen Neustart und werden beim nächsten Neuladen der Seite wirksam. Ungültige Konfigurationen protokollieren Fehler, die über journalctl --user -u collie -n 20 sichtbar sind.

Anhänge

Die Büroklammer neben dem Eingabefeld lädt eine Datei auf den Host hoch und fügt deren Pfad in Ihre Nachricht ein.

# 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 speichert die Datei unter <state-dir>/uploads mit Rechten ausschließlich für den Eigentümer und hängt ihren absoluten Pfad an Ihren Entwurf an. Der Agent liest sie von diesem Pfad, da ein Terminal keine eingefügte Datei entgegennehmen kann. Uploads werden 48 Stunden nach dem Schreiben gelöscht.

Zwei Arten von Dateien werden akzeptiert und unterschiedlich geprüft.

Bilder werden anhand ihrer Signatur-Bytes identifiziert, niemals anhand ihres Namens oder ihres deklarierten Typs: png, jpg, gif und webp. SVG wird bewusst abgelehnt, da es sich um skriptfähiges Markup und nicht um ein Bild handelt.

Text wird anhand der Dateiendung identifiziert, wobei die Bytes als Veto dienen: Eine Datei, deren erste 4 KB ein NUL-Byte oder ein sonstiges Steuerzeichen enthalten, wird unabhängig von ihrem Namen abgelehnt. Die mitgelieferte Liste umfasst 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 und patch.

Hinweis. COLLIE_UPLOAD_EXTRA_TYPES fügt ausschließlich Texttypen hinzu. Ein Bild erfordert eine Signatur zur Überprüfung, daher kann auf diesem Weg kein Binärformat hinzugefügt werden.

Das Erhöhen von COLLIE_MAX_UPLOAD_MB erhöht zwei weitere Werte. Die Bridge liest einen vollständigen Upload in den Arbeitsspeicher, bevor sie ihn messen kann; ein hohes Limit plus mehrere gleichzeitige Uploads verbraucht entsprechend viel Arbeitsspeicher. Zudem gilt das Body-Limit der Laufzeitumgebung für jede Route, nicht nur für Uploads; ein hohes Limit lässt also große Payloads jeden Handler erreichen, wo das eigene Limit des Handlers diese dann abweist. Nichts wird vor Ablauf der 48 Stunden gelöscht, daher enthält das Upload-Verzeichnis maximal die Daten von zwei Tagen. Erhöhen Sie den Wert nur bei tatsächlichem Bedarf, nicht standardmäßig.

In einem pack gelten beide Einstellungen pro Rechner, und der Rechner, der die Datei speichert, setzt sie durch. Der Lead weist einen zu großen Body vor der Weiterleitung ab, um Ihren Uplink zu schonen, tut dies jedoch anhand seines eigenen Werts. Setzen Sie auf jedem Mitglied dieselben Werte, andernfalls weist ein Peer Daten ab, die sein Lead durchgelassen hat.

Mehrere Sitzungen

Standardmäßig bedient eine Collie-Instanz jede gefundene Herdr-Sitzung.

COLLIE_MULTI_SESSION=on (Standard) erkennt und bedient jede benannte Herdr-Sitzung unter Ihrem Konfigurationsstammverzeichnis, umschaltbar über die Kopfzeile. Das Setzen von COLLIE_MULTI_SESSION=off bedient nur die primäre Sitzung. Jede erkannte Sitzung ist über dieselbe URL zugänglich, einschließlich privater oder Sandbox-Sitzungen. Sicherheit führt dieses Verhalten als Problemstelle auf.

Dunkelmodus / Hellmodus

Hinweis. Collie folgt standardmäßig dem Erscheinungsbild Ihres Smartphones.

Um es festzulegen, öffnen Sie Einstellungen → Erscheinungsbild und wählen Sie System, Hell oder Dunkel. Die Einstellung wird pro Gerät im Browser statt auf der Bridge gespeichert. Ihr Smartphone kann auf „Dark“ bleiben, während ein Laptop dem Betriebssystem folgt. Die Einstellung bleibt über Neuladungen und PWA-Neuinstallationen auf demselben Gerät hinweg erhalten.

Das Terminal-Spiegelbild weicht bewusst ab

Das Mirror rendert immer auf einem dunklen Hintergrund. Der helle Modus invertiert das gesamte Element, anstatt einzelne Spans neu einzufärben.

Agenten geben absolute 24-Bit-Farbcodes (38;2;r;g;b) aus, die für dunkle Hintergründe optimiert sind und von nachgelagerten Parsern nicht zuverlässig neu zugeordnet werden können. Direkt auf Weiß gerendert, fällt die meiste Agentenausgabe unter ein Kontrastverhältnis von 3:1. Die Invertierung bewahrt den beabsichtigten Kontrast. Die Messwerte sind in ADR 0002 dokumentiert.

Diese Implementierung hat zwei praktische Konsequenzen:

• —
  Lassen Sie Ihre Agenten für dunkle Themes konfiguriert. Dies ist die Standardeinstellung für Claude Code, codex, opencode und pi. Wenn ein Agent ein helles Theme verwendet, gibt er Dunkel-auf-Hell-Werte aus, die in Collie in beiden Modi unleserlich werden. Dies liegt an der Agentenausgabe und nicht an Collie selbst.
• —
  Diffs und hervorgehobene Zeilen werden als dunkle Blöcke gerendert im Hellmodus. Der Kontrast bleibt erhalten, aber die visuelle Gewichtung ist umgekehrt.

Hinweis. Unter iOS im Light Mode bleibt der Text der Statusleiste weiß und kann mit dem Hintergrund verschmelzen. iOS erlaubt es Web-Apps nicht, diesen Wert dynamisch zu aktualisieren. Führen Sie Collie direkt im Browser statt als installierte PWA aus, um diese Einschränkung zu umgehen.

Zen-Modus

Hinweis. Der Zen-Modus ist standardmäßig deaktiviert.

Aktivieren Sie ihn unter Einstellungen → Zen-Modus (wird pro Gerät im Browser gespeichert). Dadurch wird dem Bereichsmenü unter dem ⋮ neben „Suchen“ und „Verlauf“ die Option Zen-Modus hinzugefügt. Ein Fingertipp darauf blendet alle Collie-UI-Elemente aus: Kopfzeile, Reiter- und Bereichsleisten, Agent-Statuszeile sowie Composer-Docks. Nur die Terminal-Spiegelung bleibt sichtbar. Eine schwebende Schaltfläche in der oberen rechten Ecke oder die Escape-Taste stellt die Benutzeroberfläche wieder her.

Der Zen-Modus ist flüchtig. Die Konfiguration bleibt erhalten, aber der aktive Zustand wird zurückgesetzt, wenn Sie den Bereich wechseln oder die Seite neu laden. Bereiche öffnen sich immer mit den Standard-Bedienelementen.

Die Terminal-Spiegelung fragt auch im Zen-Modus weiter Daten ab, und interaktive Pufferelemente bleiben funktionsfähig. Eingabeschaltflächen, „Ältere laden“ und Steuerelemente für „Gesamten Verlauf anzeigen“ bleiben verfügbar, da sie Teil des Inhaltsdatenstroms und nicht der Bedienelemente sind.

Sprache

Die Benutzeroberfläche von Collie ist in sechs Sprachen verfügbar. Konfigurieren Sie dies unter Einstellungen → Sprache.

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

Die Auswahl wird lokal im Browser pro Gerät gespeichert. Die Terminal-Spiegelung bleibt unübersetzt: Sie zeigt die Rohausgabe des Agents an, während Kurzantworten, Menübeschriftungen und Tastenbeschriftungen den zugrunde liegenden Bildschirm- oder Tastaturnamen entsprechen.