環境変数
セルフホスト Multica でよく使うサーバー、ストレージ、連携、ランタイムの設定。
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 つ選ぶ必要があります。選ばない場合、認証コードと招待はサーバーログに書き込まれるだけです。
JWT_SECRET は本番環境で必須です。APP_ENV=production の場合、値が空または既知のプレースホルダーだとバックエンドが起動を拒否します(openssl rand -hex 32 で生成)。MULTICA_DEV_VERIFICATION_CODE も設定しないでください。
API とデータベース
| 変数 | デフォルト | 説明 |
|---|---|---|
DATABASE_URL | ローカルの multica データベース | PostgreSQL 接続文字列 |
DATABASE_MAX_CONNS | 25 | API プロセスあたりの最大データベース接続数 |
DATABASE_MIN_CONNS | 5 | API プロセスが保持する最小接続数 |
DATABASE_SEARCH_WORK_MEM_MB | 64 | 検索プランの各ノードに対する PostgreSQL work_mem 上限(MB)。1~64 で引き下げ、0 でデータベース/セッションの既定値を使用 |
DATABASE_REPLICA_URL | 空 | オプションの PostgreSQL 読み取り専用レプリカ接続文字列。新しい接続では読み取り専用状態が検証され、各機能はコードで結果整合性読み取りを明示的に選択する必要があります |
DATABASE_REPLICA_MAX_CONNS | 10 | API プロセスあたりの最大レプリカ接続数 |
DATABASE_REPLICA_MIN_CONNS | 0 | API プロセスが保持する最小レプリカ接続数 |
MULTICA_DATABASE_STARTUP_TIMEOUT | 3m | コンテナ起動時に migration と API が共有する、一時的なデータベース障害への再試行時間。0 にすると各フェーズで 1 回だけ試行します |
MULTICA_DATABASE_CONNECT_TIMEOUT | 5s | 起動時の接続試行ごとのフォールバックタイムアウト。pgx ネイティブの connect_timeout、PGCONNECT_TIMEOUT、service 設定が優先されます |
PORT | 8080 | API のリッスンポート |
JWT_SECRET | 本番環境で必須 | ログイン JWT と一部の署名フローに使うシークレット。本番では空または既知のプレースホルダーだと起動を拒否 |
APP_ENV | 空 | プロダクションでは production を設定 |
AUTH_TOKEN_TTL | 720h(30 日) | ブラウザ JWT と cookie の有効期間。Go duration または正の整数秒を受け付けます。セッションは有効期間の半分を過ぎるとスライド更新され、使い続けている限り失効しません。60s 未満は 60s に補正されます |
LOG_LEVEL | アプリのデフォルト | ログレベル |
MULTICA_SHUTDOWN_HOLD_DURATION | 0 | 終了シグナル受信後、グレースフルシャットダウンを開始するまでの待機時間 |
MULTICA_RUNTIME_RECONNECT_GRACE | 3h | オフラインのランタイムが処理中の作業を失敗させずに再接続できる猶予時間。150s 未満は 150s に補正されます |
Kubernetes で shutdown hold を設定する場合、terminationGracePeriodSeconds は hold と実際のシャットダウンにかかる時間の合計より大きくしてください。
primary とレプリカの接続上限は独立しています。全 API プロセスの合計が PostgreSQL クラスターの接続上限に収まるように設定してください。レプリカ接続はデフォルトで 5 分後に再作成され、昇格後に読み取り専用状態を再検証します。接続失敗時はインフラストラクチャが透過的に primary へフォールバックし、短時間のパッシブサーキットを開きます。バックグラウンドのデータベースプローブは追加されません。アプリケーションはレプリカデータの最大経過時間を保証しないため、データベース層でレプリケーション遅延を監視し、整合性が必要な読み取りは primary に残してください。
公開アドレスとブラウザアクセス
| 変数 | デフォルト | 説明 |
|---|---|---|
FRONTEND_ORIGIN | 空 | ユーザーがアクセスするフロントエンドの origin。CORS、cookie、招待リンクに使われます |
MULTICA_APP_URL | FRONTEND_ORIGIN にフォールバック | ユーザーが到達できる Web アドレス。CLI ログインとアカウント連携リンクが使います |
MULTICA_PUBLIC_URL | 空 | 公開 API アドレス。webhook URL とランタイム接続案内に使われます |
MULTICA_DAEMON_SERVER_URL | MULTICA_PUBLIC_URL、次に MULTICA_APP_URL / FRONTEND_ORIGIN にフォールバック | API プロセスが multica setup self-host コマンドに埋め込むサーバー URL。デーモンから到達する API URL が公開 webhook URL と異なる場合に設定します |
CORS_ALLOWED_ORIGINS | 空 | 追加で許可する HTTP origin。カンマ区切り |
ALLOWED_ORIGINS | CORS / フロントエンド設定にフォールバック | WebSocket origin の許可リスト。カンマ区切り |
COOKIE_DOMAIN | 空 | フロントエンドと API の host が異なり、ブラウザが API ドメインへ直接アクセスする場合は必須。単一ドメイン構成では空のまま |
MULTICA_DAEMON_SERVER_URL は認証なしの /api/config エンドポイントから返され、クライアントが読み取れます。公開設定として扱い、認証情報・トークンなどのシークレットを含めないでください。
フロントエンドと 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 を無視します。
セルフホストのデプロイでは FRONTEND_ORIGIN の設定が必須です。設定しないと、招待リンク、cookie のセキュリティ属性、WebSocket の origin 検証が実際のドメインと食い違うおそれがあります。
メールとログイン
Resend
| 変数 | デフォルト | 説明 |
|---|---|---|
RESEND_API_KEY | 空 | 設定すると Resend が有効になります |
RESEND_FROM_EMAIL | noreply@multica.ai | 送信元アドレス。検証済みドメインに属している必要があります |
SMTP
SMTP_HOST が空でない限り、SMTP が Resend より優先されます。
| 変数 | デフォルト | 説明 |
|---|---|---|
SMTP_HOST | 空 | SMTP ホスト。設定すると SMTP が有効になります |
SMTP_PORT | 25 | よく使う値: 25、587、465 |
SMTP_USERNAME | 空 | ユーザー名。匿名 relay では空のまま |
SMTP_PASSWORD | 空 | パスワード |
SMTP_FROM_EMAIL | RESEND_FROM_EMAIL にフォールバック | Envelope From とメールの From |
SMTP_TLS | starttls | implicit、smtps、ssl は暗黙的 TLS を意味します。465 では自動的に有効 |
SMTP_TLS_INSECURE | false | 証明書検証をスキップ。信頼できる内部ネットワーク専用 |
SMTP_EHLO_NAME | ホスト名 | 厳格な relay が要求する EHLO/FQDN |
Google OAuth
| 変数 | デフォルト | 説明 |
|---|---|---|
GOOGLE_CLIENT_ID | 空 | Google OAuth client ID |
GOOGLE_CLIENT_SECRET | 空 | Google OAuth client secret |
GOOGLE_REDIRECT_URI | http://localhost:3000/auth/callback | Google Console のコールバックアドレスと完全に一致している必要があります |
サインアップ範囲
| 変数 | デフォルト | 説明 |
|---|---|---|
ALLOW_SIGNUP | true | allowlist が一つも設定されていない場合に新規登録を許可するか |
ALLOWED_EMAILS | 空 | 登録を許可する完全なメールアドレス。カンマ区切り |
ALLOWED_EMAIL_DOMAINS | 空 | 登録を許可するメールドメイン。カンマ区切り |
DISABLE_WORKSPACE_CREATION | false | すべてのユーザーのワークスペース新規作成を禁止。owner/admin の例外はありません |
WORKSPACE_CREATION_ALLOWED_EMAILS | 空 | ワークスペースの新規作成を許可するメールアドレス(完全一致、カンマ区切り)。設定すると、それ以外のユーザーには 403 を返します。DISABLE_WORKSPACE_CREATION=true が優先されます。他のワークスペースへのアクセス権は付与しません |
MULTICA_DEV_VERIFICATION_CODE | 空 | 非 production 環境で使う固定 6 桁のテスト認証コード |
allowlist の正確な判定順序はログインとサインアップを参照してください。
添付ファイルストレージ
S3_BUCKET が未設定の場合、Multica はローカルディスクを使います。
| 変数 | デフォルト | 説明 |
|---|---|---|
MULTICA_MAX_PREVIEW_SIZE | 2MiB | テキストと HTML のオンラインプレビュー本文の上限。最大 16MiB。正の整数のバイト数、KB/KiB、MB/MiB(二進単位)を指定できます。16MiB を超える有効な値は 16MiB に制限され、不正な値はデフォルトに戻ります。上限を増やすと、特に構文ハイライトや Markdown の描画でブラウザーのプレビューが遅くなる場合があります。変更後は API を再起動してください。アップロードとダウンロードの制限は変わりません。 |
S3 または互換ストレージ
| 変数 | デフォルト | 説明 |
|---|---|---|
S3_BUCKET | 空 | バケット名。完全な hostname は指定しないでください |
S3_REGION | us-west-2 | バケットのあるリージョン |
AWS_ACCESS_KEY_ID | SDK デフォルトの資格情報チェーン | 静的な access key |
AWS_SECRET_ACCESS_KEY | SDK デフォルトの資格情報チェーン | 静的な secret key |
AWS_ENDPOINT_URL | 空 | MinIO などの S3 互換 endpoint |
S3_USE_PATH_STYLE | カスタム endpoint 時は true | path-style アドレスを使うか |
ATTACHMENT_DOWNLOAD_MODE | auto | auto、cloudfront、presign、proxy |
ATTACHMENT_DOWNLOAD_URL_TTL | 30m | 署名付きダウンロード URL の有効期間 |
AWS_ENDPOINT_URL が Google Cloud Storage を指す場合、Accept-Encoding はリクエスト署名から自動的に除外されます。
内部ネットワークの MinIO など、ブラウザから endpoint に直接到達できない場合は ATTACHMENT_DOWNLOAD_MODE=proxy を使ってください。
ローカルディスク
| 変数 | デフォルト | 説明 |
|---|---|---|
LOCAL_UPLOAD_DIR | ./data/uploads | ファイルと metadata の保存ディレクトリ。永続ボリュームが必要です |
LOCAL_UPLOAD_BASE_URL | 空 | 任意の公開 base URL。空の場合はアプリ内の相対アドレスを返します |
CloudFront
| 変数 | 説明 |
|---|---|
CLOUDFRONT_DOMAIN | CDN ドメイン |
CLOUDFRONT_KEY_PAIR_ID | CloudFront key pair ID |
CLOUDFRONT_PRIVATE_KEY | 完全な秘密鍵 |
CLOUDFRONT_PRIVATE_KEY_SECRET | Secrets Manager から秘密鍵を読み込む場合に使用 |
Redis とレート制限
| 変数 | デフォルト | 説明 |
|---|---|---|
REDIS_URL | 空 | 共有レート制限、リアルタイムイベント、チャンネル WebSocket リース、token cache など、すべての Redis 機能が使用する唯一の接続 URL |
REDIS_CLUSTER_MODE | false | true にすると、REDIS_URL が単一の設定エンドポイントでも Redis Cluster クライアントを使用します。クラスターモードではデータベース 0 と REALTIME_RELAY_MODE=sharded が必要です |
REDIS_DISABLE_CLIENT_NAME | false | マネージド Redis が CLIENT SETNAME を禁止している場合に true を設定 |
RATE_LIMIT_AUTH | 5 | 認証コード送信または Google ログイン開始の、IP あたり毎分の回数 |
RATE_LIMIT_AUTH_VERIFY | 20 | 認証コード検証の、IP あたり毎分の回数 |
RATE_LIMIT_INVITATION_ACTOR_10M | 10 | 招待者ごとの 10 分間スライディングウィンドウ内のワークスペース招待数。0 でこの制限を無効化 |
RATE_LIMIT_INVITATION_WORKSPACE_24H | 50 | ワークスペース内の全管理者による 24 時間スライディングウィンドウ内の招待総数。0 でこの制限を無効化 |
RATE_LIMIT_INVITATION_RECIPIENT_24H | 6 | 正規化された同一受信メールアドレスがワークスペースをまたいで 24 時間スライディングウィンドウ内に受け取れる招待数。0 でこの制限を無効化 |
RATE_LIMIT_TRUSTED_PROXIES | 空 | X-Forwarded-For の提供を許可するプロキシ CIDR。カンマ区切り |
MULTICA_TRUSTED_PROXIES | 空 | オートパイロット webhook とリアルタイム接続が使う信頼済みプロキシ CIDR |
リバースプロキシ配下のデプロイでは、実際のプロキシのネットワーク範囲を設定してください。すべての送信元を無条件に信頼してはいけません。クライアントが転送元 IP を偽装できてしまいます。
認証レート制限には REDIS_URL が必要です。未設定の場合、起動ログに認証レート制限が無効であることが表示されます。招待制限は Redis なしでもプロセス内メモリで動作し、Redis を設定すると複数レプリカで割り当てを共有します。設定済みの Redis が一時的に利用できない場合、認証レート制限はフェイルオープンしますが、招待作成は保護なしでメールを送らず、再試行可能な 503 を返します。
外部連携
| 連携 | 変数 | 説明 |
|---|---|---|
| GitHub | GITHUB_APP_SLUG | GitHub App の slug |
| GitHub | GITHUB_WEBHOOK_SECRET | Webhook HMAC と接続 state の署名シークレット |
| GitHub | GITHUB_APP_ID | PR カードの CI ステータス・マージ可否と「GitHub から選択」リポジトリに必要です |
| GitHub | GITHUB_APP_PRIVATE_KEY | App ID と対になる完全な PEM 秘密鍵。用途は同上 |
| Lark | MULTICA_LARK_SECRET_KEY | base64 エンコードされた 32 バイトの資格情報暗号化キー |
| Slack | MULTICA_SLACK_SECRET_KEY | base64 エンコードされた 32 バイトの token 暗号化キー |
| Telegram | MULTICA_TELEGRAM_SECRET_KEY | base64 エンコードされた 32 バイトの Bot token 暗号化キー |
| Telegram | MULTICA_TELEGRAM_TOOL_PROGRESS | ストリーミング返信に表示するツールのステップ。auto(既定。DM では詳細、グループでは作業の種類のみ)、off、summary、detail |
| Composio | COMPOSIO_API_KEY | Composio ツール接続を有効化 |
| Composio | COMPOSIO_CALLBACK_BASE_URL | コールバック API アドレス。MULTICA_PUBLIC_URL にフォールバック可能 |
| Composio | COMPOSIO_STATE_SECRET | OAuth state の署名シークレット。JWT_SECRET から派生可能 |
| セルフホスト Git | MULTICA_VCS_INTEGRATION_ENABLED | Forgejo/Gitea/GitLab 連携のスイッチ。compose ではデフォルトで有効 |
| セルフホスト Git | MULTICA_VCS_SECRET_KEY | base64 エンコードされた 32 バイトの暗号化キー(openssl rand -base64 32)。未設定の場合、この機能全体が利用できません |
| Plugins | MULTICA_PLUGIN_SECRET_KEY | 保存済み secret と surface 起動 URL を暗号化する base64 形式の 32 バイト鍵 |
| Plugins | MULTICA_PLUGIN_SURFACE_ORIGIN | バックエンドへルーティングする Cookie なしの専用 origin。app/API origin と分離し、Host を保持すること |
| Plugins | MULTICA_PLUGIN_API_URL | バージョンを含む Plugin Public API の完全な Base URL(例: https://plugin-api.example.com/v1)。未設定時は MULTICA_PUBLIC_URL + /v1 |
| Plugins | MULTICA_PLUGIN_DIR | 開発時にローカル plugin bundle を公開するための任意の絶対ディレクトリ |
| テーマストア | MULTICA_THEME_REGISTRY_URL | 公式レジストリの fork など、別のレジストリの index.json。テーマと外観を参照 |
GITHUB_APP_ID と秘密鍵を設定しなくても、PR の関連付け・ミラー・マージ時のステータス変更は通常どおり動きますが、カードに CI とマージ可否のステータスが表示されず、「GitHub から選択」のリポジトリ入口も無効になります。
設定手順は GitHub 連携、Lark Bot、Slack Bot、Telegram Botを参照してください。
サーバーサイド LLM
このグループは、会話タイトルなどサーバー側の補助生成機能の設定です。エージェントの実行時に使う AI コーディングツールの資格情報ではありません。
| 変数 | デフォルト | 説明 |
|---|---|---|
MULTICA_LLM_API_KEY | 空 | OpenAI 互換の API key |
MULTICA_LLM_BASE_URL | 空 | OpenAI 互換の endpoint |
MULTICA_LLM_DEFAULT_MODEL | gpt-6-luna | リクエストがモデルを指定しない場合に使用 |
MULTICA_LLM_MAX_RETRIES | 2 | 1 回の呼び出しあたりのリトライ上限。0 はリトライ無効、1〜5 は最大 N 回 |
MULTICA_LLM_DISABLE_THINKING | false | すべてのリクエストに chat_template_kwargs: {"enable_thinking": false} を付加。このフィールドを解釈する gateway 用 |
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 系モデルと GPT-6 Luna はフォローアップ質問のリクエストではサーバーが既に reasoning_effort: none を付けます。チャットの自動タイトル生成は推論フィールドを送信しません。本設定がそれに影響するのは、構成された上流が chat_template_kwargs を受け付ける場合だけです。指定できる値は true/false と 1/0(大文字小文字を区別しない)で、それ以外は起動に失敗します。起動ログにはリトライポリシーと併せて有効な状態が記録されます。
このレイヤーを使う機能は 2 つあり、どちらも設定した endpoint にチャットの内容を送信します。
- 会話タイトルの自動生成 — 新しいチャットセッションでユーザーが最初に送ったメッセージを、そのまま送信します。添付ファイルは含まれません。
- フォローアップ質問(エージェントの返信の下に表示されるボタン) — 会話の末尾を送信します。最大 6 メッセージで、対象の返信は 3000 文字、それより古いメッセージは各 800 文字が上限です。
API key と base URL の両方が空の場合、このレイヤーは無効になり、上流へのリクエストを一切行いません。上記 2 つの機能はどちらも何も送信しなくなります。このレイヤーからチャットの内容をデプロイ外へ出せないポリシーでは、これがサポートされた構成です。セッションはクライアントが最初のメッセージから生成したタイトルをそのまま使い、フォローアップ質問のボタンは表示されず、他の機能への影響はありません。
これは補助生成レイヤーのみに関する説明です。エージェントの実行は別のデータ経路です。エージェントがチャットに応答するとき、デーモンはそのエージェントの AI コーディングツールをツール自身の資格情報で実行し、上記の MULTICA_LLM_* 設定をツールへ渡すことはありません。(エージェント自身が必要とする実行単位の Multica 接続用変数は、デーモンが別途注入します。)上記の変数を空にしてもこの経路には影響しないため、エージェントのランタイム設定側で制御してください。
デーモン設定
以下の変数は、エージェントを実行するコンピューター上で読み込まれます。API コンテナ内ではありません。
| 変数 | デフォルト | 説明 |
|---|---|---|
MULTICA_SERVER_URL | ws://localhost:8080/ws | Multica API / WebSocket アドレス。http(s) も受け付けます |
MULTICA_DAEMON_DEVICE_NAME | ホスト名 | ランタイム一覧に表示されるデバイス名 |
MULTICA_AGENT_RUNTIME_NAME | Local Agent | ランタイムの表示名 |
MULTICA_DAEMON_POLL_INTERVAL | 30s | ウェイクイベントがないときの実行ポーリング間隔 |
MULTICA_DAEMON_WS_CLAIM_POLL_INTERVAL | 3m | 正常な WebSocket での claim 安全ポーリング上限。MULTICA_DAEMON_POLL_INTERVAL とは独立して設定され、下方向のジッターにより既定値は実際には 2m30s–2m45s となり、旧 Server または結果が不確実な claim では通常のポーリング間隔を維持します |
MULTICA_DAEMON_HEARTBEAT_INTERVAL | 15s | ハートビート間隔 |
MULTICA_DAEMON_MAX_CONCURRENT_TASKS | 20 | デーモン 1 つあたりの同時実行上限 |
MULTICA_AGENT_TIMEOUT | 0 | 1 回の実行の絶対時間上限。0 は上限なし |
MULTICA_AGENT_IDLE_WATCHDOG | 2h | 出力もツール実行もない状態の静穏上限。0 で watchdog 全体を無効化 |
MULTICA_AGENT_TOOL_WATCHDOG | MULTICA_AGENT_IDLE_WATCHDOG と同じ | 単一のツール呼び出しが静穏なままでいられる上限。モデルより長い余裕をツールに与えたい場合のみ設定し、0 はツール実行中に強制停止しません。Cursor のバックグラウンドシェルは、起動したプロセスが終了するまで実行中として扱われます。この上限に達すると、デーモンはそれらのプロセスを停止し、Cursor が最終結果を出すための新しい watchdog 予算を与えます。プロセスの所有権やクリーンアップを検証できない場合は、通常の実行キャンセル方針に従います |
MULTICA_OPENCODE_IDLE_WATCHDOG | 10m | OpenCode 専用の静穏しきい値 |
MULTICA_CODEX_SEMANTIC_INACTIVITY_TIMEOUT | MULTICA_AGENT_IDLE_WATCHDOG と同じ | Codex のセマンティック静穏しきい値。Codex 自身のタイマーはツール実行中かどうかを判別できないため、独自の短い上限を持たず idle / tool 予算の大きい方に追従します |
MULTICA_CODEX_FIRST_TURN_TIMEOUT | 0 | Codex 初回ターンの無進捗上限を明示的に上書き;0 はデフォルトを維持。実効の初回ターン待機は依然として MULTICA_CODEX_SEMANTIC_INACTIVITY_TIMEOUT と全体の実行タイムアウトに制限される——MULTICA_CODEX_SEMANTIC_INACTIVITY_TIMEOUT をこの値より厳密に大きく(余裕を持たせて)設定すること。さもないと待機はその値で打ち切られ、モデルカタログの起動リトライがスキップされる。同値では不十分:セマンティックタイマーが先に起動するため、同値の場合でもリトライが失われることがある |
MULTICA_CODEX_HANDSHAKE_TIMEOUT | 30s、thread/start・thread/resume:60s | Codex app-server 起動ハンドシェイクの上限。明示的な値は両方の予算を一括で上書きします |
MULTICA_CODEX_MEMORY | オフ | 1、true、yes、on のいずれかにすると、デーモンが管理する Codex の実行で Codex ネイティブのメモリを残します。既定では実行ごとにオフになります。Codex のネイティブメモリとサブエージェントを参照 |
MULTICA_CODEX_MULTI_AGENT | オフ | 値は同上。Codex ネイティブのサブエージェントを残します。親スレッドが終わった時点で実行は終了扱いになり、サブエージェントがまだ返していない結果は失われます |
MULTICA_CODEX_TURN_INTERRUPT_TIMEOUT | 2s | キャンセル後に Codex app-server が turn/interrupt を確認し turn/completed を送信するまでの猶予時間。プロセスを強制終了する前に最終トークン使用量を保持します。特に遅いホストでは daemon ログに記録された割り込み遅延を基に調整できます |
MULTICA_DAEMON_AUTO_UPDATE | Cloud は true、セルフホストは false | CLI の更新を自動でチェックして適用するか |
MULTICA_DAEMON_AUTO_UPDATE_INTERVAL | 6h | 更新チェックの間隔 |
MULTICA_DAEMON_AUTO_RELOAD | true | 帯域外で置き換えられた multica バイナリ(brew upgrade、再ダウンロード、ローカルビルド)へ再起動して追従するかどうか。MULTICA_DAEMON_AUTO_UPDATE とは独立 |
MULTICA_WORKSPACES_ROOT | ~/multica_workspaces | 実行用作業ディレクトリのルート |
MULTICA_AGENT_TEMP_BASE | /tmp(Linux/macOS) | Linux/macOS 専用。作業ごとのプライベート一時ディレクトリの親ディレクトリ。既存かつ書き込み可能な絶対パスである必要があり、無効な値の場合は /tmp にフォールバックせず作業の開始に失敗します。短いパスを選んでください。子ツールがその配下に AF_UNIX ソケットを作成する場合があり、sun_path の上限は Linux で 108 バイト、macOS で 104 バイトです |
デーモンがエージェント作業に注入する内部コンテキストについては、作業ランタイム環境を参照してください。MULTICA_REPO_CHECKOUT_MODE もその一つです。デーモンは Linux と Windows の Codex 実行でだけ isolated を設定し、手動では設定できません。デーモン自身の環境にある MULTICA_* 変数は実行に引き継がれません。
優先順位はコマンドラインフラグ → 環境変数 → ~/.multica/config.json → 組み込みデフォルトです。watchdog の動作はデーモンとランタイムを参照してください。
クリーンアップと保持
デーモンは実行ディレクトリ、リポジトリキャッシュ、セッション記録、一時ディレクトリを定期的に片付けます。何がいつ削除されるかはクリーンアップと保持を参照してください。期間は Go の duration 形式に加えて、日数の d(14d、1d12h など)も使えます。
| 変数 | デフォルト | 説明 |
|---|---|---|
MULTICA_GC_ENABLED | true | false または 0 でクリーンアップ全体を止める |
MULTICA_GC_INTERVAL | 2h | クリーンアップの間隔。デーモン起動の約 30 秒後に最初の 1 回を実行 |
MULTICA_GC_TTL | 24h | タスクが done または closed カテゴリに入ってから、またはチャットセッションがアーカイブされてから、実行ディレクトリを削除するまでの時間 |
MULTICA_GC_COMPLETED_TASK_TTL | 14d | 実行完了後、管理対象のタスクディレクトリを削除するまでの時間。ローカルディレクトリ実行は codex-home のみ削除し、daemon ログ、出力、外部のセッションを保持。ローカル履歴を持つ home は保持。0 で無効 |
MULTICA_GC_ORPHAN_TTL | 72h | 持ち主が見つからないディレクトリを、変更がないまま何時間経ったら削除するか |
MULTICA_GC_ARTIFACT_TTL | 12h | 実行終了からデーモンが再生成できる内容を削除するまでの時間。次の行のパターンは、まだ閉じていないタスクと、管理対象の作業ディレクトリを使う未アーカイブのチャットに適用される。デーモンが管理する Codex キャッシュにも同じ時間が適用される。0 でこれらのキャッシュを保持する |
MULTICA_GC_ARTIFACT_PATTERNS | node_modules,.next,.turbo | 再生成できるとみなすディレクトリ名(カンマ区切り)。設定するとデフォルトの一覧を置き換えるため、デフォルトも残したいなら一緒に書く。/ や \ を含む項目は無視される |
MULTICA_GC_REPO_TTL | 30d | どこからも参照されず worktree も残っていないベアリポジトリキャッシュを、チェックアウトがないまま何日経ったら削除するか。0 で削除しない |
MULTICA_GC_REPO_MAINTENANCE_ENABLED | true | 古いエージェントブランチを消したあと、リポジトリキャッシュに git reflog expire と git gc を実行するか。false でこの手順だけを止める |
MULTICA_GC_CODEX_SESSION_TTL | 14d | 使われていない Codex セッション記録を削除するまでの時間。0 で削除しない |
MULTICA_GC_HERMES_SESSION_TTL | 14d | 使われていない Hermes セッション記録を削除するまでの時間。0 で削除しない |
MULTICA_GC_HERMES_MEMORY_TTL | 90d | 使われていない Hermes メモリを削除するまでの時間。0 で削除しない |
MULTICA_GC_TASK_TEMP_LEGACY_TTL | 0 | 古いデーモンが残した、実行ロックのない一時ディレクトリだけが対象。変更がないまま何時間経ったら削除するか。0 で削除しない。実行ロックのある一時ディレクトリは実行終了時に削除され、この設定の影響を受けない |
デーモンのログ
デーモンがバックグラウンドで(ターミナルにつながずに)動いているとき、ログは ~/.multica/daemon.log(名前付きプロファイルでは ~/.multica/profiles/<name>/daemon.log)に書かれ、サイズでローテーションされます。ローテーション後のファイルは gzip で圧縮されます。
| 変数 | デフォルト | 説明 |
|---|---|---|
MULTICA_DAEMON_LOG_MAX_SIZE_MB | 20 | daemon.log をローテーションするサイズ(MB) |
MULTICA_DAEMON_LOG_MAX_BACKUPS | 5 | 残すローテーション済みファイルの最大数 |
MULTICA_DAEMON_LOG_MAX_AGE_DAYS | 30 | ローテーション済みファイルを残す日数 |
3 つとも正の整数を取ります。0、負の数、解釈できない値はデフォルトとして扱われ、「無制限」にはなりません。ローテーション済みファイルは、個数と日数のどちらかの上限に先に達した時点で削除されます。クラッシュ時の出力は同じディレクトリの daemon.err.log に書かれ、起動時に 5 MB を超えていれば daemon.err.log.1 に名前が変わります。
ツールごとのパス、モデル、引数
組み込みの各ツールにはパス変数 MULTICA_<PREFIX>_PATH があります。設定すると、デーモンは PATH からコマンドを探す代わりにそのパスを使います。パスが存在しない場合、そのツールは登録されず、PATH 上の同名コマンドに切り替わることもありません。多くのツールにはモデル変数 MULTICA_<PREFIX>_MODEL もあり、エージェントでモデルが選ばれていないときにこのコンピューターの既定モデルとして使われます。どちらも空ならモデルは渡されず、ツール自身が決めます。
QwenPaw と MiniMax Code には、Multica がモデルを渡さないためモデル変数がありません。詳しくは AI コーディングツール比較を参照してください。DeepSeek Harness には MULTICA_DSH_PROFILE_BUNDLE と MULTICA_DSH_PLUGIN_PATH もあり、次のセクションで説明します。
マシン全体のデフォルト引数 MULTICA_<PREFIX>_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 40DeepSeek Harness のプロファイルのインストール
MULTICA_DSH_PROFILE_BUNDLE は、multica プロファイルが存在しない場合にインストールするバンドルを指定します。カンマ区切りで複数の候補を順に試し、各項目は npm のパッケージ名、ディレクトリ、またはパック済み tarball です。既定では未設定です。Multica が利用する --stdio プロトコルはこのプロファイルが提供するため、未設定の場合は DSH のインストールには手を加えず、デーモンは使用できないランタイムを登録せずにプロファイルの欠落を報告します。
Multica 自身のブリッジはまだ公開 npm レジストリにないため、値の選び方はエージェントランタイムのインストールを参照してください。ここに設定した値は追加の確認なしに各デーモンホストの DSH ホームへインストールされるので、サプライチェーンの判断として扱ってください。
このインストールは範囲を意図的に限定しています。実行はデーモンのライフタイムにつき最大 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 が使われます。
Cursor のバックグラウンドプロセスのクリーンアップ
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 に書き込むこともできます。名前付きプロファイルの設定ファイルは ~/.multica/profiles/<name>/config.json にあります:
multica config set poll_interval 10s
multica config showサポートされるキー:
| キー | デフォルト | 説明 |
|---|---|---|
server_url | ws://localhost:8080/ws | Multica API / WebSocket アドレス |
app_url | 空 | ブラウザログインに使う Web アドレス |
workspace_id | 空 | デフォルトのワークスペース |
device_name | ホスト名 | ランタイム一覧に表示されるデバイス名 |
runtime_name | Local Agent | ランタイムの表示名 |
workspaces_root | ~ 配下のプロファイル別パス | 実行用作業ディレクトリのルート |
max_concurrent_tasks | 20 | 同時実行上限。0 または空は未設定を意味します |
poll_interval | 30s | 実行のポーリング間隔 |
ws_claim_poll_interval | 3m | 正常な WebSocket での claim 安全ポーリング上限。poll_interval とは独立して設定され、Daemon は下方向のジッターを適用します |
heartbeat_interval | 15s | ハートビート間隔 |
agent_timeout | 無制限 | 1 回の実行の絶対時間上限 |
agent_idle_watchdog | 2h | ツール実行中でないときの静穏上限。0s でデーモンの watchdog 全体を無効化し、agent_tool_watchdog も効かなくなります |
agent_tool_watchdog | agent_idle_watchdog と同じ | ツール実行中の静穏上限。0s にするとデーモンの watchdog は静穏なツール呼び出しを理由に実行を停止しなくなり、実行の上限は agent_timeout(デフォルトは無制限)だけになります |
codex_semantic_inactivity_timeout | 派生値 | Codex のセマンティック静穏しきい値。未設定なら idle と tool の watchdog 予算のうち大きい方を採用し、tool 予算が 0 の場合は idle 予算に回帰します。Codex 自身の 10m が残るのは watchdog 一式を無効化したときだけです |
codex_handshake_timeout | 30s、thread/start・thread/resume:60s | Codex app-server 起動ハンドシェイクの上限。明示的な値は両方の予算を一括で上書きします |
disable_auto_update | 環境に従う | true で自動更新を無効化。false はローカルの上書きをクリアし、環境変数またはデフォルトに戻します |
auto_update_check_interval | 6h | 更新チェックの間隔 |
disable_auto_reload | 環境に従う | true でディスク上の置き換えへの追従を停止。false はローカルの上書きをクリア。disable_auto_update とは別に解決されます |
値のルール:
- duration 系のキーは正の Go duration(
10s、2hなど)を受け付け、負の値は常に拒否されます。0sも受け付けるのはagent_timeout、agent_idle_watchdog、agent_tool_watchdogだけです。agent_timeoutの0sは実行時間上限を明示的に無効化します。watchdog の 2 キーで0sが何を無効にするかは表を参照してください。 - 空文字列を渡すと永続化された値がクリアされ、環境変数または組み込みデフォルトに戻ります。例:
multica config set poll_interval ""。 max_concurrent_tasksには非負の整数が必要です。- 相対パスの
workspaces_rootは保存時に絶対パスへ変換されます。
可観測性と分析
| 変数 | デフォルト | 説明 |
|---|---|---|
DO_NOT_TRACK | 空(テレメトリー有効) | 1 または true(大文字小文字を区別しない)で、ファーストパーティの匿名セルフホストテレメトリーの収集と送信を停止 |
ANALYTICS_DISABLED | false | true で PostHog への送信を無効化 |
POSTHOG_API_KEY | 空 | 未設定の場合は分析送信が無効。自前の PostHog プロジェクトを使う場合に設定 |
POSTHOG_HOST | https://us.i.posthog.com | PostHog アドレス |
METRICS_ADDR | 空 | Prometheus metrics のリッスンアドレス。空なら起動しません |
REALTIME_METRICS_TOKEN | 空 | /health/realtime を保護する bearer token |
ファーストパーティのセルフホストテレメトリーは、UTC 日ごとにデプロイ単位のスナップショットを、固定かつ設定変更不可の https://telemetry.multica.ai/v1/telemetry/events へ送信します。正式リリース版、ワークスペース数・重複を除いたメンバー数・アクティブなエージェント数・過去 24 時間のアクティブなデーモン数のバケット、および過去 24 時間に開始・完了・失敗・キャンセルされた実行の集計値、そして過去 1・7・28 完全 UTC 日にサインインして Web 版またはデスクトップ版を開いたメンバー数と、自分でエージェントの実行を開始した(割り当て、メンション、コメント、チャット、手動実行、再実行。autopilot やエージェント間の委任は含まない)メンバー数のバケットだけを含みます。メンバーはデプロイ内でのみ数えられ、識別されることはありません。名前、メールアドレスやドメイン、IP、業務 ID、ホストやデバイス情報、リポジトリ、モデルや plugin、prompt/output、コメントやチャット、ファイルパス、token/費用、認証情報、エラー、stack、ログは送信しません。このデータはセルフホスト版の採用状況、デプロイ規模、集計利用量、メンバーの利用状況の把握だけに使われ、課金、ライセンス、認証、セキュリティ判断には使われません。
DO_NOT_TRACK と ANALYTICS_DISABLED は独立しています。前者はこの匿名スナップショットを、後者は任意の PostHog 連携を制御します。
次のステップ
- ログインとサインアップ — ログイン方式とサインアップ制限。
- トラブルシューティング — デプロイ問題の症状別診断。
- デーモンとランタイム — デーモン側の対応する設定。