Instalar Collie

Requisitos del host, los dos métodos de acceso y configuración inicial. Lea Seguridad primero: Collie expone acceso remoto a la shell de su máquina por diseño.

Requisitos

Hosts compatibles: Linux y macOS. Windows es experimental; consulte Windows.

Nota. No se exige una versión mínima de tmux o zellij. Los adaptadores se probaron con tmux 3.4, tmux 3.6b y zellij 0.44.2. Se contempla un caso especial de tmux: en un servidor que usa window-size manual, las versiones de tmux inferiores a 3.7 fallan al crear una ventana, por lo que Collie bloquea la solicitud e indica que se ejecute tmux set -g window-size latest.

Dependencias opcionales, necesarias solo para las funciones junto a ellas:

Instalación

Tres formas de acceso:

• —
  Instalación limpia: el script de instalación, o el mismo resultado desde el código fuente.
• —
  A través de Herdr: Collie se integra como un plugin de Herdr, controlado mediante acciones de plugin.
• —
  Desde un paquete: el gestor de paquetes instala Collie y gestiona sus actualizaciones.

Herdr es uno de los tres multiplexores que Collie puede reflejar, no una dependencia del programa. Cuál reflejar es el paso posterior a este.

Instalación limpia

El script de instalación descarga la versión más reciente en ~/.local/share/collie (COLLIE_DIR) y enlaza el binario a ~/.local/bin/collie:

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

Obtiene la versión estable más reciente y no modifica una instalación existente; para eso sirve collie update. La fuente canónica es scripts/install.sh en el repositorio: una página de POSIX sh, y nunca solicita 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 no está en su PATH, ejecute el binario directamente:

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

Para fijar una versión o recuperar una instalación existente (consulte Cuando collie no se ejecute):

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

Para versiones preliminares, pase --beta: toma la versión preliminar más reciente y la instalación sigue las versiones preliminares de esa versión mayor hasta que se publique la versión final (Versiones preliminares).

El mismo resultado, desde el código fuente

# 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

Luego inícielo. start crea ~/.config/collie/ y escribe la elección del multiplexor en su .env, por lo que no es necesario inicializar nada a mano primero:

bin/collie start

A través de Herdr

Inicie primero el servidor de Herdr (herdr o herdr server &).

Desde GitHub:

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

Desde el código fuente local:

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

Adminístrelo mediante Acciones de Herdr. Para una versión preliminar, instale la etiqueta con herdr plugin install AltanS/collie --ref <tag> --yes, lo cual completa la suscripción (Versiones preliminares).

Desde un paquete

Donde Collie esté empaquetado para su sistema, instálelo como cualquier otro paquete. El paquete contiene el binario compilado que la versión ya publica, por lo que no se compila nada en su máquina: sin Bun, sin git, sin compilación. La carpeta de la versión completa se ubica bajo un único prefijo, con collie en su PATH como un enlace simbólico hacia ella.

Un paquete no es un plugin de Herdr, y cada verbo collie en su PATH funciona igual en ambos casos. Para tener los botones de Collie dentro de Herdr, enlace el árbol instalado una sola vez:

herdr plugin link /opt/collie

Herdr no escanea /opt, por lo que nunca encuentra el paquete por sí solo. Las acciones update y update-major del plugin se rechazan e indican su gestor de paquetes en su lugar. Esto es correcto y no un error: este árbol le corresponde actualizarlo a su gestor de paquetes.

Arch

collie-bin aún no está en el AUR. El AUR ha pausado el registro de cuentas nuevas, y el paquete se publicará desde nuestra propia cuenta cuando el registro se reabra. Hasta entonces, compílelo a partir de un clon de este repositorio:

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

makepkg descarga el tarball de la versión para su arquitectura, comprueba su sha256 con el manifiesto de integridad de la versión y lo descomprime. Sin Bun, sin clonar git de ninguna otra cosa y sin compilación.

Una vez que esté en el AUR, un helper de AUR instala el mismo PKGBUILD:

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

Las actualizaciones posteriores se hacen con paru -S collie-bin o yay -S collie-bin, el mismo comando con el que realizó la instalación. sudo pacman -Syu collie-bin solo funciona donde un repositorio contiene el paquete, como en Omarchy.

El paquete instala el árbol de la versión en /opt/collie y /usr/bin/collie como un symlink hacia él. README.md, CHANGELOG.md y docs/ quedan en /usr/share/doc/collie-bin/, y la licencia en /usr/share/licenses/collie-bin/. Proporciona y entra en conflicto con collie, por lo que no se pueden instalar este y un futuro paquete de fuentes a la vez. No habilita ninguna unidad de systemd: collie start escribe su propia unidad de --user, como lo hace tras cualquier instalación.

Nota. Ejecute collie restart tras cada actualización. pacman reemplaza los archivos y no reinicia nada, por lo que el servicio sigue ejecutando la versión anterior sobre un binario eliminado hasta que se reinicie. collie doctor lo reporta como restart-pending, y el teléfono muestra "Collie was replaced on disk. Restart it." junto con el comando a ejecutar.

Elimínelo en tres pasos:

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

