設定リファレンス

これは config.toml のキー別リファレンスです。Takuto Core リポジトリのルートにある注釈付きの config.toml.example が信頼できる情報源です — このページとそのファイルが食い違う場合は、example が優先されます。

設定はファイル変更時に再読み込みされます（5 秒ごとのポーラー）。いくつかのキーは 起動時のみ で、再起動が必要です（各所に注記）。シークレットは takuto.env に置き、 config.toml には決して書かないでください — 環境変数を参照。

Takuto Core は設定を 2 種類に分けています:

Bootstrap — データベース/ダッシュボードが存在する前に必要なもの、または起動時のみ適用されるもの。初回起動の前に config.toml で手編集します。
UI 管理 — 妥当なデフォルトを持ち、通常はダッシュボードの設定画面から編集します。 UI は変更を config.toml に書き戻すので、ファイルがストアであり続けます。ここで設定した値はデプロイ時のデフォルトにすぎません。

Scope 列は各キーを Bootstrap とマークするか、それを管理するダッシュボードの画面名を示します。🔒 はセキュリティに関わるキーです — 共有デプロイで変更する前に確認してください。

`[general]`

プロセス全体の挙動: チケットモード、ポーリング、同時実行数、ログ出力。

キー	デフォルト	型	Scope	説明
`ticketing_system`	`"none"`	string	Bootstrap	`"jira"`、`"github"`、または `"none"`。ポーラーとダッシュボードの + ボタンを駆動します。
`dry_mode` 🔒	`false`	bool	Bootstrap	実際の Jira/GitHub への副作用（割り当て、遷移、push）をスキップします。ローカル作業 — worktree、インストール、エージェントセッション — は引き続き実行されます。本番投入前に workflow 定義をならすのに便利です。
`log_level`	`"info"`	string	Bootstrap（再起動）	`trace`、`debug`、`info`、`warn`、`error`。
`worker_image`	`""`	string	Bootstrap	DinD 有効時の隔離 workflow container 用 Docker イメージ。空 = 実行中の Takuto イメージから自動検出。
`workflow_definitions_dir`	`"workflows"`	string	Bootstrap（再起動）	`*.toml` workflow 定義をスキャンするパス（設定ファイルのディレクトリからの相対）。
`allow_auto_generate_secret_key` 🔒	`true`	bool	Bootstrap	`true` のとき、キーがなければ初回起動時にサーバーが `{data_dir}/secret.key` を自動生成します。鍵を別管理でプロビジョニングするなら `false` に。
`poller_owner_username`	(未設定)	string	Bootstrap	ポーラーが自動作成する workflow を所有するユーザー名。未設定の場合、辞書順で最初の停止されていない admin が使われます。
`migrate_orphan_workflows`	`false`	bool	Bootstrap	`true` のとき、所有者のいない復元済み workflow（マルチユーザー化前の孤児）が起動時に解決済みのポーラー所有者へ再割り当てされます。
`migrate_orphan_repo_associations`	`true`	bool	Bootstrap	`true` のとき、起動時の整合処理で復元済み workflow を一致する登録済みリポジトリに紐付けます。
`auto_polling`	`true`	bool	UI: Item Polling	`false` のとき、ポーリングは起動時に一時停止で始まります。Resume polling でチケットの取得を始めます。
`poll_interval_secs`	`60`	int	UI: Item Polling	Jira/GitHub ポーリングの間隔（秒）。
`pr_merge_poll_interval_secs`	`60`	int	UI: Item Polling	workflow の PR が GitHub でマージされたかを確認するポーリングの間隔（秒）。`0` で無効。
`max_concurrent_workflows`	`1`	int	UI: Item Polling	並列の mise/install/エージェントセッションのセマフォサイズ。CPU と RAM に合わせて調整。
`max_active_workflows`	`0`	int	UI: Item Polling	ダッシュボードに表示される workflow の最大数（全行）。この上限ではポーラーは新しいチケットを開始しません。`0` は `max_concurrent_workflows` に追随。
`max_concurrent_manual_workflows`	`0`	int	UI: Item Polling	Done/Stopped/Error 以外のダッシュボード + 手動開始の上限。`0` = 無制限。
`generate_report`	`false`	bool	UI: Item Polling	`true` のとき、各エージェントステップが知見をレポートに追記し、最終ステップがそれらを統合します。トークンが増えます。
`work_item_log_retention_days`	`7`	int	UI: Item Polling	クリーンアップ前に保持する作業項目ログ行の日数。`0` = 永久に保持。

