環境変数

セルフホストの Multica サーバーは、起動時に環境変数から設定を読み込みます — データベース、サインイン、メール、ストレージ、サインアップ許可リストはすべてここにあります。このページでは、すべての変数を用途別にグループ化しています。各セクションでは、設定しないと何が起きるか、そしてプロダクションで必ず設定すべきものはどれかを明確に説明します。auth 関連の変数を実際にどう設定するかについては、サインインとサインアップの設定を参照してください。

コアサーバー変数

デプロイ前に必ず検討すべきコア変数です — 一部はサーバーを起動できるようにするデフォルト値を持っていますが、プロダクションでは必須項目を明示的に設定すべきです。

Kubernetes で MULTICA_SHUTDOWN_HOLD_DURATION を使用する場合、terminationGracePeriodSeconds は hold 時間とその後のグレースフルシャットダウン時間の合計より長く設定してください。両方を同じ時間にすると、クリーンアップが完了する前に kubelet が SIGKILL を送信する可能性があります。

データベース接続プール

設定しない場合、上記の値が使われます — 以前プロダクションでプール枯渇を引き起こした pgx 組み込みの 4/NumCPU デフォルトではありません。

メール設定

Multica は 2 つの配信バックエンドをサポートします — クラウドデプロイ向けの Resend と、内部 / オンプレミスネットワーク向けの SMTP relay です。両方が設定されている場合は SMTP_HOST が RESEND_API_KEY より優先されます。

Resend

SMTP relay

サーバーが STARTTLS を通知すると自動的にアップグレードされます。dial タイムアウトは 10 秒で、SMTP セッション全体には 30 秒のデッドラインがあるため、ブラックホール化した relay が auth ハンドラーをハングさせることはできません。

どちらも設定していない場合の動作: サーバーはエラーを出しませんが、送信されるはずだったすべてのメール（検証コード、招待リンク）はサーバーの stdout にのみ記録されます。ローカル開発には便利です — サーバーログからコードをコピーして使ってください。プロダクションでこれを設定し忘れると、静かなブラックホールが生まれ、ユーザーはメールをまったく受け取れず、エラーも一切表面化しません。

Google OAuth 設定

任意です。メール + 検証コードのみを使用する場合は設定しないままにし、サインインページに「Sign in with Google」を追加する場合は設定してください。

ランタイムで適用されます: フロントエンドはこれらの設定をランタイムに /api/config 経由で読み込むため、変更してもフロントエンドのリビルドや再デプロイは不要です — サーバーを再起動すれば適用されます。

完全なセットアップ（Google Cloud Console の手順を含む）はサインインとサインアップの設定にあります。

ファイルストレージ設定

Multica はユーザーがアップロードした添付ファイル（コメント内の画像やファイル）を保存します。S3 が推奨されます。S3 が設定されていない場合はローカルディスクにフォールバックします。

S3 / S3 互換ストレージ

S3_BUCKET を設定しない場合: サーバーは起動時に "S3_BUCKET not set, cloud upload disabled" をログに記録し、すべてのアップロードはローカルディスクにフォールバックします。

保存されるオブジェクト URL は次の優先順位で構築されます。

1. CLOUDFRONT_DOMAIN が設定されている場合は https://<CLOUDFRONT_DOMAIN>/<key>。
2. AWS_ENDPOINT_URL が設定されている場合は <AWS_ENDPOINT_URL>/<S3_BUCKET>/<key>（path-style）。
3. https://<S3_BUCKET>.s3.<S3_REGION>.amazonaws.com/<key>（virtual-hosted-style）。S3_BUCKET にドットが含まれる場合、AWS が発行するワイルドカード TLS 証明書がドットを含むバケットホストを検証できないため、サーバーは https://s3.<S3_REGION>.amazonaws.com/<S3_BUCKET>/<key>（path-style）にフォールバックします。

API の download_url は、CloudFront 署名が設定されていない場合 GET /api/attachments/{id}/download を使います。この endpoint は安全な場合 CloudFront/S3 presigned URL にリダイレクトし、http://rustfs:9000 のようなプライベート/内部 endpoint では server がストリーミングします。Docker/VPC 内部のオブジェクトストアでは ATTACHMENT_DOWNLOAD_MODE=proxy を明示できます。

ローカルディスク（S3 が設定されていない場合）

CloudFront（任意）

S3 の前段に CloudFront を置く場合、3 つの変数が適用されます: CLOUDFRONT_DOMAIN、CLOUDFRONT_KEY_PAIR_ID、CLOUDFRONT_PRIVATE_KEY（または Secrets Manager から読み込むには CLOUDFRONT_PRIVATE_KEY_SECRET）。CloudFront を使わない場合はスキップしてください — S3 設定とは競合しません。

Cookie ドメイン

