環境変数

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

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

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

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

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

API とデータベース

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

primary とレプリカの接続上限は独立しています。全 API プロセスの合計が PostgreSQL クラスターの接続上限に収まるように設定してください。レプリカ接続はデフォルトで 5 分後に再作成され、昇格後に読み取り専用状態を再検証します。接続失敗時はインフラストラクチャが透過的に primary へフォールバックし、短時間のパッシブサーキットを開きます。バックグラウンドのデータベースプローブは追加されません。アプリケーションはレプリカデータの最大経過時間を保証しないため、データベース層でレプリケーション遅延を監視し、整合性が必要な読み取りは primary に残してください。

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

フロントエンドと 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 が未設定の場合、Multica はローカルディスクを使います。

S3 または互換ストレージ

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

ローカルディスク

CloudFront

Redis とレート制限

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

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

外部連携

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

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

サーバーサイド LLM

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

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

MULTICA_LLM_DISABLE_THINKING は、モデルが推論（thinking）パスを実行してアシスト呼び出しのレイテンシ予算を食いつぶす gateway 向けの設定です。true（または 1）にすると、サーバーはすべてのリクエストボディに chat_template_kwargs: {"enable_thinking": false} を付加します。このフィールドを転送する gateway（vLLM/sglang 系のデプロイや、GLM/Qwen 系の一部 LiteLLM ルート）は、thinking パスを省略します。標準の OpenAI endpoint は未知のボディフィールドを拒否するため、上流が受け付ける場合のみ有効にしてください。GPT-5.6 系モデルはフォローアップ質問のリクエストではサーバーが既に reasoning_effort: none を付けます。チャットの自動タイトル生成は推論フィールドを送信しません。本設定がそれに影響するのは、構成された上流が chat_template_kwargs を受け付ける場合だけです。指定できる値は true/false と 1/0（大文字小文字を区別しない）で、それ以外は起動に失敗します。起動ログにはリトライポリシーと併せて有効な状態が記録されます。

このレイヤーを使う機能は 2 つあり、どちらも設定した endpoint にチャットの内容を送信します。

• 会話タイトルの自動生成 — 新しいチャットセッションでユーザーが最初に送ったメッセージを、そのまま送信します。添付ファイルは含まれません。
• フォローアップ質問（エージェントの返信の下に表示されるボタン） — 会話の末尾を送信します。最大 6 メッセージで、対象の返信は 3000 文字、それより古いメッセージは各 800 文字が上限です。

API key と base URL の両方が空の場合、このレイヤーは無効になり、上流へのリクエストを一切行いません。上記 2 つの機能はどちらも何も送信しなくなります。このレイヤーからチャットの内容をデプロイ外へ出せないポリシーでは、これがサポートされた構成です。セッションはクライアントが最初のメッセージから生成したタイトルをそのまま使い、フォローアップ質問のボタンは表示されず、他の機能への影響はありません。

デーモン設定

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

デーモンがエージェント作業に注入する内部コンテキストについては、作業ランタイム環境を参照してください。

各 AI コーディングツールは MULTICA_<PROVIDER>_PATH でコマンドパスを上書きでき、モデル上書き対応ツールでは MULTICA_<PROVIDER>_MODEL も利用できます。QwenPaw と MiniMax Code にはモデル変数がなく、MiniMax Code のパス変数は MULTICA_MCODE_PATH です。詳しくは AI コーディングツール比較 を参照してください。DeepSeek Harness は MULTICA_DSH_PATH と MULTICA_DSH_MODEL に対応しています（値は dsh のモデルカタログにあるモデル ID、例: deepseek-official/deepseek-chat）。 DeepSeek Harness はさらに MULTICA_DSH_PROFILE_BUNDLE に対応しています。multica プロファイルが存在しない場合にインストールするバンドルを指定するもので、カンマ区切りで複数の候補を順に試します。各項目は npm のパッケージ名、ディレクトリ、またはパック済み tarball です。既定では未設定です。Multica が利用する --stdio プロトコルはこのプロファイルが提供するため、未設定の場合は DSH のインストールには手を加えず、デーモンは使用できないランタイムを登録する代わりにプロファイルの欠落を報告します。Multica 自身のブリッジはまだ公開 npm レジストリにないため、値の選び方はエージェントランタイムのインストールを参照してください。ここに設定した値は追加の確認なしに各デーモンホストの DSH ホームへインストールされるので、サプライチェーンの判断として扱ってください。MULTICA_DSH_PROFILE_BUNDLE が有効にするインストールは範囲を意図的に限定しています。実行はデーモンのライフタイムにつき最大 1 回、プローブがプロファイルの不在を確認できた場合のみです。失敗時はパッケージマネージャー自身の出力をログに記録し、再試行はデーモンの再起動後のみ行います。プローブがタイムアウトした場合や、このデーモンが扱わないプロトコルバージョンを返した場合は報告のみで、上書きインストールは行いません。意図して用意されたプロファイルをデーモンが上書きすることはありません。調査はデーモンログで DSH runtime profile を検索してください。取り消す場合は $DSH_HOME/profiles/multica（既定は ~/.dsh/profiles/multica）を削除します。MULTICA_DSH_PLUGIN_PATH はインストール時に pnpm を解決するディレクトリを上書きします。dsh plugin が転送する pnpm は macOS でも Windows でも DSH Desktop 独自の runtime-commands ディレクトリに置かれており、デーモンはそれを自動で見つけて PATH の先頭に追加します（新しい Desktop が使うバージョン付きの構成も含みます）。したがってこの変数が必要なのは、デーモンが見つけられない場所にインストールされている場合か、独自の pnpm を使わせたい場合だけです。設定すると自動探索は完全に置き換わり、指定したディレクトリが存在しなければ、インストールは同梱の pnpm ではなくデーモンの PATH 上の pnpm にフォールバックします。Linux には DSH Desktop がないため、常に PATH が使われます。ZeroClaw は MULTICA_ZEROCLAW_PATH に対応しますが、モデル変数はありません。モデルは ZeroClaw のエージェント設定で管理します。マシン全体のデフォルト引数 MULTICA_<PROVIDER>_ARGS は、現在 Claude Code、Codex、CodeBuddy、Qwen Code、QwenPaw の 5 ツールに対応しています。対応する変数は MULTICA_CLAUDE_ARGS、MULTICA_CODEX_ARGS、MULTICA_CODEBUDDY_ARGS、MULTICA_QWEN_ARGS、MULTICA_QWENPAW_ARGS です。例:

MULTICA_CLAUDE_PATH=/opt/bin/claude
MULTICA_CLAUDE_ARGS=--max-turns 40

Cursor の検証済みバックグラウンドクリーンアップには、Linux 6.9 以降（プロセスグループ pidfd）、macOS カーネルによるプロセス識別子の照会と audit token を用いたシグナル送信のサポート、または Windows で正常に割り当てられた入れ子の Job Object が必要です。macOS では各プロセスへのシグナル送信にカーネルが検証する PID version を用いるため、同一セッションのグループに参加する必要はありません。これらの macOS API は非公開であり、プロセス捕捉時に確認されます。所有権を確保できなかったバックグラウンドプロセスは元のツール結果を返し、ツール watchdog が 0 の場合も含めて通常の idle watchdog に従います。すでに所有している作業は、クリーンアップを確認できない場合も実行中のままです。ツール watchdog を 0 にした場合はこの境界自体が存在せず、所有済みのバックグラウンド作業が生きている限り実行は継続します。その場合の実行は MULTICA_AGENT_TIMEOUT だけに制限され、これも既定値は 0 です。

所有している Cursor のバックグラウンドプロセスは、実行が正常に完了したときにも停止されます。したがって、その実行が起動したバックグラウンドサーバーが意図的に終了処理後まで生き残ることはありません。macOS は保持された元の親プロセスの識別子によって後から生まれた子プロセスを認識できますが、観測前に中間プロセスが消えた連鎖は証明できません。そのようなプロセス、追跡対象のグループから外れた作業、および継続的な所有権や送信のエラーは、バックグラウンド作業を残す可能性があります。確認できなかったクリーンアップはログに記録され、「クリーンアップ成功」による回復ウィンドウを与えることはありません。数値の PID やプロセスグループだけを根拠に未知のプロセスを終了させることはありません。

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

デーモン設定の永続化

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

multica config set poll_interval 10s
multica config show

サポートされるキー:

値のルール:

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

可観測性と分析

ファーストパーティのセルフホストテレメトリーは、UTC 日ごとにデプロイ単位のスナップショットを、固定かつ設定変更不可の https://telemetry.multica.ai/v1/telemetry/events へ送信します。正式リリース版、ワークスペース数・重複を除いたメンバー数・アクティブなエージェント数・過去 24 時間のアクティブなデーモン数のバケット、および過去 24 時間に開始・完了・失敗・キャンセルされた実行の集計値だけを含みます。名前、メールアドレスやドメイン、IP、業務 ID、ホストやデバイス情報、リポジトリ、モデルや plugin、prompt/output、コメントやチャット、ファイルパス、token/費用、認証情報、エラー、stack、ログは送信しません。このデータはセルフホスト版の採用状況、デプロイ規模、集計利用量の把握だけに使われ、課金、ライセンス、認証、セキュリティ判断には使われません。

DO_NOT_TRACK と ANALYTICS_DISABLED は独立しています。前者はこの匿名スナップショットを、後者は任意の PostHog 連携を制御します。

次のステップ

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