Configuración

Por defecto, Collie se ejecuta en modo de usuario único abierto: cualquier persona en su tailnet que pueda acceder a la URL tiene control total. Esto activa la advertencia TRUSTED_USER. Restrinja el acceso:

# 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 carga la configuración desde un archivo .env en ~/.config/collie. Si Herdr administra la instalación, la CLI consulta a Herdr por el directorio de configuración del plugin (normalmente ~/.config/herdr/plugins/config/herdr.collie). Ambas rutas se resuelven de forma coherente en todos los comandos de la CLI, por lo que el servicio lee el archivo inicializado aquí:

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"

Las rutas siguientes usan ~/.config/collie/…. En una instalación administrada por Herdr, reemplace ese prefijo por $(herdr plugin config-dir herdr.collie).

Collie lee .env únicamente durante el inicio. Ejecute collie restart tras modificarlo.

El archivo .env.example lista todas las opciones.

Incluye COLLIE_PORT, COLLIE_SERVE_MODE=http (para dominios de Headscale o .internal) y COLLIE_SERVE_PORT (para exponer HTTPS en un puerto distinto de :443; consulte docs/deployment.md → Varios Collie en un mismo host). La CLI lee los parámetros de serve para configurar tailscale serve, en lugar de pasarlos al puente.

Para leer el historial de múltiples directorios de inicio de agentes, proporcione una lista separada por comas en COLLIE_TRANSCRIPT_ROOT.

docs/deployment.md cubre dominios personalizados y proxies inversos. Collie aplica una política de mismo origen, por lo que cualquier nombre de host personalizado o terminador TLS externo debe incluirse explícitamente en la lista de permitidos:

COLLIE_ALLOWED_ORIGINS=https://collie.example.com

Sin este ajuste, la interfaz de usuario se cargará como una página vacía. Consulte Resolución de problemas para más detalles.

Comandos de barra propios

Coloque los comandos específicos de la máquina, como un plugin /fork-in-herdr de Herdr o un /deploy personalizado, en commands.toml. Este es uno de los cuatro archivos de configuración que comparten el mismo lector y patrón de carga:

Cualquier fila con el indicador activado requiere una confirmación de dos toques antes de ejecutarse. Las modificaciones en cualquiera de estos archivos surten efecto sin reiniciar el servicio. Si Collie rechaza una fila, journalctl --user -u collie -n 20 imprime el número de línea y el error.

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 panel que coincida con sus filas configuradas muestra únicamente esas filas. Prevalece la fila más específica, como se documenta en ADR 0018.

Para verificar, abra un panel y toque /; sus filas aparecerán en la primera pantalla.

Preajustes de teclas propios

Se puede reemplazar la fila Presets de la bandeja Keys en keys.toml, ubicada junto a 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

Cuando un panel coincide con las filas definidas, muestra únicamente sus ajustes preestablecidos en lugar de los botones predeterminados Ctrl C/D/U/R/L/Z (ADR 0018). El resto de la bandeja (Esc, teclas de flecha, Enter/Tab/Space, modificadores, dígitos, F1-F12) es fijo.

Las combinaciones de teclas usan la sintaxis de herdr, no la de tmux:

Para verificar, abra un panel y toque Keys → Presets para ver los nuevos botones. Si Collie rechaza una fila, revise journalctl --user -u collie -n 20 para ver los detalles del error.

Respuestas rápidas propias

Se pueden personalizar las frases del dock Quick en 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

Cuando un panel coincide con las reglas, los grupos definidos reemplazan a los predeterminados (ADR 0018). Las frases predeterminadas están en inglés (yes, commit and push).

Utilice este archivo para ejecutar en otros idiomas o para enviar palabras como approve a entornos específicos. Configurar scope = "shell" apunta a paneles de shell estándar, que de lo contrario solo reciben y/n.

Para verificar, abra un panel y toque Quick para ver los grupos. Si una fila no se carga, journalctl --user -u collie -n 20 imprime el error.

Lanzadores propios

Un toque ejecuta un comando declarado, en launchers.toml junto a 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

El lugar donde se abre el elemento depende de dónde se toque, no de la fila. Desde panel de control, un toque crea un nuevo Space con el nombre de la fila. Desde un panel (el panel selector al que se accede deslizando hacia arriba), un toque abre un nuevo pestaña en el Space propio de ese panel junto a él.

En cualquier caso, el puente escribe command en el nuevo shell y envía Enter. El comando gestiona su propio ciclo de vida: uno que se cierra solo se lleva consigo el Space o la pestaña, y htop permanece hasta que se cierre.

