Chorus デーモンを運用する

フォアグラウンドのデーモン接続を確認した後に、このガイドを使ってください。コマンドは、対応する常駐バックエンド（Claude Code、Codex、Kiro、Pi）に適用されます。

Hermes は Chorus daemon ではなく自前のゲートウェイでオンラインを維持します。コメント承認と中断・再開に対応しますが、調査とアイデア作成の専用操作ターンは実行しません。

デーモンバックエンドを 0.20.0 に更新する

更新コマンドで Chorus CLI を更新し、進行中の作業に支障のないタイミングでデーモンを再起動します。ホスト CLI は別途更新してください。デーモンが最初に作業を起動する前に、バックエンドごとの要件を確認します。

Codex App Server：codex-cli 0.157.1 で検証済み。デーモンの args はモデル指定と許可された設定だけに対応します。--chorus-only では、必要な MCP ツールの許可を Codex 設定で確認してください。
Claude Code stream-json：Claude Code 2.1.283 と 2.1.284 で検証済み。中断はまずプロトコル経由で行い、バックグラウンドでの質問には Chorus のコメントか要件詳細化を使います。
Pi RPC：Pi 0.85.0 以降が必要です（0.85.1 で検証済み）。--plugins は Chorus のパッケージを更新しますが、Pi 本体は更新しません。

デーモンがアクセスできる範囲を選ぶ

各 --cwd は、一つの作業ディレクトリを Chorus 上の別々のターゲットとして登録します。

chorus daemon \
  --agent claude-code \
  --cwd ~/work/project-a \
  --cwd ~/work/project-b \
  --chorus-only

--cwd がないと、Chorus はコマンドを起動したディレクトリを使います。繰り返し指定できる --browse-root オプションは、ユーザーがより広いルート配下からディレクトリを選ぶ必要があるときにだけ使ってください。browse root は探索を許可するだけで、すべてのディレクトリをオンライン接続として登録するわけではありません。

プロジェクトのエージェントの作業ディレクトリを固定するとき、そのパスはこのデーモンが提供するものでなければなりません。このデーモンの cwds の集合に含めて、固定したディレクトリがオンライン接続と対応づけられるようにしてください。

`daemon.json` を構成する

デーモンは設定を ~/.chorus/daemon.json から読み込みます。一般的な単一エージェントの構成では、エージェントの認証情報とランタイムのオプションをまとめて保持する、フラットな JSON オブジェクト 1 つです。1 つのデーモンで複数のエージェントを動かす場合は、代わりにそれらを agents 配列に列挙します（1 つのデーモンで複数のエージェントを動かすを参照）。どちらの形式でも、ファイルは 0600（所有者のみ読み書き可）でアトミックに書き込まれるため、書き込み途中でクラッシュしても中途半端なファイルが残ることはありません。CHORUS_DAEMON_CONFIG_PATH で別のファイルを指定できます。その場合は CLI とデーモンサービスの両方に同じ値を設定してください。シェルで export しても、実行中のサービスには反映されません。

フィールド

フィールド	型	意味
`url`	string	Chorus サーバーの URL。
`apiKey`	string	エージェントの API キー（`cho_…`）。
`agentUuid`	string	認証済みエージェントの UUID（参考情報）。
`agentName`	string	認証済みエージェントの名前（参考情報）。
`cwds`	string[]	このデーモンが提供する作業ディレクトリ。各パスは一つの独立したオンライン接続です。
`browseRoots`	string[]	リモートの作業ディレクトリ探索に公開するルート。browse root は接続を作りません。
`agent`	string	起動するローカルバックエンド：`"claude-code"`、`"codex"`、`"kiro"`、`"pi"`、`"dsh"`。
`sigintTimeoutMs`	number	中断から強制終了までの猶予（ミリ秒）。Claude Code、Codex、Pi はまずプロトコルで中断します。既定値 `10000`。
`agents`	object[]	任意。 1 つのデーモンで複数の独立したエージェントを動かします。各エントリは共有ランタイムの既定値を上書きできますが、`args` と `env` は継承されません。1 つのデーモンで複数のエージェントを動かすを参照。

chorus login と chorus daemon install を実行した後の最小構成のファイルは次のとおりです。

{
  "url": "https://chorus.example.com",
  "apiKey": "cho_REDACTED",
  "agentUuid": "8a1c…",
  "agentName": "Build Agent",
  "cwds": ["/home/demo/work/project-a"],
  "browseRoots": ["/home/demo/work"],
  "agent": "claude-code",
  "sigintTimeoutMs": 10000
}

ファイルはどう作られるか