• 空: cookie は訪問した正確なホストでのみ有効です（単一ホストのデプロイに適切）
• .example.com に設定: cookie がサブドメイン間で共有されます（そのため app.example.com と api.example.com がサインインセッションを共有します）
• 警告: IP アドレスにはできません（ブラウザは無視します）

誰がサインアップできるかを制限する

3 つの許可リストの層が優先順位に従って組み合わされます。いずれか 1 つの層でも空でない値に設定されると、一致しないメールは拒否されます — ALLOW_SIGNUP=true でさえこれを上書きできません。

直感に反する部分: ALLOWED_EMAIL_DOMAINS=company.io + ALLOW_SIGNUP=true は「company.io または全員を許可」という意味ではなく、company.io のみを許可という意味です。許可リストの層は AND セマンティクスです — 完全な決定木はサインインとサインアップの設定 → サインアップ許可リストにあります。

招待フロー自体はサインアップ許可リストをチェックしません — ただし、招待された人は招待を承諾する前に依然としてサインインできる必要があります。すでに Multica アカウントを持っている場合（例: 別のワークスペースから）、許可リストの影響を受けずに直接承諾できます。一度もサインアップしたことがない場合、サインインの最初のステップ（検証コードの要求）は依然として許可リストのチェックを通過し、ALLOW_SIGNUP=false や ALLOWED_EMAILS / ALLOWED_EMAIL_DOMAINS によって拒否されたメールはサインアップを完了できず、したがって招待を承諾できません。

ワークスペース作成をロックダウンする

ALLOW_SIGNUP=false は新しいアカウントをブロックしますが、すでにサインイン済みのユーザーが POST /api/workspaces 経由で別のワークスペースを作成することはブロックしません。すべてのイシュー、リポジトリ、エージェントがプラットフォーム管理者に見えなければならないセルフホストインスタンスでは、そのギャップを塞ぐために DISABLE_WORKSPACE_CREATION=true を設定してください。

推奨されるブートストラップ手順:

1. DISABLE_WORKSPACE_CREATION を設定しないまま（デフォルト）インスタンスを起動します。
2. 管理者としてサインインし、共有ワークスペースを作成します。
3. DISABLE_WORKSPACE_CREATION=true を設定してバックエンドを再起動します。この時点から、ユーザーは招待によってのみ参加できます。

招待されたユーザーが最初の検証コードでサインアップを完了できるよう ALLOW_SIGNUP=true を維持したい場合は、DISABLE_WORKSPACE_CREATION=true を ALLOWED_EMAIL_DOMAINS / ALLOWED_EMAILS と組み合わせて、どのアドレスがサインアップできるかの範囲を指定してください。ALLOW_SIGNUP=false を設定すると、保留中の招待対象者がアカウントを作成すること自体も追加でブロックされます — すべてのメンバーがすでに Multica アカウントを持っているインスタンスでのみ有用です。

レート制限（任意の Redis）

公開 auth エンドポイント — /auth/send-code、/auth/verify-code、/auth/google — の前段には、IP ごとの固定ウィンドウのレート制限があります。リミッターは Redis によって支えられています。REDIS_URL を設定しない場合、ミドルウェアは no-op（fail-open）になり、バックエンドは起動時に rate limiting disabled: REDIS_URL not configured をログに記録します。

リクエストが制限を超えると、サーバーは 429 Too Many Requests、Retry-After: 60、そして本文 {"error":"too many requests"} で応答します。

この独立した RATE_LIMIT_TRUSTED_PROXIES は、オートパイロット webhook リミッター（/api/webhooks/autopilots/{token}）を制御する MULTICA_TRUSTED_PROXIES とは異なります。各リミッターは自身のリストをパースするため、プロキシの背後にあるデプロイは両方を設定すべきです。

デーモンのチューニングパラメータ

デーモンはユーザーのローカルマシン上で実行され、その設定もローカル環境変数から読み込まれます。一般的なものは次のとおりです。

デーモン設定を config.json に永続化する

上表の各デーモンキー — device_name、runtime_name、max_concurrent_tasks、poll_interval、heartbeat_interval、agent_timeout、codex_semantic_inactivity_timeout、codex_handshake_timeout、disable_auto_update、auto_update_check_interval — は、プロファイルの ~/.multica/config.json（もしくは ~/.multica/profiles/<name>/config.json）に永続化することもできます。これにより、daemon start のたびにフラグを再指定したり環境変数を export したりする必要がなくなります。

multica config set device_name my-vm-custom-name
multica config set runtime_name worker-a
multica config set max_concurrent_tasks 8
multica config set poll_interval 10s          # Go の期間、必ず > 0
multica config set heartbeat_interval 30s
multica config set agent_timeout 1h           # 0s を渡すと壁時計上限を明示的に無効化
multica config set codex_semantic_inactivity_timeout 15m
multica config set codex_handshake_timeout 45s
multica config set disable_auto_update true   # 単方向: 自動アップデートを無効化する用途のみ
multica config set auto_update_check_interval 12h