`[jira]`

[general] ticketing_system = "jira" のときのみ使用。

キー	デフォルト	型	Scope	説明
`site`	`""`	string	Bootstrap	Jira ホスト、または完全な `https://` URL（例: `"yourcompany.atlassian.net"`）。トークン認証、egress 許可リスト、PR 本文の Jira リンクを駆動します。
`email`	`""`	string	Bootstrap	`acli` トークン認証用の Jira ユーザーメール。
`project_keys`	`[]`	array	UI: Item Polling	ポーリングする Jira プロジェクトキー（例: `["PROJ", "ENG"]`）。空のとき + ピッカーは非表示。
`item_types`	`["Task", "Bug"]`	array	UI: Item Polling	ポーラーが拾うチケットの種類。手動の + ピッカーは Epic 以外のすべての issue を表示します。
`done_status`	`"Done"`	string	UI: Item Polling	Mark as Done が発火させる遷移。Jira workflow 内の実在する遷移と一致している必要があります。
`jql_filter`	`""`	string	UI: Item Polling	+ ピッカーに `AND` で結合される追加 JQL。Epic は常に除外されます。
`linked_items_in_prompt`	`"full"`	string	UI: Item Polling	`"full"` \| `"summary_only"` \| `"omit"` — リンクされた issue の文章が `{ticket_context}` にどう現れるか。
`ticket_context_max_description_bytes`	`0`	int	UI: Item Polling	`{ticket_context}` 内のメインチケット説明の上限。`0` = 無制限（デフォルト）。
`linked_issue_description_max_bytes`	`0`	int	UI: Item Polling	`linked_items_in_prompt = "full"` のときの、リンク issue 説明あたりの上限。`0` = 無制限（デフォルト）。

`[polling]`

admin が調整できる項目ポーリングのポリシー: 発見した項目のどれをポーラーが自動追加するか、どのフローを自動開始するか、いくつ並列で実行するか。サイクルごとに ライブ で読み込まれます（再起動不要）。すべての [polling] キーは 設定 → Item Polling から UI 管理されます。

キー	デフォルト	型	Scope	説明
`auto_start_flow`	`""`	string	UI: Item Polling	ポーリングした項目ごとに自動開始する単一フローの slug。空 = 依存のないすべてのフローを開始。
`max_parallel_items`	`0`	int	UI: Item Polling	同時に同時実行スロットを占有する項目の上限。`0` = 無制限。
`max_parallel_per_user`	`false`	bool	UI: Item Polling	`true` のとき `max_parallel_items` は workflow 所有者ごとに数えられ、`false` ならグローバルに数えられます。

`[polling.jira]`

キー	デフォルト	型	Scope	説明
`summary_keywords`	`[]`	array	UI: Item Polling	チケットサマリーに対する大文字小文字を区別しない ANY 部分一致。空 = フィルターなし。

`[polling.github]`

キー	デフォルト	型	Scope	説明
`labels`	`[]`	array	UI: Item Polling	ラベルの完全一致メンバーシップ、ANY 一致。空 = フィルターなし。
`title_keywords`	`[]`	array	UI: Item Polling	issue タイトルに対する大文字小文字を区別しない ANY 部分一致。空 = フィルターなし。

`[git]`

すべての [git] キーは Bootstrap 設定です。