通常、このファイルは chorus agents add で最初に作成されます。設定された各エージェントの認証情報を検証し、agents 配列のエントリとして書き込みます。エージェントランタイムを接続するを参照してください。
chorus login は URL とキーを検証してから、単一のフラットなエージェントとして url、apiKey、agentUuid、agentName を書き込みます。
chorus daemon install はさらに cwds、browseRoots、agent を書き込みます（これらがまだ設定されていない場合は、提供するディレクトリとバックエンドを尋ねます）。
端末で初めて chorus daemon を実行すると、欠けている認証情報を対話的に補完して書き込みます。

ファイルはどう更新されるか

どのコマンドが書き込む場合も浅いマージを行います。新しいフィールドは、ディスク上の既存の内容の上にマージされ、無関係なフィールドは保持されます。chorus login を再実行すると、cwds、agent、sigintTimeoutMs を消さずに認証情報だけを更新します。chorus daemon install を再実行すると、認証情報を捨てずに提供するディレクトリの一覧を更新します。ファイルが欠けているか壊れている場合は空のオブジェクトとして扱われるため、再ログインは失敗せず常に有効なファイルを生成します。

フィールド、フラグ、環境変数

以下のランタイムオプションは三通りの方法で指定できます。優先順位はフラグ、次に環境変数、最後に daemon.json なので、一度きりのフラグや環境変数による上書きをファイルに書く必要はありません。

対象	`daemon.json` のフィールド	CLI フラグ	環境変数
サーバー URL	`url`	`--url`	`CHORUS_URL`
API キー	`apiKey`	`--api-key`	`CHORUS_API_KEY`
作業ディレクトリ	`cwds`	`--cwd`（繰り返し可）	`CHORUS_DAEMON_CWDS`
browse root	`browseRoots`	`--browse-root`（繰り返し可）	`CHORUS_DAEMON_BROWSE_ROOTS`
バックエンド	`agent`	`--agent`	`CHORUS_AGENT`
SIGINT 猶予	`sigintTimeoutMs`	`--sigint-timeout`	`CHORUS_DAEMON_SIGINT_TIMEOUT`
権限モード	(永続化されない)	`--yolo` / `--chorus-only`	`CHORUS_YOLO` / `CHORUS_CHORUS_ONLY`

権限モードは意図的に daemon.json に保存されません。起動時に --chorus-only を渡すか、CHORUS_CHORUS_ONLY=1 を設定してください。インストールされたサービスでは、--chorus-only はファイルではなくユニットに記録されます。

1 つのデーモンで複数のエージェントを動かす

1 つの chorus daemon プロセスは、複数の完全に独立したエージェントを同時に動かすことができます。ペルソナ、権限、アカウント、さらにはバックエンドが異なっていてもかまいません。エージェントごとに別々のデーモンを動かす必要はありません。代わりに、各エージェントを agents 配列に列挙します。各エントリが 1 つのエージェントです。

{
  "url": "https://chorus.example.com",
  "sigintTimeoutMs": 8000,
  "agents": [
    { "apiKey": "cho_alpha", "agentType": "claude-code", "cwds": ["/home/demo/project-a"] },
    { "apiKey": "cho_beta", "agentType": "kiro", "cwds": ["/home/demo/project-b"], "permissionMode": "chorus" }
  ]
}

url や sigintTimeoutMs などの共有ランタイム設定が既定値になり、エージェント自身の値で上書きできます。args と env はエージェント専用で、共有の既定値ではありません。各エージェントは、それぞれ固有のアイデンティティ（キーで決まる）、接続（cwds ごとに 1 つ）、起動キュー、バックエンドを持ちます。そのため、各エージェントは独立して起動・実行され、あるエージェントの失敗が他のエージェントを妨げることはありません。サーバー上では、各エージェントはエージェント・ホスト・ディレクトリの組み合わせごとに、設定 → エージェント（Settings → Agents）に独立した接続として表示されます。エージェントは同じ作業ディレクトリを共有することもできますが、デーモンはそれらを直列化しないため、1 つの git ツリー内で衝突する作業を並行して行うのは避けてください（別々のブランチや worktree を使ってください）。

エージェントごとのフィールド

