Collieのインストール

ホスト要件、2種類の導入方法、および初期セットアップ。Collieは設計上マシンへのリモートシェルアクセスを公開するため、最初にセキュリティをお読みください。

要件

サポートされているホスト: LinuxおよびmacOS。Windowsは実験的です。Windowsを参照してください。

注。 tmux または zellij の最小バージョンは強制されません。アダプターは tmux 3.4、tmux 3.6b、zellij 0.44.2 でテストされています。tmux のエッジケースが1つ処理されています。window-size manual を使用しているサーバーでは、3.7 未満の tmux がウィンドウ作成時にクラッシュするため、Collie はリクエストをブロックして tmux set -g window-size latest の実行を促します。

ソフト依存関係（記載された機能でのみ必要）：

インストール

3つの導入方法:

• —
  新規インストール : インストールスクリプト、またはソースから同様に導入。
• —
  Herdr 経由 : Collie は Herdr プラグインとして配置され、プラグインアクションによって動作します。
• —
  パッケージからインストール: パッケージマネージャーが Collie をインストールし、更新も管理します。

Herdr は Collie がミラーリングできる3つのマルチプレクサのうちの1つであり、プログラムの依存関係ではありません。どれをミラーするかは この次のステップ です。

新規インストール

インストールスクリプトは最新リリースを ~/.local/share/collie (COLLIE_DIR) にダウンロードし、バイナリを ~/.local/bin/collie にリンクします:

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

最新の安定版リリースを取得し、既存のインストール環境には手を加えません。既存環境の更新には collie update を使用します。正規のソースはリポジトリ内の scripts/install.sh です。1ページの 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

プレリリース版を使用する場合は --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

次に起動します。start が ~/.config/collie/ を作成し、選択したマルチプレクサを .env に書き込むため、手動で初期設定を行う必要はありません:

bin/collie start

Herdr 経由

先に Herdr サーバーを起動してください（herdr または herdr server &）。

GitHub から:

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

ローカルソースから:

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

Herdr アクション 経由で管理します。プレリリースの場合は herdr plugin install AltanS/collie --ref <tag> --yes でタグをインストールします。オプトインに必要な操作はこれだけです (プレリリース)。

パッケージからインストール

システム向けにパッケージが提供されている場合は、通常のパッケージと同様にCollieをインストールしてください。パッケージにはリリースですでに公開されているコンパイル済みバイナリが含まれているため、ローカルマシン上でのビルドは発生しません。Bunやgitは不要で、コンパイルも行われません。リリースフォルダ全体が単一のプレフィックス配下に配置され、collieがPATH上のシンボリックリンクとして作成されます。

パッケージはHerdrプラグインではなく、PATH上にあるどのcollie動詞もどちらの構成でも同様に機能します。Herdr内にCollieのボタンを表示するには、インストールされたツリーを一度リンクします:

herdr plugin link /opt/collie

Herdrは/optをスキャンしないため、自動でパッケージを検出することはありません。そのため、プラグインのupdateおよびupdate-majorアクションは拒否され、代わりにパッケージマネージャーの名前が提示されます。これは不具合ではなく正常な動作です。このツリーの更新はパッケージマネージャーが管理します。

Arch

collie-binはまだAURに登録されていません。現在AURでは新規アカウント登録が停止されており、登録が再開され次第、公式アカウントからパッケージを公開する予定です。それまでは、本リポジトリのクローンからビルドしてください:

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

makepkgは使用中のアーキテクチャに応じたリリースターボールをダウンロードし、リリースの整合性マニフェストと照合して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ユニットは有効化されません。collie startを実行すると、通常のインストール後と同様に独自の--userユニットが生成されます。

注。 アップグレード後は毎回collie restartを実行してください。pacmanはファイルを置き換えるだけで再起動は行わないため、再起動するまでサービスは削除済みバイナリ上で古いビルドを実行し続けます。collie doctorはこれをrestart-pendingとして報告し、スマートフォン側には実行すべきコマンドとともに「Collie was replaced on disk. Restart it.」と表示されます。

3つのステップで削除します:

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

collie uninstallはサービスを停止し、systemd --userユニットを削除して、Collie自身のtailscale serveマッピングを解除します。続いてpacmanが/opt/collieと/usr/bin/collieのみを削除します。ユーザー独自の2つのディレクトリは残るため、不要になったら手動で削除してください。対象は~/.local/state/collie/（または$COLLIE_STATE_DIR）配下の状態データと、.envを保持する設定ディレクトリ（Herdr環境では~/.config/herdr/plugins/config/herdr.collie/）です。

Omarchy

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

OmarchyにはtmuxとHerdrの両方が同梱されており、Collieはインストールごとに1つのマルチプレクサをミラーリングします。そのため、初回起動時には制御対象を指定する必要があります（検出された2つの間で自動判別は行われません）。startはその名前をCollieの.env（Herdr環境では~/.config/herdr/plugins/config/herdr.collie/.env）に書き込み、以降の起動はcollie startで行えます。