キー	デフォルト	型	Scope	説明
`base_branch`	`"main"`	string	Bootstrap	各 worktree の作成元ブランチ。
`remote`	`"origin"`	string	Bootstrap	fetch、ベース ref、push に使う git remote。
`repo_path`	`"/workspace"`	string	Bootstrap	container 内で clone したリポジトリへのパス。ワークスペース名はこのパスの末尾コンポーネントから導かれます。

`[github]`

任意の GitHub App 認証。設定すると、コミットと PR が個人の gh ユーザーではなく bot アカウントに帰属します。3 つのフィールド（app_id、app_installation_id、そして 1 つの秘密鍵ソース）はすべて一緒に設定する必要があります。エラーは致命的ではなく — Takuto Core は個人の gh 認証にフォールバックし、警告をログに記録します。必要な App 権限: contents（write）、pull_requests（write）、metadata（read）。

キー	デフォルト	型	Scope	説明
`app_id`	(未設定)	int	Bootstrap	GitHub App ID。
`app_installation_id`	(未設定)	int	Bootstrap	あなたの組織/リポジトリ用の App インストール ID。
`app_private_key` 🔒	(未設定)	string	Bootstrap	PEM 形式の RSA 秘密鍵（インライン）。`app_private_key_path` とは排他。`takuto.env` に置くことを推奨します。
`app_private_key_path` 🔒	(未設定)	string	Bootstrap	App の秘密鍵を含む PEM ファイルへのパス。

`[web]`

ダッシュボードサーバー。

キー	デフォルト	型	Scope	説明
`host`	`"0.0.0.0"`	string	Bootstrap（再起動）	バインドアドレス。
`port`	`8080`	int	Bootstrap（再起動）	バインドポート。
`cors_origins` 🔒	`[]`	array	Bootstrap（再起動）	許可する CORS オリジン。空 = `host`/`port` から自動計算。リバースプロキシや TLS ターミネーターの背後では明示的に設定します（例: `["https://maestro.example.com"]`）。
`cookie_secure` 🔒	(自動検出)	bool	Bootstrap	セッション cookie の `Secure` フラグを制御します。`https://` の `cors_origins` または受信した `X-Forwarded-Proto: https` から自動検出。そのヘッダーなしで TLS を終端する場合は `true` を強制。`false` はローカルの素の HTTP テスト専用です。
`kick_other_sessions_on_login`	`true`	bool	Bootstrap	`true` のとき、ログイン成功時に同一ユーザーの以前のセッションを削除します。デスクトップ + モバイルの同時セッションには `false` に。

認証は マルチユーザーのみ です。初回起動時、ダッシュボードは最初の admin アカウントの作成を促します。レガシーのシングルユーザーキー [web] dashboard_username / dashboard_password は削除されました — 古い config.toml に存在しても黙って無視されます。

セッションポリシー（設定不可）: アイドル TTL 24 時間。絶対 TTL 30 日。10 分以内にログイン/リカバリーを 5 回失敗するとアカウントロック（admin は POST /api/users/{id}/unlock で解除）。/api/auth/login と /api/auth/recover の IP ごとのレート制限は 10 / 分。

`[database]`

Takuto がユーザー、セッション、スナップショットを保存する場所。このセクションを省略する（または connection を空のままにする）と、{data_dir}/takuto.db の 設定不要の SQLite デフォルトが維持されます。外部の PostgreSQL / MariaDB / MySQL を使うには connection を設定します。再起動時のみ — PUT /api/config はこのセクションをパッチしません。バックエンドの変更にはプロセスの再起動が必要です。

