安装 Collie

在系统上安装 Collie，启动它，并在手机上进行配置。请先阅读 安全性：Collie 在设计上会暴露本机的远程 shell 访问权限。

开始之前

Collie 需要一个前置入口：用于通过 HTTPS 提供服务并限制仅供你访问的组件。

默认的前置入口是 Tailscale。collie start 会为你运行 tailscale serve，手机则通过 tailnet（你的 Tailscale 私有网络）访问 Collie。本页其余部分均基于 Tailscale 编写。如需改用身份感知代理、反向代理、Cloudflare Tunnel 或 NetBird，请参阅 各种入口方案分别配置说明。

使用 Tailscale 时，请准备好三项配置：

1. 01
   在主机上安装 Tailscale 并运行 tailscale up，将其加入你的 tailnet。
2. 02
   打开 admin console 并选择 启用 HTTPS，为 tailnet 启用 HTTPS 证书。
3. 03
   在手机上安装 Tailscale 应用并登录同一账户，将其加入同一个 tailnet。

如果未开启 HTTPS，collie start 会报错退出。手机端也必须依赖 HTTPS 才能将 Collie 安装到主屏幕并接收 Web Push。

两种运行方式

每个 Collie 都属于两种类型之一，本页上的每个命令都针对这两种类型分别列出。选择你的对应列，并在后续文档中保持一致。

collie doctor 在其 config-file 行下列出了本次安装实际读取的配置文件。

Herdr 插件仍然是同一个 collie 二进制文件；各项操作会转发给它（Herdr 操作）。插件安装方式不会在你的 PATH 中添加 collie，因此没有对应 action 的动词命令（pair、qr、logs、link、devices、stt、config）需要从插件目录中作为 bin/collie <verb> 运行。

Herdr 也是 Collie 可以镜像的五种复用器之一（Herdr、tmux、zellij、tuios 和 tern）。镜像哪一个属于独立的选择（指定你的多路复用器）：独立运行的 Collie 可以镜像 Herdr，而 Herdr 插件可以镜像 tmux。

环境要求

Collie 运行在 Linux 和 macOS 上。搭载 Herdr 的 Windows 11 x64 是受支持的主机，目前仍标记为实验性；参见 Windows 支持。

注意。 Collie 不强制要求最低 tmux 或 zellij 版本。适配器已针对 tmux 3.4、tmux 3.6b 和 zellij 0.44.2 进行了测试。此处处理了一个 tmux 边缘情况：在采用 window-size manual 的服务器上，低于 3.7 的 tmux 版本在创建窗口时会崩溃。Collie 会拦截该请求并提示你运行 tmux set -g window-size latest。

可选依赖，仅在使用这些功能时需要：

安装

在下方找到你的系统，运行对应命令，然后继续阅读 启动它。

Linux

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

该脚本会安装适用于 x86_64 或 arm64 的预构建二进制文件。独立安装 说明了它的具体操作以及如何固定版本。

collie start 将 bridge 作为 systemd --user 服务运行。它会在您登出时停止。在通过 SSH 连接的服务器上，若要在登出和重启后保持运行：

loginctl enable-linger $USER

详见 在系统重启后保持运行。

Arch Linux 与 Omarchy

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

collie-bin 尚未进入 AUR 或 Omarchy 的仓库。目前请通过此仓库的 PKGBUILD 构建。它会直接下载预编译二进制文件，无需编译。发布后，即可使用 sudo pacman -S collie-bin（Omarchy）或 paru -S collie-bin（AUR）替代本地克隆。

Omarchy 包含 tmux 和 Herdr。首次启动时必须指定要镜像的一项，例如 COLLIE_MUX=herdr collie start。“包详情”下的 Arch 和 Omarchy 涵盖了目录结构、更新以及卸载说明。

NixOS 与 Nix

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

此方案适用于 NixOS 以及任何在 x86_64-linux、aarch64-linux 和 aarch64-darwin 上安装了 Nix 的系统。目前尚无 NixOS 模块。其余内容见“包详情”下的 Nix。

macOS

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

发布的 Mac 二进制文件涵盖 Apple Silicon (macos-arm64) 与 Intel (macos-x64)，并要求最低 macOS 13 或更高版本（其 Bun 构建所链接的最低版本）。Intel 二进制文件使用 Bun 的 baseline 目标构建，因此也可在不支持 AVX2 的 Mac 上运行。

