環境
タスクの実行が起動した開発サーバーやアプリをタスクのサイドバーで確認し、.multica/environments.toml に宣言して、メンバーがサイドバーから起動・停止・ログ確認できるようにします。
エージェントが Web アプリを扱うと、成果は開いて確かめるものになりがちです。開発サーバー、プレビュー、デスクトップアプリなどです。タスクのサイドバーの環境セクションには、そのタスクの実行が動かしているものが、動いているマシンごとにまとめて表示され、それぞれを開けます。
環境が表示される経路は 2 つあります。
| 自動検出 | 宣言 | |
|---|---|---|
| どこから来るか | 実行のディレクトリ内で待ち受けているサーバーをデーモンが見つける | リポジトリが .multica/environments.toml に記述し、エージェントが multica env start で起動する |
| 準備 | 不要 | リポジトリにファイルを追加する |
| 実行が終わったあと | プロセスが動いている間は表示され続ける | 停止されるか TTL が切れるまでデーモンが管理する |
| サイドバーでできること | 開く、URL をコピー、停止 | 開く、URL をコピー、起動、停止、再起動、ログを表示 |
自動検出のおかげで、設定なしでもこのセクションは役に立ちます。宣言すると環境を再現できるようになります。どの実行でも同じ方法で、専用のポートで起動し、ログもサイドバーから読めます。
自動検出されるサーバー
macOS と Linux では、デーモンが約 30 秒ごとに TCP ポートで待ち受けているプロセスを調べます。次の条件を満たすプロセスがサイドバーに表示されます。
- 作業ディレクトリが、そのタスクのいずれかの実行のディレクトリ内にある
- 2 回続けてスキャンで見つかった（一瞬だけ動くテスト用サーバーは表示されません）
次のものは対象外です。
- AI コーディングツール自体と
multicaCLI - プロジェクトのローカルディレクトリから動いているサーバー（実行ではなく、あなたが起動したものです）
- すでに宣言された環境に属しているサーバー（その環境の下に 1 回だけ表示されます）
- チャットセッションなど、タスクに紐づかない実行のサーバー
デスクトップアプリ（Electron アプリなど）は、ポートごとではなく 1 つのアプリとして表示されます。URL はなく、同じマシンの Multica Desktop でウィンドウに切り替えを押すと前面に出せます。リモートデバッグ用のポートはリンクとして表示されません。
自動検出されたサーバーは、実行が終わっても待ち受けている間は表示され続けます。メンバーはサイドバーから停止できますが、デーモンは起動方法を知らないため、ログはなく再起動もできません。それらが必要なら宣言してください。
環境を宣言する
リポジトリのルートに .multica/environments.toml を追加し、実行がチェックアウトするブランチにコミットします。サイドバーはチェックアウトのルートか、その 1 つ下のディレクトリにあるファイルだけを見つけ、エラーのあるファイルは読み飛ばします。何が問題かは multica env start が表示します。[environments.<name>] テーブル 1 つが 1 つの環境です。
[environments.web]
label = "Web app"
start = "npm ci && npx vite --port $MULTICA_PORT --strictPort"
ttl = "24h"エージェントは自分のチェックアウトの中からこれを起動します。
multica env start webコマンドは環境が応答するまで待ってから URL を表示します。環境はサイドバーに表示され、実行が終わっても動き続け、TTL が切れると停止します。
フィールド
| フィールド | 必須 | 既定値 | 意味 |
|---|---|---|---|
start | はい | 環境を起動するシェルコマンド。.multica/ を含むディレクトリで /bin/sh -c により実行されます。 | |
label | いいえ | 環境名 | サイドバーに表示される名前。 |
url | いいえ | http://localhost:$MULTICA_PORT | メンバーが開くアドレス。ワーカーやデスクトップアプリなどページのないものは url = "" にします。 |
ready | いいえ | url と同じ | 500 未満のステータス（404 を含む）が返るまで確認するアドレス。ready も url もない場合は、start が起動した時点で実行中になります。 |
stop | いいえ | デーモンがプロセスにシグナルを送る前に実行するコマンド。コンテナなど、start のプロセスが所有しないものを作る場合に使います。 | |
ttl | いいえ | 24h | 停止されるまでの時間。1m から 168h まで。単位は s、m、h で、7d は使えません。 |
環境名は environments. のあとの部分です。小文字、数字、-、_ が使え、先頭は英字か数字、最大 40 文字です。
ポートと変数
各環境には専用の空きポートが 10 個割り当てられます。MULTICA_PORT から MULTICA_PORT+9 までです。同じマシンの 2 つの実行や 2 つのタスクがぶつかることはないので、ポートを固定で書かないでください。
start と stop には次の変数が渡されます。
| 変数 | 値 |
|---|---|
MULTICA_PORT | ポート範囲の先頭。例: 41000 |
MULTICA_ENVIRONMENT | 環境名 |
PATH | multica env start を実行したエージェントの PATH。リポジトリのツールチェーンが見つかるようにするためです。サイドバーから起動した場合は、そのタスクでエージェントがその環境に最後に使った PATH を使います。 |
デーモンの環境変数も引き継ぎますが、MULTICA_* 変数（認証情報を含む）は除かれます。環境が実行の権限で操作することはできません。url と ready で置き換えられるのは $MULTICA_PORT（または ${MULTICA_PORT}）だけです。2 つ目のポートが必要なら、API_PORT=$((MULTICA_PORT + 1)) のようにシェルで計算します。
start はフォアグラウンドで動かす
start は新しいプロセスグループのリーダーとして実行されます。グループ内にプロセスが 1 つでも残っている間は環境が続き、停止するとグループ全体にシグナルが送られます。そのため:
- メインのサーバーはフォアグラウンドで動かします。
&でバックグラウンドに置いた補助プロセスは問題ありません。同じグループに残ります。 docker compose up -d、システムサービス、setsidなど、グループの外に処理を渡さないでください。環境はすぐに終了になり、停止してもその処理には届きません。こうしたツールはフォアグラウンドで動かし、stopコマンドを追加します。- 実行のチェックアウトには依存関係がインストールされていません。
startの中でインストールしてください。デーモンが準備完了を待つ 10 分にはその時間も含まれます。
例
それぞれが .multica/environments.toml の全体です。npm ci は、リポジトリに合わせてパッケージマネージャーのインストールコマンド（pnpm install --frozen-lockfile、yarn install --immutable）に置き換えてください。
[environments.web]
label = "Web app"
start = "npm ci && npx next dev --port $MULTICA_PORT"
ttl = "24h"複数の環境を宣言するには、同じファイルにテーブルを追加します。各環境のプロセスはその環境と一緒に止まります。同じチェックアウトの別の環境がそれを使っていても同じです。Web アプリとその API のように一緒に動き続ける必要があるサーバーは、Web + API の例のように 1 つの環境にまとめてください。
CLI で起動・停止する
| コマンド | 内容 |
|---|---|
multica env start <name> | カレントディレクトリか親ディレクトリで見つかった .multica/environments.toml から環境を起動します。準備ができるまで待ち、URL を表示します。このタスクで同じ名前の環境が同じチェックアウトから動いていれば、それをそのまま返します。 |
multica env start <name> --wait=false | 起動したらすぐに戻ります。 |
multica env list | このマシンにあるこのタスクの環境を、状態、URL、ログのパスとともに一覧表示します。 |
multica env stop <name> | このマシンで動いている、このタスクの同じ名前の環境を停止します。stop コマンドがあれば実行し、残ったプロセスに SIGTERM、10 秒後に SIGKILL を送ります。同じ名前のものが複数動いている場合はそのうち 1 つを止めます。特定のものを止めるにはサイドバーを使ってください。 |
いずれも --output json に対応しています。multica environment は multica env の長い形式です。
これらのコマンドは実行中のタスクの認証情報を使うため、エージェントの実行の中でしか使えません。自分のターミナルで実行すると MULTICA_DAEMON_PORT not set で失敗します。自分で起動・停止するにはサイドバーを使います。
起動コマンドが準備完了前に終了すると、multica env start は失敗し、ログの最後の数行を表示します。10 分経っても応答がない場合、コマンドは戻り、環境は起動中のまま、理由（"not answering at http://localhost:41000" など）が表示されます。
環境は個々の実行ではなくタスクに属します。同じタスクのあとの実行は、前の実行が起動した環境を一覧・停止できます。同じ名前でもう一度起動したときに既存の環境が再利用されるのは、このマシンで同じチェックアウトから動いている場合だけです。別のチェックアウトを使う実行は同じ名前で 2 つ目を専用のポートで起動するため、起動前に multica env list で確認してください。
サイドバーで管理する
各環境には、状態、起動・終了の時刻、期限、起動した人が表示されます。開くで URL を開き、URL をコピーでコピーします。終了した環境は「終了済み N 件」にまとめられます。
- 起動: 環境の横の + をクリックします。各マシンで最新の実行が宣言した環境が並び、選んだものをその実行のコードで起動します。タスクがまだ実行されていないか、そのコードが削除されている場合は、代わりにエージェントへの依頼を提案します。エージェントはコードを用意して
multica env startを実行し、宣言がなければ起動方法を自分で判断します。 - 停止・再起動・ログを表示: 環境のその他の操作メニューを開きます。再起動はチェックアウト内の宣言を読み直すため、チェックアウトとその
.multica/environments.tomlが残っている必要があります。自動検出されたサーバーは確認のうえ停止だけができます。
起動・停止・再起動には、タスクにアクセスでき、そのマシンのランタイムを使えるワークスペースメンバーである必要があります（デーモンとランタイムを参照）。マシンがオンラインで、その Multica が環境の操作に対応したバージョンである必要もあります。足りないものがあればボタンが理由を示します。ログの表示に必要なのはタスクへのアクセスだけです。
ログ
ログを表示では、宣言された環境の出力のうち最後の 500 行（最大 256 KiB）が表示されます。環境が動いている間は約 5 秒ごとに新しい出力を追い、追従の一時停止、更新、絞り込み、折り返し、コピーができます。
環境がクラッシュすると最後の 2 行の出力が環境とともに保存されるため、マシンがオフラインになってもサイドバーで終了した理由がわかります。新しく読み込むにはマシンがオンラインである必要があります。
完全なログはマシンの <workspaces root>/.environments/v1/ に残り、環境の終了後 7 日間保持されます。パスは multica env start と multica env list が表示します。
タスクにアクセスできる人は誰でも環境のログを読めます。Multica はアップロードする行から認識できる秘密情報を伏せ、読み込んだログを 10 分後に削除しますが、それに頼らず、サーバーの出力に認証情報を出さないでください。
状態
| 状態 | 意味 |
|---|---|
| 起動中 | 起動済みで、ready のアドレスが応答するのを待っています。 |
| 実行中 | 準備完了、または（自動検出の場合）待ち受け中です。 |
| 終了 | クラッシュなどでプロセスが自分で終わりました。終了コードと最後の出力が表示されます。 |
| 停止 | エージェント、メンバー、または TTL によって停止されました（「期限切れで自動停止」）。 |
| 応答なし | 動かしているマシンから 3 分間報告がありません。デーモンが止まったか、マシンがスリープ中かオフラインです。デーモンが報告を再開すると実際の状態に戻ります。 |
デーモンが止まっている間は何も管理されません。デーモンが再起動すると、プロセスがまだ生きている環境は再び管理下に入ります。環境が動いている実行ディレクトリは、環境が止まるまでデーモンのワークスペース整理で削除されません。
エージェントにファイルを書かせる
エージェントはこの形式を知っています。すべてのエージェントが受け取る Multica 組み込みのプラットフォームスキルに、.multica/environments.toml の書き方と確認方法が載っています。タスクで次のように頼めます。
このリポジトリの Web アプリを
multica env startで起動できるように.multica/environments.tomlを追加してください。一度起動して動くことを確かめてから PR を作ってください。
エージェントはプロジェクトの起動方法を調べ、MULTICA_PORT のポートを使ってファイルを書き、環境を起動して応答を確かめ、ほかの変更と同じように提出します。マージされれば、以降のどの実行でも、メンバーもサイドバーから、その環境を起動できます。
既知の制限
- macOS と Linux のみ。 Windows ではサーバーは検出されず、
multica env startは未対応であることを伝えます。 - localhost の URL は動かしているマシンでしか開けません。 ビルドサーバーや同僚のコンピューターなど別のマシンで動いている場合はサイドバーにそう表示されます。そのマシンで開くか、自分でポートを転送してください。
- systemd でのデーモン再起動。 Linux でログイン時の自動起動を使っていると、デーモンの再起動や更新で宣言された環境も止まります。そのあと起動し直してください。
- 環境は 1 台のマシンで動きます。 環境は起動した実行のマシンで動き、タスクと一緒に移動しません。
次のステップ
- デーモンとランタイム — 環境を検出・管理するデーモン。
- CLI を使う —
multica envコマンドとほかの CLI コマンド。 - 実行 — 実行のディレクトリがどこから来るか。