環境変数

trackica はプロセス起動時に環境変数を読み込みます。変更後は、該当する API・Web・デーモンのプロセスを再起動してください。Docker Compose の docker compose restart は .env を再読み込みしません。up -d でコンテナを再作成して初めて反映されます。

このページにはデプロイ運用者向けの設定のみを載せています。テスト用変数や内部タスク用の変数は扱いません。グループ別のリファレンスとして使い、完全なデプロイ手順はセルフホストクイックスタートを参照してください。

プロダクションの最小構成

DATABASE_URL=postgres://user:password@postgres:5432/trackica?sslmode=require
JWT_SECRET=<long-random-secret>
APP_ENV=production
FRONTEND_ORIGIN=https://trackica.example.com
TRACKICA_APP_URL=https://trackica.example.com
TRACKICA_PUBLIC_URL=https://api.trackica.example.com

さらにメールサービスを 1 つ選ぶ必要があります。選ばない場合、認証コードと招待はサーバーログに書き込まれるだけです。

API とデータベース

Kubernetes で shutdown hold を設定する場合、terminationGracePeriodSeconds は hold と実際のシャットダウンにかかる時間の合計より大きくしてください。

公開アドレスとブラウザアクセス

フロントエンドと API が異なる host を使い、ブラウザが API ドメインへ直接アクセスする構成では、COOKIE_DOMAIN の設定が必須です。設定しないとブラウザが CSRF cookie を読めず、すべての書き込みリクエストが 403 CSRF validation failed を返す一方、読み取りは正常に動きます。値には、両方の host を同時にカバーできる最も狭い親ドメインを使ってください（.example.com より .agent.example.com）。この設定はログインセッション cookie をそのドメイン配下のすべての host に広げるため、それらの host がすべて同一の信頼できる運用主体のものである場合にのみ使えます。変更後は両方の host で古い cookie を削除し、再ログインしてください。セルフホストクイックスタートの同一オリジン構成（ブラウザは app ドメインのみアクセス）に従う場合は、空のままで構いません。IP アドレスは指定しないでください。ブラウザは Domain が IP の cookie を無視します。

メールとログイン

Resend

SMTP

SMTP_HOST が空でない限り、SMTP が Resend より優先されます。

Google OAuth

サインアップ範囲

allowlist の正確な判定順序はログインとサインアップを参照してください。

添付ファイルストレージ

S3_BUCKET が未設定の場合、trackica はローカルディスクを使います。

S3 または互換ストレージ

内部ネットワークの MinIO など、ブラウザから endpoint に直接到達できない場合は ATTACHMENT_DOWNLOAD_MODE=proxy を使ってください。

ローカルディスク

CloudFront

Redis とレート制限

リバースプロキシ配下のデプロイでは、実際のプロキシのネットワーク範囲を設定してください。すべての送信元を無条件に信頼してはいけません。クライアントが転送元 IP を偽装できてしまいます。

認証レート制限には REDIS_URL が必要です。未設定の場合、起動ログに認証レート制限が無効であることが表示されます。招待制限は Redis なしでもプロセス内メモリで動作し、Redis を設定すると複数レプリカで割り当てを共有します。設定済みの Redis が一時的に利用できない場合、認証レート制限はフェイルオープンしますが、招待作成は保護なしでメールを送らず、再試行可能な 503 を返します。

外部連携

GITHUB_APP_ID と秘密鍵を設定しなくても、PR の関連付け・ミラー・マージによる done への遷移は通常どおり動きますが、カードに CI とマージ可否のステータスが表示されず、「GitHub から選択」のリポジトリ入口も無効になります。

設定手順は GitHub 連携、Lark Bot、Slack Bot、Telegram Botを参照してください。

サーバーサイド LLM

このグループは、会話タイトルなどサーバー側の補助生成機能の設定です。エージェントがタスクを実行するときに使う AI コーディングツールの資格情報ではありません。

TRACKICA_LLM_MAX_RETRIES はリトライポリシーの唯一の設定元です。未設定ならデフォルトの 2 回、0 なら 1 回の呼び出しにつきリクエストは 1 回だけ、1〜5 ならリトライは最大その回数までになります。これは割り当てではなく上限です。消費するのはリトライ対象の失敗だけで、成功や呼び出し側自身のデッドラインによって早く終わることもあります。それ以外の値（負数、非数値、5 超過）は静かに補正されるのではなく起動に失敗します。上限はレイテンシ予算です。バックオフは 0.5 秒から始まり 8 秒を上限に倍増するため、これより大きい予算は呼び出し側自身のタイムアウトを超え、リトライ可能な失敗をタイムアウトに変えてしまいます。リトライの対象は接続失敗と HTTP 408、409、429、5xx で、それ以外の 4xx はそのまま返されます。サーバーは起動時に有効なポリシーを llm retry policy として記録しますが、その行に資格情報は含まれません。