collie start 会在 ~/Library/LaunchAgents 中注册一个 launchd agent。它会在登录时启动 Collie，并在崩溃后重启。它还会运行 tailscale serve，因此 tailscale 命令必须位于 PATH 中。Mac 版 Tailscale 应用可在其设置中安装该命令。

注意。 仅通过 SSH 访问的 Mac 没有用于 launchd 的登录会话。collie start 会报告此情况，并在无守护状态下于后台运行 bridge：失败不会重启，登录时也不会执行任何操作。

macOS 尚无安装包。mise 可在 Mac 上运行，aarch64-darwin Nix 输出也可以正常使用。

Windows 支持（实验性）

实验性功能。 安装已在 Windows 11 虚拟机上针对公开发布的 v1.16.0 版本完成测试，更新也已针对发布文件的本地副本进行演练。通过 Tailscale Serve 经由 HTTP 的手机访问也已运行验证。两个真实版本之间的更新以及 HTTPS 形式的手机访问尚未测试。从现在开始，发布检查要求必须提供 Windows zip 文件。只有维护者可以在发布 Linux 热修复时覆盖此项规则。“受支持”意味着维护者负责该代码并进行测试；在 Windows 页面上的条件全部满足之前，状态仍为“实验性”。Windows 上的 Collie 包含完整页面内容。

运行 install.ps1。它不需要 Bun、Git 或 bash：

irm https://colliepwa.dev/install.ps1 | iex

若想先阅读脚本，请将其保存，打开并作为文件运行：

Invoke-WebRequest -OutFile install.ps1 https://colliepwa.dev/install.ps1
notepad install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1

然后打开一个新终端并启动 Herdr。Herdr 会接管该终端，因此请打开第二个终端或一个 Herdr 窗格并在其中运行 collie start。从零到手机访问 包含每个步骤，包括如何在手机上打开 Collie。

开始前需要了解的事项：

• —
  仅限搭载 Herdr 的 Windows 11 x64。 tmux、zellij、Windows 10 和 Windows on ARM 均不在覆盖范围内。
• —
  二进制文件未经签名。 SmartScreen 可能会在运行前弹出提示，Smart App Control 可能会直接阻止运行。Windows 页面。
• —
  你需要自行发布该地址。 在 Linux 和 macOS 上，collie start 会为你运行 tailscale serve。在 Windows 上它不会运行，因此你需要手动执行：通过手机访问 包含使用 Tailscale 的步骤，变体 C 介绍了反向代理。
• —
  在此 release 中，Windows 机器无法加入 crew。
• —
  从源码构建需要 Git for Windows 的 bash。 zip 无需工具链。
• —
  在 Windows 上，源码检出永远不会自动更新。 迁移到 zip 安装是一次性手动操作：collie uninstall，然后 install.ps1。之后 collie update 即可正常使用。详情请见 更新。

独立安装

安装脚本将最新版本下载到 ~/.local/share/collie（COLLIE_DIR）并将二进制文件链接到 ~/.local/bin/collie：

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

它会获取最新的稳定版本，且不会变动现有的安装。若要更新现有安装，请使用 collie update。权威来源是仓库中的 scripts/install.sh：仅一页 POSIX sh 内容，绝不调用 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

如果 ~/.local/bin 不在 PATH 中，直接运行二进制文件：

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

固定版本或修复现有安装（参见 当 collie 无法运行时）：

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

该脚本会请求 GitHub API 获取 release 信息，此接口对每个 IP 地址有速率限制。若返回 HTTP 403，请按上文所示固定版本，或将 GH_TOKEN 设置为无权限 scope 的 token。参见 如果 GitHub 限制 release 检查的速率。

如需获取预发布版本，请传入 --beta。它会选择最新的预发布版本，之后安装会持续跟踪该大版本的预发布更新，直到正式版本发布（预发布版本）。

从源码构建的相同结果

# 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

从源码构建需要 Bun 和 git。通过 bin/collie start 启动，或在建立链接后通过 collie start 启动。

Herdr 插件

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

请先启动 Herdr 服务（herdr 或 herdr server &）。此操作适用于 Linux 和 macOS。

若改为从本地克隆安装：

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

对于预发布版本，请使用 herdr plugin install AltanS/collie --ref <tag> --yes 安装该 tag。这样即可完成加入（预发布版本）。

通过包管理器安装

包是由您的包管理器维护的独立安装：负责安装、更新和卸载。各包管理器的命令已在上文及 软件包详情 下列出，同时还提供了适用于 Linux 和 macOS 的 mise。