キー	デフォルト	型	Scope	説明
`connection` 🔒	`""`	string	Bootstrap（再起動）	データベース URL。空 → SQLite。スキーム: `sqlite://…`、`postgres://…` / `postgresql://…`、`mysql://…`（MariaDB もこれに含む）。パスワードは `GET /api/config` では伏せられます。
`max_connections`	`10`	int	Bootstrap（再起動）	接続プールのサイズ。
`acquire_timeout_secs`	`30`	int	Bootstrap（再起動）	プールから接続を取得するまでにタイムアウトせず待つ時間。
`idle_timeout_secs`	`600`	int	Bootstrap（再起動）	アイドル接続の寿命。
`fail_fast` 🔒	`true`	bool	Bootstrap（再起動）	`true` のとき、起動時に 5 秒の `SELECT 1` プローブを実行し、バックエンドに到達できなければ中断します。`false` のときは警告をログに出し、そのプロセスはローカルの SQLite にフォールバックします。
`import_from_sqlite`	`true`	bool	Bootstrap（再起動）	まっさらな外部バックエンドへの初回接続時に、既存のローカル SQLite データをそこへ一度だけコピーします（セッションは失効するので、ユーザーは再認証します）。以降の再起動ではスキップされます。

データベースを container で動かしていますか? connection のホストは Takuto container の内側から 到達できなければなりません — localhost やホスト側に公開したポート（例: localhost:5433）ではなく、データベースの container 名とその内部ポート（例: takuto_db:5432）を使い、両方の container を同じネットワークに載せてください。詳しい手順は 外部データベース にあります。

`[agent]`

prompt を持つ workflow ステップ用の AI プロバイダー。すべての [agent] キーは 設定 → AI Settings から UI 管理されます。ここの値はデプロイ時のデフォルトです。

キー	デフォルト	型	Scope	説明
`provider`	`"claude"`	string	UI: AI Settings	`"claude"`、`"cursor"`、`"codex"`、または `"opencode"`。それぞれ自分の `[agent.providers.<name>]` サブテーブルを読みます。
`step_timeout_secs`	`1800`	int	UI: AI Settings	ステップごとのタイムアウト（秒）。すべてのプロバイダーに適用。
`improve_timeout_secs`	`300`	int	UI: AI Settings	AI による説明の改善（“improve”）アクションのタイムアウト（秒）。
`share_conversation_across_steps`	`false`	bool	UI: AI Settings	フローのステップ間で 1 つのエージェント会話を共有するか、ステップごとに新しいセッションにするか。
`max_repeated_output_lines`	`8`	int	UI: AI Settings	無進捗ガードレール。出力が同じ実質的な行をこの回数連続で繰り返したらステップを中断。`0` で無効。

プロバイダーごとの設定（モデル、エンドポイント、CLI パス、追加引数）は [agent.providers.<name>] サブテーブルにあります。共通フィールド: model、extra_args、 allow_shared_default。Claude/Codex/OpenCode は base_url を、Cursor は cli を使います。

`[agent.providers.cursor]`

provider = "cursor" のときのみ使用。

キー	デフォルト	型	Scope	説明
`cli`	`"agent"`	string	UI: AI Settings	Cursor Agent の実行ファイル名または絶対パス。
`model`	`"Auto"`	string	UI: AI Settings	Cursor Agent の `--model`。`"Auto"` または空 = 自動選択。
`extra_args`	`[]`	array	UI: AI Settings	追加の CLI フラグ（deny-list で制限）。

`[agent.providers.opencode]`

OpenCode（セルフホスト、OpenAI 互換）アダプター。provider = "opencode" のときのみ使用。セルフホストモデルを参照。

キー	デフォルト	型	Scope	説明
`model`	`""`	string	UI: AI Settings	エンドポイントが提供するモデル id（`-m self_hosted/<model>` の `<model>`）。有効時は必須。
`base_url`	`""`	string	UI: AI Settings	OpenAI 互換エンドポイントの URL（例: `http://lm-studio:1234/v1`）。有効時は必須。
`extra_args`	`[]`	array	UI: AI Settings	追加の CLI フラグ（deny-list で制限）。
`allow_shared_default`	`false`	bool	UI: AI Settings	個人の bearer を持たないユーザーが、デプロイのデフォルトトークンにフォールバックできるようにします。
`context_limit`	`32768`	int	UI: AI Settings	セルフホストモデルの最大コンテキストウィンドウ（トークン）。サーバーで読み込んだコンテキスト長に合わせます。
`output_limit`	`8192`	int	UI: AI Settings	レスポンスあたりの最大出力トークン。