collie uninstall detiene el servicio, elimina la unidad de systemd --user y retira el mapeo tailscale serve propio de Collie; pacman luego elimina /opt/collie y /usr/bin/collie, y nada más. Se conservan dos directorios propios, que se eliminan manualmente si se desea: el estado bajo ~/.local/state/collie/ (o $COLLIE_STATE_DIR), y el directorio de configuración que contiene su .env, que es ~/.config/herdr/plugins/config/herdr.collie/ en un host con Herdr.

Omarchy

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

Omarchy incluye tanto tmux como Herdr, y Collie replica un multiplexor por instalación, por lo que el primer inicio debe indicar cuál controlar: se niega a elegir entre dos que puede ver. start escribe ese nombre en el archivo .env de Collie, que en un host con Herdr es ~/.config/herdr/plugins/config/herdr.collie/.env, y los inicios posteriores son collie start.

Eso funciona una vez que collie-bin esté en el propio repositorio de paquetes de Omarchy, y la pull request que lo añade aún no se ha fusionado. Hasta que lo esté, compile el mismo paquete desde packaging/aur con makepkg -si, como en cualquier host Arch mencionado anteriormente.

Las actualizaciones llegan luego con sudo pacman -Syu, el comando que ya ejecuta para actualizar la máquina; no interviene ningún helper de AUR, porque pkgs.omarchy.org es un repositorio real de pacman. Es el mismo PKGBUILD y la misma estructura de /opt/collie en cualquier caso.

Nota. Las actualizaciones provienen de su gestor de paquetes, y Collie no se actualizará a sí mismo aquí. En su lugar, collie update lo rechaza. La barra de actualización del teléfono muestra "Collie x.y.z available via pacman.", y la página de Actualizaciones muestra el comando para copiar en lugar de un botón de actualización, porque el gestor de paquetes es el propietario de esa carpeta. Collie indica la forma sudo pacman -Syu collie-bin, que es la nomenclatura del repositorio; en una instalación desde el AUR, ejecute su helper en su lugar. Ejecute collie restart tras la actualización por el motivo anterior: pacman no reinicia nada.

En un pack, esta máquina nunca recibe una actualización desde el teléfono: el pack la lista como "waits for the package manager", y solo se nivela cuando se ejecuta el helper en ella.

Elimínelo con los mismos tres pasos descritos anteriormente para Arch.

Nix

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

El flake exporta packages.<system>.collie para x86_64-linux, aarch64-linux y aarch64-darwin. Descarga el tarball de la versión para esa plataforma según el sha256 en el propio manifiesto de integridad de la versión, aplica un parche al intérprete del binario en Linux e instala el árbol de la versión en <store-path>/lib/collie con bin/collie como un enlace simbólico hacia él. Ejecútelo una vez sin instalar mediante nix run github:AltanS/collie#collie -- doctor.

No se compila desde el código fuente de forma deliberada: la instalación de dependencias requiere red y una derivación de Nix no tiene acceso a ella, por lo que el paquete envuelve el binario que la versión ya publica y verifica mediante sumas de control.

Aún no existe un módulo de NixOS, solo el paquete flake, por lo que nix profile es el camino: instálelo en su perfil como se indicó anteriormente, o agregue la salida del flake a una lista home-manager o environment.systemPackages manualmente.

Nota. Las actualizaciones provienen de nix, y Collie no se actualizará a sí mismo aquí. collie update rechaza la acción e indica nix profile upgrade collie en su lugar, y el teléfono muestra la nueva versión con ese comando donde estaría el botón de actualización.

En un pack, esta máquina nunca recibe una actualización desde el teléfono: el pack la lista como "waits for the package manager", y solo se nivela cuando se ejecuta nix en ella.

Elimínelo primero con collie stop, luego:

nix profile remove collie

Esto elimina la ruta del store de su perfil y nada más. Sus propios archivos permanecen: el estado en ~/.local/state/collie (o $COLLIE_STATE_DIR), la configuración en ~/.config/collie, y la unidad de systemd --user en ~/.config/systemd/user/collie.service que collie start escribió. Ejecute collie uninstall antes de eliminar el paquete para suprimir esa unidad y el mapeo de puertos.

mise

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

mise use -g escribe la herramienta en ~/.config/mise/config.toml y coloca el bin/ de la versión en su PATH. El backend github obtiene el tarball de la versión para esa plataforma, por lo que funciona en Linux y macOS sin Bun y sin compilación. Todo el árbol queda bajo ~/.local/share/mise/installs/github-altan-s-collie/<version>/, incluidos web/dist y herdr-plugin.toml, y collie resuelve su propia raíz desde allí.

Obtenga una nueva versión con la misma línea mise use y una etiqueta más reciente, o permita que mise seleccione la última:

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

--bump es el flag importante. Un 1.5.6 fijado es un rango de uno, por lo que un mise upgrade simple reporta la herramienta como actualizada y no mueve nada.

