設定

デフォルトで Collie はオープンなシングルユーザーモードで動作します。tailnet 内で URL にアクセスできるユーザー全員に完全な制御権が付与されます。これにより TRUSTED_USER 警告が表示されます。アクセスを制限する方法:

# 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 は ~/.config/collie 内の .env ファイルから設定を読み込みます。Herdr がインストール環境を管理している場合、CLI は Herdr にプラグイン設定ディレクトリ (通常は ~/.config/herdr/plugins/config/herdr.collie) を問い合わせます。どちらのパスも CLI コマンド間で一貫して解決されるため、サービスはここに配置されたファイルを読み込みます:

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"

以下のパス表記では ~/.config/collie/… を使用します。Herdr 管理下のインストール環境では、このプレフィックスを $(herdr plugin config-dir herdr.collie) に置き換えてください。

Collie が .env を読み込むのは起動時のみです。変更後は collie restart を実行してください。

すべてのオプションは .env.example ファイルに記載されています。

これには COLLIE_PORT、COLLIE_SERVE_MODE=http（Headscale または .internal ドメイン用）、および COLLIE_SERVE_PORT（:443 以外のポートで HTTPS を公開する場合。docs/deployment.md → 単一ホスト上での複数 Collie の実行 を参照）が含まれます。CLI はこれらの serve パラメータを bridge に渡すのではなく、tailscale serve の設定に使用します。

複数のエージェントのホームディレクトリから履歴を読み込むには、COLLIE_TRANSCRIPT_ROOT にカンマ区切りのリストを指定します。

docs/deployment.md はカスタムドメインとリバースプロキシに対応します。Collie は同一生成元ポリシー (SOP) を適用するため、カスタムホスト名や外部 TLS ターミネータは明示的に許可リストへ登録する必要があります:

COLLIE_ALLOWED_ORIGINS=https://collie.example.com

この設定がない場合、UI は空のページとして読み込まれます。詳細は トラブルシューティング を参照してください。

カスタムスラッシュコマンド

Herdr プラグインの /fork-in-herdr やカスタムの /deploy など、マシン固有のコマンドは commands.toml に記述してください。これは、同一のリーダーおよび読み込みパターンを共有する4つの設定ファイルの1つです。

フラグが設定された行は、実行前に2回タップして確認する必要があります。これらのファイルの変更は、サービスを再起動しなくても反映されます。Collie が行を拒否した場合、journalctl --user -u collie -n 20 に行番号とエラーが表示されます。

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"

設定した行に一致するペインには、その行のみが表示されます。ADR 0018 に記載されているとおり、最も一致範囲の狭い行が優先されます。

確認するには、ペインを開いて / をタップします。最初の画面に設定した行が表示されます。

カスタムキープリセット

commands.toml の隣にある keys.toml 内で、Keys トレイの Presets 行を置き換えることができます:

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

ペインが定義した行に一致する場合、デフォルトの Ctrl C/D/U/R/L/Z ボタン（ADR 0018）の代わりに、プリセットのみが表示されます。トレイのその他の部分（Esc、矢印キー、Enter/Tab/Space、修飾キー、数字、F1〜F12）は固定です。

和音（Chord）には tmux ではなく herdr の構文を使用します。

動作を確認するには、ペインを開いて Keys → Presets をタップし、新しいボタンを表示します。Collie が行を拒否した場合は、journalctl --user -u collie -n 20 でエラーの詳細を確認してください。

カスタムクイック返信

quick-replies.toml で Quick ドックのフレーズをカスタマイズできます:

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

ペインがルールに一致すると、デフォルトのグループ（ADR 0018）が独自の設定で置き換わります。デフォルトのフレーズは英語（yes、commit and push）です。

他の言語で実行する場合や、approve のような単語を特定のハーネスに送信する場合は、このファイルを使用します。scope = "shell" を設定すると標準のシェルペインが対象になります。設定しない場合、それらのペインは y/n のみを受信します。

動作を確認するには、ペインを開いて Quick をタップし、グループを表示します。行の読み込みに失敗した場合、journalctl --user -u collie -n 20 にエラーが出力されます。

独自のランチャー

1回タップするだけで、launchers.toml内の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

タップした項目がどこで開くかは、行の設定ではなくタップした場所によって決まります。ダッシュボード からタップすると、その行の名前が付いた新しい Space が作成されます。ペイン（上にスワイプして表示するスイッチャーシート）からタップすると、その横に新しい そのペイン独自のSpace内のタブ が開きます。