包不是 Herdr 插件。要在 Herdr 中显示 Collie 的按钮，只需对安装目录树建立一次链接：

herdr plugin link /opt/collie

Herdr 不会扫描 /opt，因此绝不会自动检测到该包。该插件的 update 和 update-major 操作将拒绝运行，并提示您使用包管理器。这是预期行为：该目录树由您的包管理器管理。

指定你的多路复用器

Collie 镜像一个后端：COLLIE_MUX=herdr（默认）、tmux 或 zellij。

您无需在首次启动前进行配置。start 会检查活跃的 Herdr socket、正在运行的 tmux 服务端以及 zellij 会话，输出检测到的内容，并将您的选择写入配置文件 .env（如有必要会创建该文件）。

在没有终端交互提示的情况下，start 会自动选择检测到的唯一后端并予以报告。如果未检测到任何后端，或检测到多个后端，它将拒绝启动并提示您设置 COLLIE_MUX。

若要提前选择，请在首次启动前预先写入配置：

mkdir -p ~/.config/collie
cp ~/.local/share/collie/current/.env.example ~/.config/collie/.env

该路径适用于安装脚本；源码检出的根目录下包含 .env.example。对于 Herdr 插件，该文件位于 herdr plugin config-dir herdr.collie 所指向的位置。然后设置后端及其端点：

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

注意。 启动后不要运行该 cp：它会覆盖 start 刚刚写入的 COLLIE_MUX 值。

配置变动后可随时修改此文件。详见 将 Collie 指向多路复用器。

启动它

herdr plugin action invoke start --plugin herdr.collie   # Herdr plugin
collie start                                             # standalone

start 将会：

1. 01
   若缺失则构建 web/dist。
2. 02
   在 systemd --user（或 launchd/nohup）下启动 bridge。
3. 03
   运行 tailscale serve --bg 8787（HTTPS :443 → 127.0.0.1:8787）。
4. 04
   输出连接提示信息。

首次运行：界面说明

collie start 的输出（Herdr 运行会返回 JSON；使用 herdr plugin log list --plugin herdr.collie 查看日志）：

$ 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

若健康检查失败（⚠ Collie isn't answering on :8787 yet），参见 问题排查。

网桥作为 systemd --user 服务或 macOS launchd agent 运行。它在登录时启动，并在故障时重启（ARCHITECTURE.md §3）。在 Linux 上，loginctl enable-linger $USER 使其在重启后保持运行（在系统重启后保持运行）。

在 配置 中配置用户访问权限，并通过 配对 配置设备访问权限（collie pair）。

它是否正常运行？

验证状态和日志：

$ 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

$ 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 is checked by its pairing token alone. Set it to your tailnet login (see README → Variant A).

若要限制访问，请在 .env 中设置 COLLIE_TRUSTED_USER=you@example.com 并运行 collie restart（配置）。若仪表盘内容缺失，请参阅 问题排查。

在手机上使用

在手机上打开 Collie，完成配对，并将 Collie 添加到主屏幕。

1. 01
   确认手机上的 Tailscale 应用与主机处于同一个 tailnet 中。
2. 02
   在主机上运行 collie qr 并扫描其二维码，或者打开 collie url 输出的 URL。
3. 03
   在主机上运行 collie pair 并扫描该二维码。

扫描 collie pair 中的二维码可打开“设置 → 系统 → 已配对设备”并自动填入验证码。你也可以手动打开“设置 → 系统 → 已配对设备”并输入验证码。在设备配对前，Collie 不会响应任何设备，因此在此之前仪表盘会显示 配对该设备（配对设备）。

Collie 是一个 Web 应用。浏览器无需通过应用商店即可将其添加到主屏幕，提供独立图标和全屏视图。

iPhone 和 iPad

1. 01
   在 Safari 中打开 Collie URL。
2. 02
   轻点 分享，然后轻点 添加到主屏幕。
3. 03
   轻点 添加。

在 iOS 16.4 及更高版本中，Chrome、Edge 和 Firefox 也在其分享菜单中提供 添加到主屏幕。如果看到 作为 Web App 打开，请保持选中状态。

Safari 不提供安装按钮。在你完成这些步骤之前，Collie 的 Settings 会显示包含上述步骤的“Install”卡片。

注意。 在 iPhone 或 iPad 上，Web Push 需要 iOS 16.4 或更高版本，且仅在通过主屏幕图标打开时有效。从该图标打开 Collie，然后在 Settings 中启用通知。

Android