Claude と Codex は独自の [agent.providers.claude] / [agent.providers.codex] サブテーブルを使い、model、base_url、extra_args をすべて 設定 → AI Settings から編集できます。

`[docker]`

すべての [docker] キーは Bootstrap です（イメージビルド時 / compose up 時に消費）。

キー	デフォルト	型	Scope	説明
`build_commands`	`[]`	array	Bootstrap	イメージビルド中に実行する任意の `bash -c` ステップ。
`compose_up_commands`	`[]`	array	Bootstrap	毎回の `docker compose up` でプリフライト後に `maestro` ユーザーとして実行する任意のコマンド。

`[editor]`

ブラウザ内の VS Code（openvscode-server）と動的ポートフォワーディング。すべての [editor] キーは Bootstrap です。

キー	デフォルト	型	Scope	説明
`ports`	`[]`	array	Bootstrap	エディターを開くときに公開するアプリケーションポート（例: `[3000, 5173, 6006]`）。各ポートは 9100–9200 の範囲のホストポートにマップされ、workflow カードに表示されます。
`dynamic_ports`	`10`	int	Bootstrap	dev サーバーの自動フォワーディング用に事前確保する予備ポート。`0` で無効。
`theme`	`""`	string	Bootstrap	VS Code のカラーテーマ。空のときはエディター自身のデフォルトが使われます（例: `"One Dark Pro"`）。
`extensions`	`[]`	array	Bootstrap	事前インストールするマーケットプレイス ID（例: `["esbenp.prettier-vscode"]`）。
`settings`	`{}`	table	Bootstrap	`[editor.settings]` 配下の自由形式の VS Code 設定。

`[terminal]`

エディター container 内の Web ターミナル（ttyd）。すべての [terminal] キーは Bootstrap です。

キー	デフォルト	型	Scope	説明
`git_editor`	(未設定)	string	Bootstrap	すべてのエディター container にインストールする apt パッケージ（例: `"nano"`、`"vim"`）。`git config core.editor` がこれに設定されます。
`setup_commands`	`[]`	array	Bootstrap	エディター container のライフタイムごとに 1 回実行するシェルコマンド（マーカーファイルで防護）。
`startup_commands`	`[]`	array	Bootstrap	新しいエディター container が作成されるたびに実行するシェルコマンド。

`[network]`

firewall ポリシー — デプロイ時のみ。すべての [network] キーは Bootstrap です。

許可リストは プロバイダー対応 です: firewall は、有効にした AI プロバイダーの API ホスト — アクティブな [agent].provider と [agent].available_providers のすべてのプロバイダー（Claude、Codex/OpenAI、Cursor）、そしてセルフホストの base_url — を自動的に許可します。デフォルト設定（4 つのプロバイダーすべてが利用可能）では、対応するすべてのベンダーに最初から到達できます。available_providers を絞れば、firewall を実際に使うプロバイダーだけに狭められます。正確なホストは、適用時に core の takuto egress-hosts コマンドが解決します。

キー	デフォルト	型	Scope	説明
`extra_egress_hosts` 🔒	`[]`	array	Bootstrap	組み込みのデフォルト（あなたの AI プロバイダー、Atlassian、GitHub、npm レジストリ、`.npmrc` で検出されたレジストリ）に加えて egress 許可リストに追加するドメイン。各エントリは攻撃面を広げます — エージェントが到達することを信頼できるホストだけを追加してください。
`allow_all_https` 🔒	`false`	bool	Bootstrap	`true` のとき、許可リストをスキップしてすべての送信 HTTPS（443/8443）を許可します。`extra_egress_hosts` は無視されます。信頼できる環境でのみ使用してください — これは Takuto Core の中核的な緩和策の 1 つを無効化します。