どちらの場合も、ブリッジは新しいシェルに command を入力して Enter を送信します。コマンドが自身のライフタイムを管理します。自身で終了するコマンドは Space またはタブも一緒に閉じ、htop は終了するまで残ります。

cwd は、その新しい Space またはタブが開く場所です。（上記の htop のように）固定すると、行をどこでタップしてもその場所が優先されます。

省略した場合は「現在地」を意味します。ダッシュボードではホームディレクトリで開き、ペインでは そのペイン自身の の cwd で開きます。cwd を指定しない行は、常に特定のディレクトリのルートで開くのではなく、チェックアウト先の移動に追従します。

このファイルは許可リストです。POST /api/launchはこのファイルの行と完全に一致するcommandのみを受け付けるため、ファイルに存在しない処理はスマートフォンから一切開始できません。変更は再起動なしで即座に適用されますが、すでに開いているタブは次回の読み込み時にのみ行を再読み込みします。

設定した行は2箇所に表示されます。ダッシュボードの 起動 セクション（Spaces や Recent と同様に折りたたみ可能）と、スイッチャーシート（ペインから上にスワイプ）の 起動 セクションです。固定された行には、ホームディレクトリ配下を短縮したフォルダーパスが表示されます。cwd のない行はスイッチャーで「here」と表示されます（ダッシュボードはすでにホームを前提としているため、そこには何も表示されません）。行を定義しない場合、どちらのセクションも表示されません。

pack（複数マシン構成で、スマートフォン側を向くリードが1台）では、各マシンがこのファイルの独自のコピーを読み込みます。行は、リード上ではなく、タップ元のダッシュボードまたはペインが存在するマシン上で起動します。

動作を確認するには、ダッシュボードをリロードして herd の下を確認します。行の読み込みに失敗した場合、journalctl --user -u collie -n 20 にエラーが出力されます。

カスタムフォント

インターフェースのフォントはデバイスごとの設定です。Settings → Typeface で、System、Space Grotesk (デフォルト)、Aldrich から選択できます。4番目の設定ファイルである theme.toml でカスタムフォントを追加できます:

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

カスタムフォントは、組み込みリストを置き換えるのではなく末尾に追加されます（ADR 0033）。これは commands.toml や他の設定ファイルの動作とは異なります。フォントはアクションをトリガーしないため、上書きして隠す対象が存在しません。

これらは3つのデフォルトエントリの下に表示され、クライアントデバイスごとに個別に選択します。

注意すべき3つの動作:

• —
  初回読み込み時のレイアウトシフト。 カスタムフォントにはメトリクスが一致するフォールバックがないため、初回読み込み時にわずかなレイアウトシフトが発生します。組み込みフォントはビルド時にフォールバックが生成されるため、この問題を回避できます。
• —
  コールドロード時の遅延。 コールドロード時はわずかな遅延を伴ってファイルを取得します。キャッシュ済みのクライアントは即座に描画します。
• —
  Chrome のみ。 選択したフォントは Collie の UI（chrome）にのみ適用されます。ターミナルミラー、トランスクリプト、レンダリングされた Markdown は独自のタイポグラフィを維持します。
• —
  次回リロード時に反映。 変更に再起動は不要で、次のページリロード時に反映されます。無効な設定はエラーをログに記録し、journalctl --user -u collie -n 20 で確認できます。

添付ファイル

メッセージボックス横のクリップアイコンを使うと、ファイルをホストにアップロードしてメッセージ内にそのパスを挿入します。

# 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 は所有者のみアクセス可能な権限でファイルを <state-dir>/uploads 配下に保存し、下書きにその絶対パスを追加します。ターミナルにはファイルを直接ペーストできないため、エージェントはこのパスからファイルを読み込みます。アップロードされたファイルは書き込みから48時間後に削除されます。

受け付けるファイル形式は2種類あり、それぞれ異なるチェックが行われます。

画像 はファイル名や宣言されたタイプではなく、シグネチャバイトによって識別されます: png、jpg、gif、webp。SVG は画像ではなくスクリプトを含むマークアップであるため、意図的に拒否されます。

テキスト は拡張子で識別され、バイト単位の検証によって拒否判定が行われます。先頭4 KBに NUL や不正な制御バイトが含まれるファイルは、拡張子にかかわらず拒否されます。標準で対応している拡張子は 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、patch です。

注。 COLLIE_UPLOAD_EXTRA_TYPES で追加できるのはテキスト形式のみです。画像には検証用のシグネチャが必要なため、この方法で追加できるバイナリ形式はありません。