1. 01
   在 Chrome 中打开 Collie URL。
2. 02
   前往 Collie 的 Settings，并轻点顶部卡片上的 安装。

Chrome 提供安装选项后会显示此卡片。如果没有显示，请打开 Chrome 菜单 (⋮)，轻点 添加到主屏幕，然后轻点 安装。某些 Chrome 版本将其标记为 安装应用。Firefox 和三星浏览器在主菜单中使用 添加到主屏幕。

Android 在标准浏览器标签页中即支持 Web Push。安装操作仅用于添加主屏幕图标和全屏模式。

桌面端

Chrome 和 Edge 会在地址栏显示安装图标，同时在“设置”中显示 安装 卡片。在 macOS 上，Safari 17 及更高版本使用 文件 → 添加到程序坞。

各设备通用注意事项

• —
  安装需要 HTTPS。在 COLLIE_SERVE_MODE=http 下，浏览器会禁用 service worker，将 Collie 限制在标准浏览器标签页中运行。
• —
  开发版本（基于非 release tag 检出的代码构建）会安装为 Collie (dev) 并带有橙色图标，避免与正式发布版本混淆。
• —
  配对绑定到单个设备。请为你打算使用的每部手机、平板电脑或浏览器进行配对。
• —
  推送通知需要主机密钥：Web Push。

首次启动

当 Collie 首次在设备上打开并加载仪表盘时，引导界面会概述你的配置。它会列出当前活跃的 multiplexer、镜像主机、正在运行的窗格、等待输入的窗格、crew 机器数量以及你的写权限。

在此下方，它会建议最多两项操作：配对设备、启动任务、启用提醒，或将 Collie 添加至主屏幕。末尾提供了六项可直接运行的核心任务。

应用在加载时会将此界面标记为已读，因此关闭标签页后不会再次显示。之后可以在“设置”中点击 再次显示首屏 重新查看。

更新

一条命令即可获取当前大版本的最新发布版。

herdr plugin action invoke update --plugin herdr.collie   # Herdr plugin
collie update                                             # standalone

它会将新版本部署在旧版本旁边，完成切换，重启 bridge；若新版本无响应，则执行回滚。

通过软件包安装的版本使用其包管理器更新，随后需要重启，因为包管理器只替换文件而不重启任何服务：

sudo pacman -Syu collie-bin                 # Omarchy; on the AUR: paru -S collie-bin
nix profile upgrade collie                  # Nix
mise upgrade --bump github:AltanS/collie    # mise
collie restart

在软件包安装上执行 collie update 会被拒绝，并提示改用该命令。手机在原本显示更新按钮的位置也会显示相同的命令。

跨主版本升级是一个单独的、需要确认的步骤：

herdr plugin action invoke update-major --plugin herdr.collie   # Herdr plugin
collie update --major                                           # standalone

手机也可以执行常规更新：设置 → 系统 → 更新，轻点一次；在 crew lead 上轻点一次即可将所有成员同步到同一版本。关于手机端更新路径、运行前检查、回滚、crews 以及更新卡住时的处理方法，请参见 管理与更新。

卸载

分为三个步骤，按此顺序执行。每一步只移除一层，不涉及其他内容。

1. 移除服务和端口映射。 这会停止 bridge，删除 systemd --user 单元（macOS 上为 launchd agent）并移除 Collie 自身的 tailscale serve 映射。程序文件和你的 .env 会保留。

herdr plugin action invoke uninstall --plugin herdr.collie   # Herdr plugin
collie uninstall                                             # standalone

2. 移除程序。

herdr plugin uninstall herdr.collie      # Herdr plugin, installed from GitHub
herdr plugin unlink herdr.collie         # Herdr plugin, a linked clone or a linked package

collie unlink                            # standalone: drop the ~/.local/bin/collie symlink
rm -rf ~/.local/share/collie             # standalone: the install script's tree, or $COLLIE_DIR

sudo pacman -Rns collie-bin              # package: Arch and Omarchy
nix profile remove collie                # package: Nix
mise uninstall github:AltanS/collie@1.14.2  # package: mise, the version
mise unuse github:AltanS/collie             # package: mise, the config line

链接的克隆是你自己的检出副本。unlink 会注销 Herdr 注册，目录则保留供你删除或留存。

3. 移除你自己的文件（若不需要保留）。 上述操作均不会影响这些内容，因此重新安装后仍能找到原有的配对和设置：

若只想暂停而不删除任何内容，运行 stop 即可：