`[provisioning]`

起動時に共有ツールボリュームへインストールする追加 CLI ツール（イメージに焼き込まれたものに加えて）。ツールのバージョンを固定したり、bake から外されたツールを追加したり、1 つを丸ごとスキップしたりするのに使います。Bootstrap（起動時に適用）。Takuto Core の拡張を参照。

キー	デフォルト	型	Scope	説明
`install_commands`	`[]`	array	Bootstrap	ツールボリュームに対して順に実行するシェルスニペット。SHA でゲートされ、リストが変わったときだけ再実行されます。各スニペットは冪等で、`$MAESTRO_TOOLS_BIN` にインストールするようにしてください。

`[dev]`

開発専用のつまみ。本番ではコメントアウトしておきます。すべての [dev] キーは Bootstrap です。

キー	デフォルト	型	Scope	説明
`mock_agent`	`false`	bool	Bootstrap	`true` のとき、エージェントセッションはスクリプト化されたモックに短絡します — 実際の `claude`/`agent` プロセスも、トークン消費もありません。`MAESTRO_DEV_MOCK_AGENT=1` を尊重します。
`mock_agent_script_path`	(未設定)	string	Bootstrap	モックスクリプトファイルへのパス。デフォルトなし — `tmp/mock_script.txt` はあくまで推奨例です。
`mock_agent_line_delay_ms`	`75`	int	Bootstrap	モック出力行の間の遅延。
`mock_agent_total_ms`	`5000`	int	Bootstrap	モックセッションの総時間。

無視されるセクション

次のセクションは 読み込み時に完全に無視されます — 気づけるように起動時の警告がログに記録されますが、その内容は決して読まれません。ユーザーごと・ワークスペースごとであるため config.toml から外され、いまはデータベースにのみ存在し、ダッシュボードから編集されます:

[commands] — worktree 初期化コマンド（以前の pre_install、install、pre_workflow、いまは worktree_init_commands）はデータベースにあり、(user, workspace) ごとに解決され、 設定 → Worktree Settings から編集されます。
[[run_commands]] — 実行/停止ボタンとして現れる長時間稼働の dev サーバーコマンドはユーザーごとで、同じ Worktree Settings タブから設定されます。

config によるフォールバックはありません: セクションがデータベースに存在しなければ、 workflow はそれに対するコマンドを単に何も実行しません。

環境変数

シークレットとホストごとのオーバーライドは takuto.env（/etc/maestro/env にマウント）に書きます。export VAR=value の行のみが尊重されます。

変数	用途
`ANTHROPIC_API_KEY` 🔒	Claude API キー（または `claude login` 経由の OAuth）。
`ANTHROPIC_BASE_URL`	Anthropic API エンドポイントのオーバーライド（プロキシ / オンプレゲートウェイ）。
`CLAUDE_CODE_OAUTH_TOKEN` 🔒	Claude Code OAuth 認証のトークン。
`CURSOR_API_KEY` 🔒	Cursor Agent のキー — 対話式の `agent status` プリフライトをスキップします。
`GH_TOKEN` 🔒	GitHub PAT（きめ細かく、対象リポジトリに範囲を限定）。
`MAESTRO_CONFIG`	代替の `config.toml` へのパス。
`MAESTRO_DATA_DIR`	永続データディレクトリ（`maestro.db`、スナップショット）のオーバーライド。
`MAESTRO_HOME`	`MAESTRO_DATA_DIR` の計算に使うホームベースのオーバーライド。
`MAESTRO_DEV_MOCK_AGENT`	`1` = モックエージェントを強制的に有効化（`[dev] mock_agent` を上書き）。

takuto.env の例:

export ANTHROPIC_API_KEY="sk-ant-..."
export GH_TOKEN="github_pat_..."
export ANTHROPIC_BASE_URL="https://custom-proxy.example.com/claude"