フィールド	意味
`apiKey`（必須）	エージェントの `cho_` キー。そのアイデンティティを決めます。
`url`	Chorus サーバー（エージェントごとに異なってよい。別のサーバーやワークスペース）。
`agentType`	`claude-code`、`codex`、`kiro`、`pi`（バックエンドは混在可）。
`cwds`	このエージェントが提供する作業ディレクトリ（それぞれ 1 接続）。
`permissionMode`	`yolo` または `chorus`。
`maxConcurrency`	このエージェント自身の起動同時実行数の上限（既定値 `4`）。
`sigintTimeoutMs`	中断から強制終了までの猶予（ミリ秒）。
`browseRoots`	ディレクトリ探索の許可リスト。
`args`	バックエンド CLI に渡す追加引数の文字列配列（任意）。既定値 `[]`。エージェントのモデル、思考レベル、環境変数を設定するを参照。
`env`	環境変数名を文字列値に対応付けるオブジェクト（任意）。既定値 `{}`。

エージェントのモデル、思考レベル、環境変数を設定する

~/.chorus/daemon.json の対象エントリにフィールドを追加します。この Pi の例はダミーの認証情報と機密でない環境変数値を使っています。URL、キー、モデルを環境に合わせて置き換え、他のエージェントを消さずに既存ファイルへマージしてください。

{
  "url": "https://chorus.example.com",
  "agents": [
    {
      "agentName": "pi-worker",
      "apiKey": "cho_REDACTED",
      "agentType": "pi",
      "args": ["--model", "anthropic/claude-sonnet-4-6", "--thinking", "high"],
      "env": { "PROVIDER_REGION": "us-east-1" }
    }
  ]
}

モデルは例であり、Chorus の既定値ではありません。バックエンドが対応するフラグと値を使ってください。独立した model や thinking フィールドはありません。デーモンによる起動と chorus agents run --name pi-worker の両方がこのエントリを使います。offline エージェントは引き続きデーモンから起動されません。

グローバル設定は継承しません：空でない agents 配列がある場合、トップレベルの args や env はエラーになります。必要な各エントリへ移してください。他のエージェントやシェルには影響しません。
値はそのまま渡されます：args の各要素が 1 つの引数です。シェル用の引用符を追加しないでください。$HOME、${TOKEN}、シェルコマンドは展開されません。Chorus は dotenv 読み込み、変数展開、シークレット検索、env 値の特別な処理を追加しません。env は子プロセスが継承した環境を上書きしますが、Chorus が管理する制御項目が優先されます。環境変数名は Windows では大文字小文字を区別せず、POSIX では区別します。
検証：null、文字列以外の引数や値、NUL 文字、[A-Za-z_][A-Za-z0-9_]* に合わない変数名は起動前に拒否されます。空文字列の値は有効です。位置引数のプロンプトやサブコマンドではなく、オプションを指定してください。未知のオプションには、バックエンドが対応していれば "--future=value" を使います。"--future", "value" は曖昧なため拒否されます。
保護された制御項目：永続引数では、既知のセッション/再開、プロンプト、通信/出力、作業ディレクトリ、管理対象 MCP、権限制御を変更できません。ヘルプやバージョンなど、情報を表示して終了するだけのオプションや、単独の --、標準入力マーカー - も禁止です。CHORUS_* 環境変数名と、ネストした Claude コンテキストの CLAUDECODE / CLAUDE_CODE_ENTRYPOINT は大小文字を問わず予約済みです。設定すると、黙って削除されるのではなくエラーになります。専用の Chorus 設定か、明示的なフォアグラウンド引数を使ってください。
Windows コマンドラッパー：.cmd/.bat 経由では、設定された空の引数や、空白・引用符・コマンドのメタ文字を含む引数は拒否されます。それらの値にはネイティブ実行ファイルを使ってください。ラッパー経由の明示的なフォアグラウンド引数には、シェル上の安全性の保証はありません。

env には平文のプロバイダー認証情報を保存できます。ファイルを保護し（POSIX では chmod 600 ~/.chorus/daemon.json）、シークレットをコミットしないでください。Chorus の検証・起動メッセージには設定値を出しませんが、子プログラムや OS の検査で露出する可能性があります。暗号化や保管庫の機能はありません。CODEX_HOME や PI_CODING_AGENT_DIR などを変更する場合は、そのディレクトリにも Chorus 連携を設定してください。

変更を反映する：chorus daemon restart を実行します。デーモンは起動時に設定を読み込み、エージェントを起動するたびには読み直しません。ファイルを編集しても実行中の子プロセスは変わらず、再起動までは次の起動にも旧設定が使われます。新しい chorus agents run は毎回設定を読み直しますが、実行中の子プロセスには影響しません。args/env を削除するとカスタマイズ前の動作に戻ります。