herdr plugin action invoke stop --plugin herdr.collie   # Herdr plugin
collie stop                                             # standalone

软件包详情

PKGBUILD、Nix 表达式及其说明位于此仓库的 packaging/ 中。每个包都包含发布版本已提供的编译二进制文件，因此不会在你的机器上构建任何内容：无需 Bun，无需 git，亦无需编译。整个 release 文件夹放置在同一个前缀目录下，并在你的 PATH 中创建指向它的 collie 符号链接。macOS 暂无对应包；aarch64-darwin flake 输出是最接近的替代方案。

Arch

collie-bin 尚未进入 AUR。AUR 暂停了新账号注册，待注册重新开放后，我们将通过自己的账号发布该软件包。在此之前，请通过克隆此仓库进行构建：

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

makepkg 会下载适用于你架构的发布版本 tarball，根据发布的完整性清单校验其 sha256，并解压。无需 Bun，无需克隆任何其他 git，无需编译。

进入 AUR 后，AUR 助手会安装相同的 PKGBUILD：

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

后续更新使用 paru -S collie-bin 或 yay -S collie-bin，即你安装时使用的相同命令。sudo pacman -Syu collie-bin 仅在有仓库收录该软件包时有效，例如 Omarchy 的仓库。

该软件包将发布目录树安装到 /opt/collie，并将 /usr/bin/collie 作为符号链接指向其中。README.md、CHANGELOG.md 和 docs/ 放入 /usr/share/doc/collie-bin/，许可证放入 /usr/share/licenses/collie-bin/。它提供并冲突于 collie，因此它与未来的源码包无法同时安装。它不会启用任何 systemd unit：collie start 会像在任何安装后一样写入你自己的 --user unit。

注意。 每次升级后请运行 collie restart。pacman 会替换文件但不会重启任何服务，因此服务会继续基于已删除的二进制文件运行旧构建，直到你将其重启。collie doctor 将其报告为 restart-pending，手机端会显示 "Collie was replaced on disk. Restart it." 以及需要运行的命令。

按照 卸载 下的三个步骤将其移除：先执行 collie uninstall，仅在建立过链接时执行 herdr plugin unlink herdr.collie，然后执行 sudo pacman -Rns collie-bin。pacman 仅会移除 /opt/collie 和 /usr/bin/collie，不涉及其他内容。

Omarchy

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

Omarchy 同时内置 tmux 和 Herdr，而 Collie 每次安装仅镜像一个 multiplexer，因此首次启动必须指定由哪个来驱动：当检测到两者时它不会自行猜测。start 会将该名称写入 Collie 的 .env（在装有 Herdr 的主机上为 ~/.config/herdr/plugins/config/herdr.collie/.env），之后的启动只需执行 collie start。

当 collie-bin 进入 Omarchy 自己的软件包仓库后即可这样操作，目前添加它的 pull request 尚未合并。在此之前，请像上面针对任何 Arch 主机那样，在 packaging/aur 中使用 makepkg -si 构建相同的软件包。

后续更新则直接使用 sudo pacman -Syu，即你平时用来更新机器的命令。这里不需要 AUR helper，因为 pkgs.omarchy.org 是一个真正的 pacman 仓库。无论采用哪种方式，其 PKGBUILD 和 /opt/collie 布局都完全相同。

注意。 更新来自你的包管理器，Collie 在此环境下不会自行更新。collie update 会拒绝执行。手机端的更新横条会显示 "Collie x.y.z available via pacman."，Updates 页面会显示可复制的命令来替代更新按钮，因为该目录归包管理器所有。Collie 会提示 sudo pacman -Syu collie-bin 形式（即仓库命名写法）；在 AUR 安装中请改用你的 helper。升级后请运行 collie restart，原因如上所述：pacman 不会重启任何服务。

在 crew 中，此机器绝不从手机端获取更新：crew 将其列为“等待包管理器”，且仅在您对其运行辅助程序时才会升级。

按照上面针对 Arch 的相同三个步骤进行卸载。

Nix

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

该 flake 为 x86_64-linux、aarch64-linux 和 aarch64-darwin 导出了 packages.<system>.collie。它根据发布版本自身完整性清单中的 sha256 获取对应平台的发布版本 tarball，在 Linux 上为二进制文件的解释器打补丁，并将发布版本目录树安装到 <store-path>/lib/collie，同时创建指向它的软链接 bin/collie。无需安装，直接运行一次：nix run github:AltanS/collie#collie -- doctor。