期間系キーは正の Go 期間（500ms、10s、1m30s など）のみを受け付けます。0s、負値、パース不能な文字列は config set の時点で拒否されます。ただし agent_timeout は例外で、ここでは 0s は「壁時計上限を明示的に無効化する」意味を持つ有効値です（負値はやはり拒否されます）。永続化した値をクリアして環境変数 / 組み込みデフォルトに戻すには空文字を渡してください: multica config set poll_interval ""。

disable_auto_update は単方向のブール値です。true にするとデーモンの CLI 自動アップデートを無効化し、false（もしくは "" でクリア）にすると判定を MULTICA_DAEMON_AUTO_UPDATE / cloud-vs-self-host のデフォルトに委ねます。config ファイルから自動アップデートを 強制的に有効化 することはできません。

優先順位は上から順に: daemon start の --flag > MULTICA_… 環境変数 > config.json > 組み込みデフォルト。systemd unit などで環境変数を設定するとファイルより優先され、明示的な CLI フラグは両者よりさらに優先されます。

--profile <name> で同一ホスト上に複数のデーモンを走らせるときに特に有用です。プロファイルごとに device_name を独立して設定すれば、Runtimes 画面でも共有ホスト名で潰れることなく別々の行として区別できます。

各パラメータがデーモンの動作にどう影響するかの完全な説明は、デーモンとランタイムを参照してください。

デフォルトのエージェント引数（MULTICA_<PROVIDER>_ARGS）

バックエンドに対してフリート全体のデフォルトとなる CLI フラグの層を設定します。各エージェントの custom_args を個別に編集することなく、デーモン上のすべてのエージェントにデフォルトのコスト・リソースのベースライン（例: --max-turns）を適用できる便利な手段です。これはデフォルトの層であり、超えられない上限ではありません。各エージェント自身の custom_args が後から追加され、これを上書きできます（下記の優先順位を参照）。

• 優先順位： デフォルト引数が先に適用され、その後に各エージェント自身の custom_args が追加されます。値を取るフラグについては、下流 CLI 自身の引数パーサーが最終的な勝者を決めます（多くのツールでは最後の出現が優先）。そのため個々のエージェントはデーモンのデフォルトを引き上げられますが、エージェントが上書きしない箇所ではデフォルトが引き続き有効です。
• パース： 値は POSIX シェルワード規則で分割されるため、クォートが使えます——MULTICA_CLAUDE_ARGS='--append-system-prompt "multi word"' は 2 つのトークンに解析されます。
• 安全性： デフォルト引数の層と各エージェントの custom_args の層は、いずれも同じ blocked-flags フィルターを通過します。そのためプロトコル上重要なフラグ（Claude の -p、--output-format、--input-format、--permission-mode、--mcp-config、および Codex の --listen など）はどちらの層からも注入できません。
• 未設定・空 の場合は動作に変化はありません。

フロントエンドのアクセス制御

GitHub 連携

GitHub PR ↔ イシュー連携には 2 つの必須変数が必要です。設定で Connect GitHub を有効にし、受信 webhook を受け付けるには両方を設定してください。さらに 2 つの任意変数を設定すると、インストール時点で連携先のアカウント名を取得できます。

いずれかの必須変数が設定されていない場合の動作:

• 設定 → GitHub の Connect GitHub が無効になり、admin に「not configured」というヒントを表示します。
• /api/webhooks/github エンドポイントは 503 github webhooks not configured を返します — Multica はすべての署名を有効として扱うのではなく、secret なしではイベント処理を拒否します。

任意の GITHUB_APP_ID / GITHUB_APP_PRIVATE_KEY が設定されていない場合の動作:

• インストール直後、接続カードには一時的に Connected to unknown と表示されます。GitHub から installation.created webhook が届くと（通常は数秒以内）、Multica は行を実際の組織名/ユーザー名に更新し、リアルタイムブロードキャストを発行するため、開いている Settings → GitHub タブは手動更新なしで反映されます。

注: GITHUB_WEBHOOK_SECRET はインストールフローの state token の署名キーとして再利用されるため、運用者は secret を 1 つだけ管理すればよいです。これは GitHub App の Client secret ではありません — Client secret は OAuth 関連であり、この連携では使われません。完全な手順は GitHub 連携 → セルフホストのセットアップを参照してください。

使用量分析

デフォルトでは、サーバーは Multica の公式 PostHog インスタンスにレポートします。オプトアウトするには ANALYTICS_DISABLED=true を設定してください。

次へ

• サインインとサインアップの設定 — 上記の auth 関連変数を実際にどう設定するか、そして落とし穴がどこにあるか
• GitHub 連携 — GITHUB_APP_SLUG / GITHUB_WEBHOOK_SECRET を支える GitHub App をどうセットアップするか
• トラブルシューティング — よくある設定ミスの症状と対処法
• デーモンとランタイム — MULTICA_DAEMON_* パラメータが実際に何をするか