COLLIE_MAX_UPLOAD_MB の値を引き上げると、連動して他の2つの数値も増加します。ブリッジはサイズを判定する前にアップロード全体をメモリに読み込むため、上限を大きくして複数同時にアップロードすると、その分メモリを消費します。また、ランタイムのボディサイズ制限はアップロードだけでなく全ルートに適用されるため、上限を大きくすると大きなボディが他のハンドラーにも到達し、そのハンドラー固有の制限で拒否されることになります。ファイルは48時間経過するまで削除されないため、アップロードディレクトリには最大で2日分の送信データが保持されます。この値は安易に引き上げず、必要な場合にのみ変更してください。

pack では両方の設定がマシンごとに適用され、ファイルを保存するマシンがその設定を強制します。リードはアップリンクを節約するため転送前にサイズ超過のボディを拒否しますが、判定にはリード自身の数値を使用します。全メンバーで同じ値を設定してください。設定が異なると、リードを通過したリクエストがピアで拒否される原因になります。

マルチセッション

デフォルトでは、1つの Collie インスタンスが検出したすべての Herdr セッションを提供します。

COLLIE_MULTI_SESSION=on (デフォルト) は、設定ルート配下にある名前付き Herdr セッションをすべて検出して提供し、ヘッダーから切り替え可能にします。COLLIE_MULTI_SESSION=off を設定すると、プライマリセッションのみが提供されます。検出されたすべてのセッションは、プライベートセッションやサンドボックスセッションを含め、同一の URL からアクセス可能です。セキュリティ では、この動作を注意点として挙げています。

ダークモード / ライトモード

注。 Collie はデフォルトでスマートフォンの外観設定に追従します。

固定するには、Settings → Appearance を開いて System、Light、または Dark を選択します。この設定はブリッジ上ではなくブラウザの デバイスごと に保存されます。ノート PC で OS 設定を追従させながら、スマートフォンは Dark のままにできます。設定内容はリロードしても、同一デバイスでの PWA 再インストール後も保持されます。

ターミナルミラーの意図的な仕様差

ミラーは常に ダーク背景 上に描画されます。ライトモードでは、個々の span の色を再設定するのではなく、要素全体を反転します。

エージェントはダーク背景向けに調整された絶対24ビットカラーコード（38;2;r;g;b）を出力するため、後続のパーサーで確実に再マッピングすることはできません。白の上に直接描画すると、ほとんどのエージェント出力でコントラスト比が3:1未満に低下します。反転処理により、意図したコントラストが維持されます。測定結果は ADR 0002 に記載されています。

この実装には実用上 2 つの影響があります。

• —
  エージェントの設定はダークテーマのまま維持してください。 Claude Code、codex、opencode、pi ではこれがデフォルトです。エージェントが ライト テーマを使用している場合、白地に黒系の値が出力され、Collie ではどちらのモードでも視認できなくなります。これは Collie 側ではなくエージェント側の出力に起因します。
• —
  ライトモードでは 差分やハイライトされた行が暗いブロックとして描画される。コントラストは維持されますが、視覚的な重みは反転します。

注。 iOSにインストールした状態でライトモードを使用すると、ステータスバーのテキストが白のままになり、背景に溶け込む場合があります。iOSはWebアプリによるこの値の動的更新を許可していません。この制限を回避するには、インストールしたPWAではなく、ブラウザで直接Collieを実行してください。

Zen モード

注。 Zenモードはデフォルトで無効です。

Settings → Zen mode で有効にします（設定はブラウザのデバイスごとに保存されます）。有効にすると、FindとHistoryの横にある⋮のペインメニューに Zen モード オプションが追加されます。これをタップすると、ヘッダー、タブやペインのストリップ、エージェントステータスライン、コンポーザードックなど、CollieのUI要素がすべて非表示になります。ターミナルミラーのみが表示された状態になります。右上のフローティングボタンまたはEscapeキーでUIを復元できます。

Zenモードは 一時的な状態 です。設定内容は保持されますが、ペインを切り替えたりページを再読み込みしたりするとアクティブ状態はリセットされます。ペインは常に標準のchromeで開きます。

ターミナルミラーはZenモードでもポーリングを継続し、インタラクティブなバッファ要素も引き続き機能します。プロンプトボタン、「Load older」、「Show entire history」などのコントロールは、chromeではなくコンテンツストリームの一部であるため、そのまま利用できます。

言語

Collieのインターフェースは6言語で利用できます。Settings → Language で設定してください。

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

選択内容はデバイスごとにブラウザのローカルへ保存されます。ターミナルミラーは翻訳されず、エージェントからの生の出力が表示されます。クイック返信、メニューラベル、キーキャップは、元の画面やキーボードの名前に一致します。