这里特意没有提供源码构建：安装依赖需要网络，而 Nix derivation 无法访问网络，因此该软件包直接封装了发布版本已经发布并附带校验和的二进制文件。

目前还没有 NixOS 模块，只有 flake 软件包，因此途径是 nix profile：按上述方式将其安装到你的 profile 中，或者自行将 flake output 添加到 home-manager 或 environment.systemPackages 列表中。

注意。 更新来自 nix，Collie 在这里不会自行更新。collie update 会拒绝并提示 nix profile upgrade collie，手机端会在原本显示更新按钮的位置展示新版本以及该命令。

在 crew 中，此机器绝不从手机端获取更新：crew 将其列为“等待包管理器”，且仅在您对其运行 nix 时才会升级。

先使用 collie uninstall 移除它，然后：

nix profile remove collie

这只会从你的 profile 中移除 store 路径，不涉及其他内容。你自己的文件会保留，如 卸载 所列。

macOS 上的 Home Manager agents

collie status
launchctl print "user/$(id -u)/herdr.collie"

collie status 会在 gui/<uid> 和 user/<uid> 中发现实例的 label，并报告其 domain 和进程状态。如果两个 domain 都包含该 label，它会同时报告两者；已停止的 GUI agent 不会隐藏正在运行的后台 agent。不需要覆盖环境变量。

对于现有的由 Home Manager 管理的 Collie agent，以下设置用于选择后台 domain（Home Manager 26.11 或更高版本）：

launchd.agents.collie = {
  domain = "user";
  config.Label = "herdr.collie";
};

这是对 agent 定义的补充，不是完整的服务模块。请在 Home Manager 中保持配置其命令、环境和日志路径。使用 collie _exec-bridge 而非 collie start 运行 bridge，这样 launchd 可以在 Collie 不重写受管 plist 的情况下监管 bridge。凭据和配对状态需保存在 Nix store 之外。使用 collie serve 单独配置 front door，或使用 external-proxy 设置。

对于命名实例，请在 agent 和 CLI 环境中使用 label herdr.collie-<name> 以及相同的 COLLIE_INSTANCE、COLLIE_PORT 和配置目录（多实例）。

注意。 Home Manager 管理服务生命周期。请更新或删除其声明并激活 Home Manager，而不是运行 collie start、stop、restart 或 uninstall。这些命令仍然管理 Collie 的 GUI-domain agent；状态发现不会转移所有权。继续正常使用 collie pair、devices、url 和 logs。

mise

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

mise use -g 会将工具写入 ~/.config/mise/config.toml，并将发布版本的 bin/ 放入你的 PATH。github 后端会拉取该平台的发布版本 tarball，因此这在 Linux 和 macOS 上均可运行，无需 Bun，无需编译。整个目录树均置于 ~/.local/share/mise/installs/github-altan-s-collie/<version>/ 下，包含 web/dist 和 herdr-plugin.toml，collie 从该位置解析其自身的根目录。

使用相同的 mise use 行配合更新的 tag 获取新版本，或者让 mise 选择最新版本：

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

--bump 是关键的 flag。固定的 1.14.2 是一个单值范围，因此直接执行 mise upgrade 会报告工具已是最新且不会移动任何内容。

重启是必须的。每个版本都有自己的目录，并且 collie start 会将运行它的目录固定写入服务定义中，因此服务会继续从旧目录运行旧版本，直到你将其重启。collie restart 会使用新路径重写该定义：Linux 上为 systemd --user unit，macOS 上为 ~/Library/LaunchAgents plist。两端均为同一命令。

注意。 仅通过 SSH 管理的 Mac 没有用于加载 agent 的 gui/<uid> 域。在此情况下 collie start 会给出提示并改为运行不受监管的后台桥接，故障时不重启，登录时不自启。collie restart 仍会将其迁移到新目录。

注意。 collie update 在此会被拒绝，并且不会提示包管理器名称：它会显示 cannot tell how this Collie was installed。mise 目录树位于你的 home 目录下，自身不带 .git，上方也没有 versions/ 布局，因此 Collie 既不将其视作代码检出，也不视作软件包。在此安装中，mise 负责更新，通过上述两条命令完成版本迁移。

先使用 collie uninstall 移除它，然后：

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

uninstall 会删除该版本的目录，unuse 会从配置中移除该行。两处均须使用该工具完整的 github: 名称；简短的 collie 仅适用于 upgrade，不适用于 uninstall。你自己的文件会保留，如 卸载 所列。