これはcollie-binがOmarchy自身のパッケージリポジトリに追加された後に機能します。現在、追加用のプルリクエストは未マージです。マージされるまでは、上記の通常のArch環境と同様にpackaging/aurからmakepkg -siを使用して同じパッケージをビルドしてください。

その後の更新は、マシンのアップデートに普段使用しているコマンドであるsudo pacman -Syuで行われます。pkgs.omarchy.orgは実際のpacmanリポジトリであるため、AURヘルパーは使用しません。どちらの方法でも、配置されるPKGBUILDおよび/opt/collieの構造は同じです。

注。 更新はパッケージマネージャーから行われ、Collieが自身を自動更新することはありません。collie updateは処理を拒否します。スマートフォンの更新通知バーには「Collie x.y.z available via pacman.」と表示され、パッケージマネージャーがディレクトリを管理しているため、Updatesページには更新ボタンの代わりにコピー用のコマンドが表示されます。Collieはリポジトリ向けの表記であるsudo pacman -Syu collie-bin形式を案内します。AURインストールの場合は代わりにAURヘルパーを実行してください。前述のとおりpacmanは再起動を行わないため、アップグレード後はcollie restartを実行してください。

pack内では、このマシンが電話から更新を受け取ることはありません。pack上では「waits for the package manager」と表示され、そのマシン上でヘルパーを実行したときにのみ更新が適用されます。

上記のArch環境と同じ3ステップで削除します。

Nix

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

このflakeは、x86_64-linux、aarch64-linux、aarch64-darwin向けにpackages.<system>.collieをエクスポートします。リリースの整合性マニフェストに記載されたsha256に基づいて各プラットフォーム向けのリリースタールボールを取得し、Linux上ではバイナリのインタープリタをパッチした上で、リリースツリーを<store-path>/lib/collieにインストールし、bin/collieへのシンボリックリンクを作成します。インストールせずに一度だけ実行するには、nix run github:AltanS/collie#collie -- doctorを使用します。

意図的にソースビルドは行っていません。依存関係のインストールにはネットワークアクセスが必要ですが、Nix derivation内ではネットワークが利用できないためです。そのため、パッケージはリリースですでに公開されチェックサム検証済みのバイナリをラップしています。

現時点ではNixOSモジュールは存在せず、flakeパッケージのみが提供されています。そのため、nix profileを使用してください。上記のようにプロファイルへインストールするか、flakeの出力をhome-managerまたはenvironment.systemPackagesのリストに手動で追加してください。

注。 更新はnix経由で提供されるため、この環境ではCollie自身による自己更新は行われません。collie updateは更新を拒否して代わりにnix profile upgrade collieを提示し、電話側では更新ボタンの代わりにそのコマンドとともに新しいバージョンが表示されます。

pack内では、このマシンが電話から更新を受け取ることはありません。pack上では「waits for the package manager」と表示され、そのマシン上でnixを実行したときにのみ更新が適用されます。

まずcollie stopで削除し、その後に以下を実行します。

nix profile remove collie

これによりプロファイルからストアパスのみが削除されます。~/.local/state/collie（または$COLLIE_STATE_DIR）内の状態、~/.config/collie内の設定、およびcollie startによって作成された~/.config/systemd/user/collie.serviceのsystemd --userユニットなど、ユーザー固有のファイルは残ります。パッケージを削除する前にcollie uninstallを実行して、ユニットとポートマッピングを削除してください。

mise

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

mise use -gはツールを~/.config/mise/config.tomlに書き込み、リリースのbin/をPATHに追加します。githubバックエンドがプラットフォーム用のリリースターボールを取得するため、BunやコンパイルなしでLinuxおよびmacOS上で動作します。web/distやherdr-plugin.tomlを含むツリー全体が~/.local/share/mise/installs/github-altan-s-collie/<version>/配下に配置され、collieはそこから自身のルートを解決します。

新しいバージョンに更新するには、同じmise useの記述で新しいタグを指定するか、miseに最新版を選択させます:

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

重要なのは--bumpフラグです。固定された1.5.6は範囲が1つに制限されるため、単にmise upgradeを実行しても最新と判定され、何も更新されません。

再起動は必須です。バージョンごとに独立したディレクトリが作成され、collie startは実行元のディレクトリをサービス定義に埋め込むため、再起動するまでサービスは古いディレクトリから古いバージョンを提供し続けます。collie restartを実行すると、Linuxではsystemd --userユニット、macOSでは~/Library/LaunchAgents plistの定義が新しいパスで書き直されます。どちらのOSでもコマンドは1つです。

注。 SSH経由でのみ管理されているMacには、エージェントを読み込むためのgui/<uid>ドメインが存在しません。その場合collie startはその旨を表示し、ログイン時の自動起動や障害時の自動再起動を行わない、監視なしのバックグラウンドブリッジとして起動します。collie restartを実行すれば、新しいディレクトリへの移行は問題なく行われます。