従来のフラットなファイル：空でない agents 配列がなければ、トップレベルの args/env は唯一のデーモンエージェントに適用されます。フォアグラウンドの選択には agents[] が必要です。設定をエントリ単位で管理するには、フラットな URL、キー、識別情報、args、env をエントリへ移し、agent を agentType に改名します。chorus agents add または chorus login --add による追加でも、既存のフラットな認証プロファイルと args/env が agents[0] へ移り、対応するトップレベルのキーが削除されます。キーのない不完全なプロファイルは、先に補完するか手動で変換してください。

一度きりの上書きとサブコマンドの詳細は CLI リファレンスを参照してください。

もう 1 つのエージェントを追加する

chorus login --add は新しいキーを検証し、別のエージェントとして追加します。フラットなファイルで初めて --add を使うと、既存の認証情報を agents[0] に移し、新しいキーを agents[1] として追加します。重複するキーは拒否され、既存のエージェントが上書きされることはありません。
chorus daemon install --add はインストールウィザードをループさせ、一度の実行で複数のエージェントを追加できます（端末のみ）。
~/.chorus/daemon.json の 手動編集 も常にサポートされています。

ファイルを編集したらデーモンを再起動し（chorus daemon restart）、設定 → エージェント（Settings → Agents）で各エージェントが表示されることを確認してください。

各バックエンドはどのように自分のキーを受け取るか

各エージェントは自分のキーで認証しますが、そのキーが起動されたサブプロセスにどのように届くかはバックエンドによって異なります。

Claude Code — 自動です。デーモンは起動ごとに、そのエージェントの URL とキーを含む MCP 設定を書き出します。設定は不要です。
Kiro — 環境変数を通じて自動です。インストールされた mcp.json は ${CHORUS_URL} と ${env:CHORUS_API_KEY} を参照し、デーモンが起動ごとにそれらをエクスポートするため、各 Kiro エージェントは自分のキーで認証します。
Codex — 環境変数を通じて自動です。chorus agents add は、キーを設定ファイルに埋め込まずに Codex を設定します。CHORUS_URL / CHORUS_API_KEY / CHORUS_AGENT_PROFILE を ~/.codex/.env（Codex が起動時に読み込む）に書き込み、config.toml に bearer_token_env_var = "CHORUS_API_KEY" を設定するため、Codex はファイルからではなく環境変数からキーを読みます。デーモンは起動ごとに各エージェント自身のキーを注入するため、1 つのデーモン内の複数の Codex エージェントがそれぞれ自分自身として認証します。
Pi — 環境変数を通じて自動です。デーモンは起動ごとに各エージェント自身の CHORUS_URL / CHORUS_API_KEY / CHORUS_AGENT_PROFILE を、起動された Pi セッションにエクスポートし、chorus-pi 拡張がそれらを読み取るため、各 Pi エージェントは自分のキーで認証します。

Linux サービスをインストールする

Linux では、確認済みの構成をユーザーサービスとしてインストールします。

chorus daemon install \
  --agent claude-code \
  --cwd ~/work/project-a \
  --chorus-only

インストーラーはサービスを直ちに起動し、ユーザーがログインしたときに開始するよう設定します。サービスが保存済みの認証情報を読めるように、先に chorus agents add（または chorus login）を実行してください。chorus agents add に --daemon-autostart を渡せば、同じ手順でこのサービスもインストールできます。

起動されるエージェントに必要な認証情報を渡す

デーモンは Chorus 接続（CHORUS_URL、CHORUS_API_KEY、CHORUS_AGENT_PROFILE）を提供しますが、モデルプロバイダーの認証情報は提供しません。バックエンドがプロバイダー認証情報を環境変数から読む場合は、そのエージェントの env か、デーモンが継承する環境で指定します。systemd --user サービスはログインシェルのエクスポートを継承しません。サービス経由で渡すには、ドロップインに設定して再起動してください。

[Service]
Environment=EXAMPLE_PROVIDER_API_KEY=…

systemctl --user daemon-reload && systemctl --user restart chorus-daemon

プロバイダー認証をファイルから読み取るバックエンド（例えば ~/.claude / ~/.codex の Claude Code や Codex）は、デーモンの HOME が正しく設定されていればよく、インストールされたユニットが既にそれを行っています。

日常の運用には次のコマンドを使います。

chorus daemon status
chorus daemon logs
chorus daemon restart
chorus daemon stop
chorus daemon uninstall

認証情報、作業ディレクトリ、バックエンド、権限モードを変更した後は、サービスを再インストールまたは再起動し、設定 → エージェント（Settings → Agents）で接続を確認してください。

ログアウト後も Linux デーモンを動かす

