設定リファレンス
kanade サービスは、TOML ファイル、環境変数、またはレジストリパスから読み込まれる構造化された設定に依存しています。
1. エージェント設定
両サービスの設定探索順は --config <path>、空でない KANADE_AGENT_CONFIG / KANADE_BACKEND_CONFIG、存在する標準ファイルの順です(Windows は %ProgramData%\Kanade\config\agent.toml / backend.toml、Unix は /etc/kanade/agent.toml / backend.toml)。作業ディレクトリへの fallback や既定設定の自動生成はなく、設定がなければエラーです。TOML は teravars テンプレートなので、環境変数が項目を変えるのはテンプレートが明示的に参照した場合のみです。
開発用設定 (configs/agent.dev.toml)
[vars]
hostname = '{{ system.host }}'
pc_id = '{{ env(name="KANADE_DEV_AGENT_ID", default=vars.hostname) }}'
[agent]
id = '{{ vars.pc_id }}'
nats_url = 'nats://127.0.0.1:4223'
[log]
path = './target/dev-data/agents/{{ vars.pc_id }}/agent.log'
level = 'info'
設定パラメータ
| フィールド | 型 | 説明 |
|---|---|---|
agent.id | String | 大文字小文字を区別する正確なホスト識別子 (pc_id) です。ハードウェア UUID ではありません。開発テンプレートは KANADE_DEV_AGENT_ID を受け付けます。 |
agent.nats_url | String | ブローカーのアドレス。KANADE_NATS_URL は CLI の --server を指定するもので、このサービス設定項目を上書きしません。 |
log.level | String | ログフィルター。RUST_LOG が上書きします。 |
log.path | Path | 日次ローテーションするログの出力先。 |
log.keep_days | 整数 | 当日を含む日次ファイルの保持数。既定は 14、0 はファイルへのログ出力を無効にします。 |
データディレクトリは TOML の項目ではありません。KANADE_AGENT_DATA_DIR が Windows の %ProgramData%\Kanade\data または Unix の /var/lib/kanade を上書きします。Linux / macOS の setup スクリプトは明示的に /var/lib/kanade-agent を使います。
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. バックエンド設定
バックエンドも上記と同じ探索順です。開発時は --config configs/backend.dev.toml を渡すか、cargo make backend-dev を使ってください。
開発用設定 (configs/backend.dev.toml)
[server]
bind = '127.0.0.1:8081'
[nats]
url = 'nats://127.0.0.1:4223'
[db]
sqlite_path = './target/dev-data/backend.db'
[log]
path = './target/dev-data/backend.log'
level = 'info'
設定パラメータ
| フィールド | 型 | 説明 |
|---|---|---|
server.bind | String | HTTP / WebSocket の待受アドレス。 |
server.public_url | 任意の文字列 | アカウントメール用の公開 SPA ベース URL。プロキシ経由の場合やリクエストヘッダー由来のリンク生成を避ける場合に設定してください。 |
nats.url | String | ブローカーのアドレス。 |
nats.monitor_url | 任意の文字列 | 監視エンドポイントのベース URL。既定はブローカーホストの HTTP、ポート 8222 です。 |
db.sqlite_path | Path | SQLite ファイルのパス。 |
log.path, log.level, log.keep_days | エージェントと同じログ設定項目。 |
KANADE_BIND_ADDR、DATABASE_URL、KANADE_NATS_URL はこれらのサービス設定を上書きしません。認証設定は [auth] TOML セクションではありません。KANADE_AUTH_DISABLE は値に関係なく存在するだけで認証を無効にします(0 でも無効化)。開発専用です。本番では JwtSecret / KANADE_JWT_SECRET、StaticToken / KANADE_AUTH_STATIC_TOKEN、BootstrapAdminPassword / KANADE_BOOTSTRAP_ADMIN_PASSWORD などのバックエンド secret を使います。
SMTP 接続設定は [mail] TOML セクションではなく server_settings.mail(設定 → サーバー)にあり、バックエンド再起動後に反映されます。SMTP パスワードは別の MailPassword / KANADE_MAIL_PASSWORD secret のままです。
3. Windows レジストリ統合
本番の NATS トークンや管理 API bearer トークンなどは、ACL で保護された Windows レジストリ値に保存します。暗号化保存ではなく平文 REG_SZ です。Windows 以外では対応する環境変数を使います。
キーパス
- エージェント設定:
HKLM:\SOFTWARE\Kanade\agent - バックエンド設定:
HKLM:\SOFTWARE\Kanade\backend
導入スクリプトはレジストリの ACL を設定し、読み取りを SYSTEM と Administrators に制限します。
Passkeys (WebAuthn)
Passkeys are configured only in Operator Settings → Server Settings → Passkeys (the persisted server_settings KV document). There is no TOML setting. New installations default to disabled. An operator sets the RP ID, allowed origins (one per line), optional display name (default: Kanade), and explicitly enables passkeys. The update API uses nested per-field PATCH semantics: omission preserves a field, null clears it, and an origins array replaces the whole array. Invalid configurations are rejected before saving.
The RP ID must be a lowercase ASCII domain name without scheme, port or path. Origins must be HTTPS bare origins matching that domain or a subdomain; HTTP is accepted only for localhost. Values are never derived from request headers. Saving valid settings takes effect immediately, without restarting, on all backend instances. The settings card reports the effective enabled/disabled state and configuration/read failures. Each change invalidates outstanding registration and sign-in challenges, including a change back to an earlier RP. A ceremony's final authoritative settings read is its commit boundary: a settings write after that read applies to subsequent ceremonies.
Credential listing, removal and administrator reset remain available when passkey sign-in is disabled. Enrollment/removal still require the current password and, when enabled, TOTP. Password/TOTP sign-in and account recovery remain available. RP changes can make credentials registered under another RP unusable; register new credentials for the configured RP.
Configuration is shared across backends, but in-flight challenges remain in process memory. Route both steps of each ceremony to the same backend (sticky sessions); restarting that backend discards its outstanding challenges. Keep the backend behind a trusted proxy that appends the real client IP for throttling.