注。 ここではcollie updateが拒否され、パッケージマネージャー名は提示されずにcannot tell how this Collie was installedと表示されます。miseのツリーはホームディレクトリ内に配置され、独自の.gitを持たず、上位にversions/構造も存在しないため、Collieはこれをチェックアウトとしてもパッケージとしても認識しません。この環境での更新はmiseが担当するため、上記の2つのコマンドで更新を行います。

まずcollie uninstallで削除し、その後に以下を実行します。

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

uninstallはそのバージョンのディレクトリを削除し、unuseは設定から該当行を削除します。どちらのコマンドでも、ツール名は完全なgithub:名で指定してください。短いcollieはupgradeでは使用できますが、uninstallでは機能しません。独自ファイルは保持されます。対象は~/.local/state/collie（または$COLLIE_STATE_DIR）内の状態データと、~/.config/collie内の設定です。

PKGBUILD、Nix式、および関連ドキュメントは、このリポジトリのpackaging/に配置されています。macOS向けパッケージはまだ用意されていません。現時点ではaarch64-darwin flake出力が最も近い代替手段です。

マルチプレクサの指定

Collie は1つのバックエンドをミラーリングします: COLLIE_MUX=herdr（デフォルト）、tmux、または zellij。

注。 事前に設定しておく必要はありません。

初回起動時の start は、稼働中の Herdr ソケット、実行中の tmux サーバー、zellij セッションを検出し、検出結果を表示して、ユーザーの選択を設定ファイル .env に書き込んで新規作成します。プロンプトを表示する端末がない場合、検出された唯一のバックエンドを採用してその名前を表示します。バックエンドが検出されない場合や複数検出された場合は、起動を拒否して COLLIE_MUX を指定するよう求めます。

事前に指定したい場合は、初回起動前にそのファイルを作成します。単体構成の場合は ~/.config/collie/.env、または herdr plugin config-dir herdr.collie が出力するパスに作成します:

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

次にバックエンドとそのエンドポイントを設定します:

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

注意。 起動後にその cp を実行しないでください。起動処理によって書き込まれたばかりの COLLIE_MUX の上に .env.example を上書きしてしまいます。

その後、ファイルを編集します。Collieをマルチプレクサに向ける を参照してください。

起動する

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

start は以下の処理を行います:

1. 01
   存在しない場合は web/dist をビルドする。
2. 02
   systemd --user（または launchd/nohup）下でブリッジを起動する。
3. 03
   tailscale serve --bg 8787を実行します（HTTPS :443 → 127.0.0.1:8787）。これにはtailnetでHTTPSが有効になっている必要があります（admin console → 「Enable HTTPS」）。有効になっていない場合、Collieはその旨を表示して停止します。
4. 04
   接続バナーを表示する。

初回実行時の表示内容

bin/collie start からの出力（Herdr の実行結果は JSON を返します。ログの確認は 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

ヘルスチェックが失敗した場合（⚠ Collie isn't answering on :8787 yet）は、トラブルシューティング を参照してください。

stop はサービスを停止し、uninstall はサービスとプロキシを削除します。ブリッジは systemd --user サービス（macOS では launchd エージェント）として動作し、ログイン時に起動して障害発生時に再起動します（ARCHITECTURE.md §3）。Linux では loginctl enable-linger $USER によって再起動後も存続します（再起動後も維持する）。

設定 でユーザーアクセスを、ペアリング（bin/collie pair）でデバイスアクセスを設定します。

スマートフォンで開く

バナーに表示された tailnet URLを開きます（bin/collie url でいつでも再取得できるほか、bin/collie qr でQRコードを生成できます）。クライアントが同一のtailnet上にある必要があります。

1. 01
   デバイスをペアリングする: ホスト上でbin/collie pairを実行します。表示されたQRコードをスキャンすると、クライアントでコードが入力された状態で「Settings」→「Paired devices」が開きます。または、クライアントで「Settings」→「Paired devices」を開いてコードを入力します（デバイスをペアリングする）。
2. 02
   PWAをインストールする: Safari（iOS）または Chrome（Android）で ホーム画面に追加 をタップします。

PWA のインストールには HTTPS が必要です。COLLIE_SERVE_MODE=http では Service Worker が無効化されるため、このモードではスマートフォンからはブラウザタブでのみ利用できます。

正常に動作しているか確認する

ステータスとログを確認します:

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

アクセスを制限するには、.env 内で COLLIE_TRUSTED_USER=you@example.com を設定して bin/collie restart を実行します（設定）。ダッシュボードのコンテンツが表示されない場合は、トラブルシューティング を参照してください。

最新の状態に保つ

コマンド1つで現在のメジャーバージョンを更新します。

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

アップデートは現在のメジャーバージョンに適用されます。メジャーバージョンをまたぐ更新には collie update --major を実行するか、Herdr 管理下のインストールの場合は update-major アクションを使用します。これらやロールバック、アンインストールについては 管理とアップデート を参照してください。