El reinicio no es opcional. Cada versión obtiene su propio directorio, y collie start fija el directorio desde el que se ejecutó dentro de la definición del servicio, por lo que el servicio sigue ejecutando la versión antigua desde el directorio antiguo hasta que se reinicie. collie restart reescribe esa definición con la nueva ruta: la unidad de systemd --user en Linux, el plist de ~/Library/LaunchAgents en macOS. Un solo comando en ambos.

Nota. Un Mac administrado únicamente por SSH no tiene dominio de gui/<uid> en el que cargar un agente. En ese caso, collie start lo advierte y ejecuta un puente en segundo plano no supervisado en su lugar, sin reinicio ante fallos y sin nada al iniciar sesión. collie restart aún lo traslada al nuevo directorio.

Nota. collie update se rechaza aquí y no indica ningún gestor de paquetes: dice cannot tell how this Collie was installed. Un árbol de mise reside dentro de su directorio personal, no contiene ningún .git propio y no tiene una estructura de versions/ por encima, por lo que Collie no lo interpreta ni como un checkout ni como un paquete. mise gestiona las actualizaciones en esta instalación, y los dos comandos anteriores son los que la modifican.

Elimínelo primero con collie uninstall, luego:

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

uninstall elimina el directorio de esa versión, unuse quita la línea de la configuración. Escriba la herramienta con su nombre github: completo para ambos; el formato corto collie funciona para upgrade pero no para uninstall. Sus propios archivos se conservan: el estado en ~/.local/state/collie (o $COLLIE_STATE_DIR), y la configuración en ~/.config/collie.

El PKGBUILD, la expresión de Nix y sus notas se encuentran en packaging/ en este repositorio. macOS aún no tiene paquete; la salida del flake aarch64-darwin es lo más cercano.

Indicar el multiplexor

Collie refleja un backend: COLLIE_MUX=herdr (predeterminado), tmux o zellij.

Nota. No es necesario configurarlo previamente.

El primer start busca un socket de Herdr activo, un servidor tmux en ejecución y sesiones de zellij, muestra lo encontrado y escribe la respuesta en la configuración .env, creándola. Sin una terminal para consultar, toma el único backend encontrado e indica cuál; si no hay ninguno o hay varios, rechaza el inicio y señala COLLIE_MUX.

Para decidirlo de antemano, inicialice ese archivo antes del primer inicio. Es ~/.config/collie/.env de forma independiente, o la ruta que imprime herdr plugin config-dir herdr.collie:

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

Luego defina el backend y su endpoint:

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

Precaución. No ejecute ese cp después de un inicio: sobrescribe con .env.example el COLLIE_MUX que el inicio acaba de generar.

Posteriormente, edite el archivo. Consulte Configurar Collie para un multiplexor.

Iniciarlo

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

start hará lo siguiente:

1. 01
   Compilar web/dist si falta.
2. 02
   Iniciar el puente bajo systemd --user (o launchd/nohup).
3. 03
   Ejecute tailscale serve --bg 8787 (HTTPS :443 → 127.0.0.1:8787). Su tailnet necesita tener HTTPS habilitado para esto (consola de administración → "Enable HTTPS"); Collie lo indicará y se detendrá si no lo está.
4. 04
   Mostrar el banner de conexión.

Primera ejecución: lo que se verá

Salida de bin/collie start (las ejecuciones de Herdr devuelven JSON; vea los registros con 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 la comprobación de estado falla (⚠ Collie isn't answering on :8787 yet), consulte Resolución de problemas.

stop detiene el servicio; uninstall elimina el servicio y el proxy. El puente se ejecuta como un servicio systemd --user, un agente de launchd en macOS, que se inicia al iniciar sesión y se reinicia ante fallos (ARCHITECTURE.md §3); en Linux loginctl enable-linger $USER permite que persista tras reiniciar (Persistencia tras reinicios).

Configure el acceso de usuarios en Configuración y el acceso de dispositivos mediante emparejamiento (bin/collie pair).

Abrir en el teléfono

Abra la URL tailnet del banner (se puede recuperar en cualquier momento con bin/collie url o generar un código QR con bin/collie qr). El cliente debe estar en la misma tailnet.

1. 01
   Emparejar el dispositivo: Ejecute bin/collie pair en el host. Escanee el código QR impreso para abrir Settings → Paired devices en el cliente con el código rellenado, o abra Settings → Paired devices en el cliente e introduzca el código (Emparejar un dispositivo).
2. 02
   Instalar PWA: Toque Añadir a la pantalla de inicio en Safari (iOS) o Chrome (Android).

Instalar la PWA requiere HTTPS; COLLIE_SERVE_MODE=http deshabilita los service workers, por lo que el teléfono solo puede usar la pestaña del navegador en ese modo.

¿Está funcionando realmente?

Verificar estado y registros:

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

Para restringir el acceso, configure COLLIE_TRUSTED_USER=you@example.com en .env y ejecute bin/collie restart (Configuración). Si falta contenido en el panel, consulte Resolución de problemas.

Mantenerlo actualizado

Un solo comando actualiza la versión mayor actual.

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

Las actualizaciones se aplican a la versión mayor actual; cambiar de versión mayor requiere collie update --major, o la acción update-major en una instalación administrada por Herdr. Para ello, reversiones y desinstalación, consulte Gestión y actualización.