cwd es donde se abre ese nuevo Space o pestaña. Si se fija uno (como hace htop arriba), tiene prioridad sin importar dónde se toque la fila.

Si se omite, significa "aquí": el panel de control lo abre en el directorio personal, un panel lo abre en el cwd de el propio de ese panel; una fila sin cwd sigue la ubicación actual entre los distintos repositorios en lugar de abrirse siempre en la raíz de uno.

Este archivo es la lista de permitidos. POST /api/launch solo acepta un command que coincida exactamente con una fila aquí, por lo que un teléfono no puede iniciar nada que no esté en el archivo. Los cambios se aplican de inmediato sin reiniciar, pero una pestaña ya abierta solo vuelve a leer las filas en su siguiente carga.

Las filas aparecen en dos lugares: una sección Iniciar en el panel de control, que se pliega como Spaces y Recent, y una sección Iniciar en el panel selector (deslizar hacia arriba desde un panel). Una fila fijada muestra su carpeta, abreviada respecto al directorio personal; una fila sin cwd muestra "aquí" en el selector (el panel de control ya asume el directorio personal, por lo que no muestra nada allí). Si no se declaran filas, no aparece ninguna de las dos secciones.

En un pack (varias máquinas, un nodo principal orientado al teléfono), cada máquina lee su propia copia de este archivo: una fila se inicia en el panel de control o en el panel de la máquina desde donde se tocó, no en el nodo principal.

Para verificar, recargue el panel de control y revise debajo de la manada. Si una fila no se carga, journalctl --user -u collie -n 20 imprime el error.

Tipografías propias

La fuente de la interfaz es un ajuste por dispositivo. En Settings → Typeface, se puede elegir entre System, Space Grotesk (la predeterminada) y Aldrich. Se pueden añadir fuentes personalizadas en theme.toml, el cuarto archivo de configuración:

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

Las fuentes personalizadas se añaden al final de la lista integrada en lugar de reemplazarla (ADR 0033), a diferencia del comportamiento en commands.toml y en los otros archivos de configuración. Dado que las fuentes no desencadenan acciones, no hay nada que enmascarar.

Aparecen debajo de las tres entradas predeterminadas y cada dispositivo cliente selecciona la suya.

Tres comportamientos a tener en cuenta:

• —
  Desplazamiento del diseño en la primera carga. Las fuentes personalizadas carecen de alternativas con métricas coincidentes, lo que causa un leve desplazamiento del diseño durante la carga inicial. Las fuentes integradas evitan esto porque sus alternativas se generan en tiempo de compilación.
• —
  Retraso en carga en frío. Una carga en frío descarga el archivo con un breve retraso; un cliente en caché renderiza de inmediato.
• —
  Solo interfaz. La fuente seleccionada se aplica únicamente a la interfaz de Collie. El espejo del terminal, la transcripción y el markdown renderizado conservan su propia tipografía.
• —
  Activo en la siguiente recarga. Los cambios no requieren reinicio y surten efecto en la siguiente recarga de la página. Las configuraciones inválidas registran errores visibles mediante journalctl --user -u collie -n 20.

Adjuntos

El icono de clip junto al cuadro de mensaje sube un archivo al host y coloca su ruta en el mensaje.

# 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 guarda el archivo en <state-dir>/uploads con permisos exclusivos para el propietario y añade su ruta absoluta al borrador. El agente lo lee desde esa ruta, ya que una terminal no admite pegar archivos. Las subidas se purgan 48 horas después de haberse escrito.

Se aceptan dos tipos de archivos, y se comprueban de manera diferente.

Imágenes se identifican por sus bytes de firma, nunca por su nombre o su tipo declarado: png, jpg, gif y webp. SVG se rechaza deliberadamente, ya que es marcado con capacidad de ejecutar scripts en lugar de una imagen.

Texto se identifica por su extensión, con los bytes como veto: un archivo cuyos primeros 4 KB contengan un byte NUL o de control aislado se rechaza independientemente de su nombre. La lista incluida es 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 y patch.

Nota. COLLIE_UPLOAD_EXTRA_TYPES añade únicamente tipos de texto. Una imagen requiere una firma contra la cual comprobarse, por lo que no hay formatos binarios que se puedan añadir de esta forma.