このレイヤーを使う機能は 4 つあり、設定した endpoint に次のデータを送信します。

• 会話タイトルの自動生成 — 新しいチャットセッションでユーザーが最初に送ったメッセージを、そのまま送信します。添付ファイルは含まれません。
• フォローアップ質問（エージェントの返信の下に表示されるボタン） — 会話の末尾を送信します。最大 6 メッセージで、対象の返信は 3000 文字、それより古いメッセージは各 800 文字が上限です。
• ガントステータス要約 — ユーザーが選択した最大 100 件の課題について、識別子、タイトル、説明（最大 2000 文字）、ステータス、優先度、日付、プロジェクトタイトルを送信します。
• プロジェクトスナップショットの要約 — ステータス、担当者、マイルストーン、タスク、デリバリー、リポジトリチェック、進捗、健全性シグナル、リスクフラグからなる構造化されたプロジェクト情報を送信します。課題の説明、コメント、添付ファイル、チャットは含まれません。 API key と base URL の両方が空の場合、このレイヤーは無効になり、上流へのリクエストを一切行いません。上記の機能は何も送信しなくなります。このレイヤーからデータをデプロイ外へ出せないポリシーでは、これがサポートされた構成です。セッションはクライアントが生成したタイトルを使い、フォローアップ質問と AI ガント要約は表示されず、プロジェクトスナップショットには事実ベースのフォールバックが残ります。

デーモン設定

以下の変数は、エージェントを実行するコンピューター上で読み込まれます。API コンテナ内ではありません。

各 AI コーディングツールは TRACKICA_<PROVIDER>_PATH でコマンドパスを上書きでき、モデル上書き対応ツールでは TRACKICA_<PROVIDER>_MODEL も利用できます。QwenPaw と MiniMax Code にはモデル変数がなく、MiniMax Code のパス変数は TRACKICA_MCODE_PATH です。詳しくは AI コーディングツール比較 を参照してください。DeepSeek Harness は TRACKICA_DSH_PATH と TRACKICA_DSH_MODEL に対応しています（値は dsh のモデルカタログにあるモデル ID、例: deepseek-official/deepseek-chat）。ZeroClaw は TRACKICA_ZEROCLAW_PATH に対応しますが、モデル変数はありません。モデルは ZeroClaw のエージェント設定で管理します。マシン全体のデフォルト引数 TRACKICA_<PROVIDER>_ARGS は、現在 Claude Code、Codex、CodeBuddy、Qwen Code、QwenPaw の 5 ツールに対応しています。対応する変数は TRACKICA_CLAUDE_ARGS、TRACKICA_CODEX_ARGS、TRACKICA_CODEBUDDY_ARGS、TRACKICA_QWEN_ARGS、TRACKICA_QWENPAW_ARGS です。例:

TRACKICA_CLAUDE_PATH=/opt/bin/claude
TRACKICA_CLAUDE_ARGS=--max-turns 40

優先順位はコマンドラインフラグ → 環境変数 → ~/.trackica/config.json → 組み込みデフォルトです。watchdog の動作はデーモンとランタイムを参照してください。

デーモン設定の永続化

デーモン側のよく使う設定は、シェルの環境変数に頼らず ~/.trackica/config.json に書き込むこともできます。名前付きプロファイルの設定ファイルは ~/.trackica/profiles/<name>/config.json にあります:

trackica config set poll_interval 10s
trackica config show

サポートされるキー:

値のルール:

• duration 系のキーは正の Go duration（10s、2h など）を受け付け、0s と負の値は拒否されます。唯一の例外は agent_timeout で、0s は有効な値として実行時間上限を明示的に無効化します。
• 空文字列を渡すと永続化された値がクリアされ、環境変数または組み込みデフォルトに戻ります。例: trackica config set poll_interval ""。
• max_concurrent_tasks には非負の整数が必要です。
• 相対パスの workspaces_root は保存時に絶対パスへ変換されます。

可観測性と分析

次のステップ

• ログインとサインアップ — ログイン方式とサインアップ制限。
• トラブルシューティング — デプロイ問題の症状別診断。
• デーモンとランタイム — デーモン側の対応する設定。