設定リファレンス
kanade サービスは、TOML ファイル、環境変数、またはレジストリパスから読み込まれる構造化された設定に依存しています。
1. エージェント設定
エージェントは KANADE_AGENT_CONFIG 環境変数を介して設定を検索し、存在しない場合はネイティブパスにフォールバックします。
開発用設定 (configs/agent.dev.toml)
# 開発用設定スキーマ
[agent]
id = "dev-pc"
nats_url = "nats://localhost:4223"
data_dir = "target/dev-data/agent"
[log]
level = "debug"
file = "target/dev-data/agent/logs/agent.log"
設定パラメータ
| フィールド | 型 | 説明 | 環境変数による上書き |
|---|---|---|---|
agent.id | String | ユニークなハードウェア識別子 (pc_id)。 | KANADE_DEV_AGENT_ID (テンプレート化) |
agent.nats_url | String | NATS ブローカー of ネットワークアドレス。 | KANADE_NATS_URL |
agent.data_dir | Path | 送信トレイのスクリプト、状態データベース、およびローカルの補完データをキャッシュするルートパス。 | KANADE_AGENT_DATA_DIR |
log.level | String | ログ出力レベルの冗長度 (error, warn, info, debug, trace)。 | RUST_LOG |
log.file | Path | ローリングログの書き出し先ファイルパス。 | - |
Per-PC job concurrency
max_local_concurrent lives in the layered agent_config store, not the agent TOML file. It applies to backend schedules, agent-local schedules, and operator runs from the CLI or administration SPA. One agent shares a single budget across these paths. User-triggered kanade-client actions are exempt: they start without waiting for or consuming a slot. They do not interrupt jobs already running.
When no scope sets the limit, the agent uses its locally available logical CPU count (falling back to 1 if detection fails). The backend leaves this automatic value as null; it never substitutes the backend host's CPU count. An explicit limit must be an integer of at least 1. Scopes apply in order: built-in automatic default → global → groups → PC.
kanade config set max_local_concurrent=4
kanade config set --group low-power max_local_concurrent=2
kanade config set --pc EXACT-HOSTNAME max_local_concurrent=1
kanade config unset --pc EXACT-HOSTNAME max_local_concurrent
kanade config (get, set, unset, clear, effective) talks to the backend HTTP API, not to NATS: it needs KANADE_AUTH_TOKEN (an operator-role token to change anything, like the other HTTP subcommands) and no broker token. Automation that calls kanade config must therefore authenticate with an auth token. The backend does each set / unset as a compare-and-swap on that one field, so a concurrent rollout writing target_version on the same scope is not overwritten, and a request that would change nothing writes nothing. Each change is recorded in the audit log under the caller's account; the audit entry is published after the write and is best-effort, not atomic with it. effective prints the backend's resolved view; its warnings are the backend's rendered text.
unset restores inheritance; when all applicable scopes omit the field, CPU-based sizing resumes. Updates apply without restarting the agent. Reducing the limit lets existing jobs finish and holds new jobs until enough slots are free. A job keeps its slot through retries, collection and finalize. Jitter happens before admission. Queued jobs can be killed and are skipped if their starting deadline expires. Waiting does not consume the script timeout or emit a running lifecycle event. Execution gates (version pin, revocation, staleness and deadline) are checked before jitter and again after admission.
Compatibility note: runs_on: agent schedules previously omitted their starting deadline from local commands. They now enforce starting_deadline from the local fire time, including jitter and slot waiting. Existing schedules whose jitter exceeds that deadline can therefore report a deadline skip even with a free slot. Keep the deadline longer than the maximum jitter plus the acceptable queue wait, or omit it when late execution is acceptable. Kill delivery is best effort: if the broker subscription fails, the agent logs a warning and continues waiting under the same capacity and deadline rules.
A critical job can opt out for every execution of that manifest:
execute:
shell: powershell
script: 'Write-Output "critical action"'
timeout: 30s
bypass_local_limit: true
Exempt jobs consume no slots, so total host concurrency can exceed the limit. The budget is agent-process-wide; it assumes one agent service per PC. constraints.max_concurrent remains a separate backend, fleet-wide per-job limit. This setting does not fix its jitter accounting issue (#1373).
2. バックエンド設定
バックエンドの調整レイヤーは KANADE_BACKEND_CONFIG で指定されたファイルから設定を取得し、指定がない場合はデフォルトの構造体を登録します。
開発用設定 (configs/backend.dev.toml)
[backend]
listen_addr = "127.0.0.1:8081"
nats_url = "nats://localhost:4223"
database_url = "sqlite://target/dev-data/backend/state.db"
[auth]
# 認証設定
設定パラメータ
| フィールド | 型 | 説明 | 環境変数による上書き |
|---|---|---|---|
backend.listen_addr | String | HTTP/WebSocket トラフィック用のネットワークバインド文字列。 | KANADE_BIND_ADDR |
backend.nats_url | String | 対象とする NATS ブローカーの URL。 | KANADE_NATS_URL |
backend.database_url | String | SQLite データベースへの接続文字列。 | DATABASE_URL |
auth.disable | Boolean | オペレーターのトークン検証を無効にするには true を設定します (開発環境でのみ有効)。 | KANADE_AUTH_DISABLE |
3. Windows レジストリ統合
本番環境では、セキュリティに敏感なトークン（NATS クライアントトークンや管理用 API ベアラートークンなど）は、プレーンテキストファイルではなく、保護された Windows レジストリに保存されます。
キーパス
- エージェント設定:
HKLM:\SOFTWARE\Kanade\agent - バックエンド設定:
HKLM:\SOFTWARE\Kanade\backend
これらのレジストリパスはローカルの ACL 設定で保護されており、SYSTEM および指定されたオペレーターにのみ読み取り権限が厳密に制限されます。