Aumentar COLLIE_MAX_UPLOAD_MB incrementa otros dos números a la vez. El puente lee una subida completa en memoria antes de poder medirla, por lo que un límite alto junto con varias subidas simultáneas consumirá esa cantidad de memoria. Además, el límite del cuerpo del runtime se aplica a todas las rutas, no solo a la de subida, por lo que un límite alto permite que un cuerpo grande llegue a cualquier controlador, donde el propio límite de ese controlador lo rechazará. No se elimina nada antes de que transcurran sus 48 horas, por lo que el directorio de subidas almacena como máximo lo enviado en dos días. Aumente el número únicamente si lo necesita, no por defecto.

En un pack, ambos ajustes son por máquina, y la máquina que almacena el archivo es la que los aplica. El nodo principal rechaza un cuerpo de tamaño excesivo antes de reenviarlo, para ahorrar enlace de subida, pero lo rechaza según su propio número. Configure los mismos valores en cada miembro, o un par rechazará lo que su nodo principal permitió pasar.

Multisesión

Por defecto, una instancia de Collie atiende todas las sesiones de Herdr que encuentra.

COLLIE_MULTI_SESSION=on (la opción predeterminada) detecta y sirve cada sesión nombrada de Herdr bajo su raíz de configuración, intercambiable desde el encabezado. Definir COLLIE_MULTI_SESSION=off sirve solo la sesión principal. Todas las sesiones detectadas son accesibles a través de la misma URL, incluidas las sesiones privadas o de sandbox. Seguridad lista este comportamiento como un punto crítico.

Modo oscuro / modo claro

Nota. Collie sigue la apariencia del teléfono por defecto.

Para fijarla, abra Configuración → Apariencia y elija Sistema, Claro o Oscuro. El ajuste se almacena por dispositivo en el navegador y no en el puente. El teléfono puede permanecer en modo oscuro mientras una portátil sigue el sistema operativo. La preferencia persiste entre recargas y reinstalaciones de la PWA en el mismo dispositivo.

El espejo del terminal es diferente de forma deliberada

El espejo siempre se renderiza sobre un fondo oscuro. El modo claro invierte todo el elemento en lugar de cambiar el color de cada span por separado.

Los agentes emiten códigos de color absolutos de 24 bits (38;2;r;g;b) ajustados para fondos oscuros, los cuales los analizadores posteriores no pueden reasignar de forma confiable. Renderizada directamente sobre blanco, la mayor parte de la salida del agente cae por debajo de una relación de contraste de 3:1. La inversión conserva el contraste previsto. Las mediciones están documentadas en ADR 0002.

Esta implementación tiene dos consecuencias prácticas:

• —
  Mantenga los agentes configurados con temas oscuros. Este es el valor predeterminado para Claude Code, codex, opencode y pi. Si un agente utiliza un tema claro, emite valores de texto oscuro sobre fondo claro que se vuelven ilegibles en Collie en ambos modos. Esto se debe a la salida del agente y no a Collie.
• —
  Los diffs y las filas resaltadas se renderizan como bloques oscuros en modo claro. El contraste permanece intacto, pero el peso visual se invierte.

Nota. Al instalarse en iOS, en modo claro, el texto de la barra de estado permanece blanco y puede confundirse con el fondo. iOS no permite que las aplicaciones web actualicen este valor de forma dinámica. Ejecute Collie directamente en el navegador en lugar de como PWA instalada para evitar esta limitación.

Modo Zen

Nota. El modo Zen está desactivado de forma predeterminada.

Actívelo en Configuración → Modo Zen (se almacena por dispositivo en el navegador). Esto añade la opción Modo Zen al menú del panel, bajo el icono ⋮ junto a Find e History. Al pulsarlo, se ocultan todos los elementos de la interfaz de Collie: el encabezado, las barras de pestañas y paneles, la línea de estado del agente y los acoplamientos del compositor. Solo permanece visible el reflejo del terminal. Un botón flotante en la esquina superior derecha o la tecla Escape restaura la interfaz.

El modo Zen es transitorio. La configuración persiste, pero el estado activo se restablece al cambiar de panel o recargar la página. Los paneles siempre se abren con la interfaz estándar.

El reflejo del terminal continúa sondeando en modo Zen y los elementos interactivos del búfer siguen funcionando. Los botones de indicaciones, "Load older" y los controles "Show entire history" permanecen disponibles porque forman parte del flujo de contenido y no de la interfaz.

Idioma

La interfaz de Collie está disponible en seis idiomas. Configure esta opción en Configuración → Idioma.

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

La selección se guarda localmente en el navegador por dispositivo. El reflejo del terminal permanece sin traducir: muestra la salida sin procesar del agente, mientras que las respuestas rápidas, las etiquetas de menú y los nombres de las teclas coinciden con los nombres subyacentes de la pantalla o del teclado.