Chorus 0.21.0 以降の chorus daemon install は現在のユーザーの systemd lingering を有効にしようとします。最後のログアウト後もユーザーサービスを維持し、ログインなしで起動時に開始するためです。認可は非対話型で時間制限があり、パスワード画面を待ちません。

認可が拒否された場合や logind が利用できない場合でも、サービスのインストールは成功し得ますが、ログアウト後や起動時の継続を保証できないと警告します。chorus daemon status で linger: yes を確認します。ホストの方針で許可される場合、表示された sudo loginctl enable-linger <user> を管理者に実行してもらってください。

既存ホストは chorus daemon install の再実行で修復できます。chorus agents add もサービスのインストール時や既存サービスの検出時に確認し、--daemon-autostart がない場合や自動起動を断った場合も対象です。どちらも --no-linger で試行を省略できますが、既存設定を無効にはしません。lingering がなければログアウト後に停止し、次のログインまで起動しないことがあります。他のユーザーサービスが必要とする可能性があるため、Chorus サービスのアンインストールでも lingering は維持されます。

サービスなしで実行する

一時的な接続なら、chorus daemon をフォアグラウンドで実行したままにします。デタッチモードも使えます。

chorus daemon -d --agent codex --cwd ~/work/project-a --chorus-only

同じ status、logs、restart、stop のコマンドで管理します。デタッチモードを、別途用意したプロセススーパーバイザーと組み合わせないでください。

運用状態を確認する

コマンドラインと Web の両方で状態を確認します。

chorus daemon status を実行します。
chorus daemon logs で直近の出力を確認します。
設定 → エージェント（Settings → Agents）で、期待する各作業ディレクトリがオンライン（Online）であることを確認します。
小さなテストセッションを開始し、意図したディレクトリを対象にしていることを確認します。

ログにはパス、プロンプト、コマンドの出力が含まれることがあります。共有する前に機微な値を削除してください。失敗した場合はエージェント接続のトラブルシューティングへ進んでください。

Claude のバックグラウンド待機上限（0.22.0）

Claude の daemon 実行は、未完了の子エージェントを主ターン終了後に既定で 60 分待機します。これはターン後の待機上限であり、実行全体の制限や中断後の猶予時間ではありません。対話型 Claude セッションは変わりません。Chorus CLI と Claude プラグインを更新し、daemon を再起動してください。

CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS: Claude のネイティブ値。明示された場合は 0 や空文字列も含めてそのまま渡し、最優先します。
CHORUS_CLAUDE_BG_WAIT_CEILING_MS: ネイティブ変数が存在しない場合のみ使用。ミリ秒単位の非負の安全な整数で、前後の空白は除去します。
既定値: ネイティブ変数がなく Chorus 値が未設定または無効なら 3600000 ms（60 分）。空でない無効な Chorus 値は警告し、空文字列や空白のみなら既定値を使います。

優先順位はネイティブ → Chorus → 3600000です。明示的な 0 は無期限待機を要求するため、停止した子によって実行が終わらなくなる可能性があります。空のネイティブ値もそのまま渡されるので、既定値を要求するために使わないでください。Claude が未設定として自身の短い上限に戻す可能性があります。 Chorus の値を使うにはネイティブ変数を完全に削除します。ネイティブ値の検証と解釈は Claude が行います。

~/.chorus/daemon.json の対象エージェントの env に設定します。

{
  "env": {
    "CHORUS_CLAUDE_BG_WAIT_CEILING_MS": "3600000"
  }
}

daemon サービスの環境にも設定できます。ログインシェルの export は実行中のサービスに届きません。 chorus daemon restart で再起動し、継承したネイティブ値が優先されていないか確認します。

親は子の完了結果を集めるか明示的に停止してからターンを終了する必要があります。上限の延長はこの責任の代わりになりません。Claude が Background tasks still running after …s; terminating. と報告した場合、実際の終了コードがゼロでも異常として記録し、起点のアイデアやタスクに説明コメントを投稿しようとします。明示的な中断・終了はクラッシュではなく中断のままです。タスク状態の自動修復や新たな自動再試行はありません。再開前に途中結果を確認してください。コメント投稿に失敗しても実行の診断にはエラーが残ります。

バックエンドの制限を混同しないでください。 CHORUS_DSH_TIMEOUT_MS は dsh 実行全体を制限し、既定は 1800000 ms（30 分）です。正の安全な整数を受け付け、0 や無効な値は無期限ではなく既定値に戻ります。Claude のターン後待機設定は Codex、Pi、Kiro、Hermes には適用されません。他のランタイムの子エージェントの寿命を Claude の挙動から推測しないでください。