環境をセットアップする
環境は 1 つのスペースの実行スタックです。ブランチに必要なサービスが他のすべてのスペースから隔離されて動き、サイドバーに表示され、エージェントからアクセスできます。PR にはすでに専用のスペースがあるので、プルリクエストにも環境があります。
ワークスペース管理者が定義を一度書きます。その後、メンバーはスペースまたは PR のサイドバーの 環境 セクションで 開始 を押します。定義はワークスペースのデータベースに保存されるため、機能ブランチが Control Center の実行内容を変えることはありません。ただし、ツールはそのブランチのコードを実行します。
定義を作成する
「定義を作成する」というセクション- 設定 → ワークスペース → 環境 を開きます。定義を変更できるのはワークスペース管理者だけで、サーバーのホスト上で動く定義を保存できるのはサーバーオーナーだけです(誰が何を保存できるか を参照)。
- 新しい定義 をクリックし、空の定義 または リポジトリから下書き を選びます。下書きはリポジトリから compose ファイル、
Procfile、package.jsonのスクリプトを探し、結果はあなたが確認します。 - フォームに入力するか、JSON タブを使います。このページの例はその JSON です。
- テストを実行 をクリックします。使い捨ての環境を起動し、準備完了を待ってから破棄します。
保存時には定義が厳密にチェックされます。未知のフィールド、型の合わない値、綴りの誤った選択肢は拒否され、そのパスと最も近い有効な名前が示されます。例:repos.app.requird: Unknown field. Did you mean "required"?。トップレベルの $schema は使用できます。
定義をリポジトリに置くには リポジトリのファイルをリンク を使います。Control Center はファイルをデフォルトブランチからのみ読み取り、承認されたバージョンだけを実行します。承認するのはワークスペース管理者か、定義がホスト上で動く場合はサーバーオーナーです。新しいバージョンは 更新があります と表示され、承認されるまで何も変わりません。
誰が何を保存できるか
「誰が何を保存できるか」というセクション環境の定義は、サーバーのホスト上で、サーバー自身のユーザーとしてコマンドを実行できます。これはワークスペースのロールではなく、サーバーオーナーの判断です。
- 定義は、ホストの配置を持つとき、コマンドを実行するチェックを持つとき、または
provisionかarchiveのタスクを持つとき、ホスト上で実行されます。それらのタスクは、配置がどうであれ、ホスト上のスペースのワークツリーで実行されます。 - ホスト上で実行される定義を保存または承認できるのは、サーバーオーナーだけです。これには、リンクされたリポジトリファイルの新しいバージョンの承認も含まれます。試みたワークスペース管理者には「サーバーのホスト上で実行される環境を保存または承認できるのは、サーバーオーナーだけです。ワークスペース管理者はリグで実行される環境を使用できます。」と表示されます。
- ワークスペース管理者は、リグ内でのみ実行される定義を保存して承認できます。
"placement": "rig"で、チェックコマンドがなく、provisionもarchiveのタスクもないものです。 - メンバーは、どちらの場合でも環境を開始、停止、利用します。
- ホスト上で実行される定義は、現在のサーバーオーナーが保存または承認した後にのみ実行されます。サーバーはその承認を自分で記録し、開始、チェック、タスク、プルリクエストのヘッド同期のたびに確認します。現在のオーナーが承認していない定義(以前のオーナーが保存したものなど)は、環境の一覧とエディターでその行の下に保留されます。サーバーオーナーには「このサーバー上で実行されます。開始するには承認してください。」と 承認 が表示され、それを押すと内容は変えずに保存されます。それ以外の人には「このサーバー上で実行されます。開始するには、サーバーオーナーの承認が必要です。」と表示されます。
- 承認のために保留された環境には「サーバーオーナーがまだこの環境を承認していないため、このサーバーでは実行できません。」と表示されます。サーバーオーナーには代わりに「まだこの環境を承認していません。サーバー上で実行されるため、定義を承認すると開始されます。」と 確認して承認 が表示され、それを押すと定義が開きます。
- 環境のプロセスのターミナル、および開始時に対応が必要になると開かれるターミナルは、サーバーのホスト上で動きます。ターミナルに入力する、サイズを変更する、閉じるには、スペースが公開するすべてのリポジトリへの書き込みアクセスが必要です。自分のフォージサインインを通じて読めるリポジトリが対象です。環境を開始する場合と同じ条件です。それ以外のユーザーは、それらのターミナルにまったく到達できません。
最小の定義
「最小の定義」というセクションシンプルな compose リポジトリならこれだけで足ります。
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "compose", "id": "stack" } ]}それ以外にはすべてデフォルトがあります。compose ファイルは自動で見つかり、すべてのサービスが動き、ポートが割り当てられ、HTTP エンドポイントが検出され、環境にはブランチ名が付きます。
コンポーネントの種類
「コンポーネントの種類」というセクション環境はコンポーネントの順序付きリストです。after で別のものを指定しない限り、各コンポーネントは前のものの準備完了を待ち、停止は逆順で行われます。enabledWhen は、opt.seed、!opt.seed、repo.web のように、オプションやロールに応じてコンポーネントを有効にします。ロールが任意で、スペースにそのロールがない場合も同様に除外されます(enabledWhen は不要です)。そのコンポーネントは起動せず、{port.*} や {url.*} も持たないため、それらを読み取る別のコンポーネントは起動に失敗します。
| 種類 | 実行するもの | 用途 |
|---|---|---|
compose |
Control Center の compose ドライバー | 任意の compose ファイル。環境ごとに 1 つ |
cli |
あなたのツール。Control Center は対応付けた動詞を呼び出して JSON を読みます | ライフサイクル、ドメイン、データを自分で管理するツール |
process |
Control Center。監視付きのターミナルセッションで実行 | 開発サーバーとワーカー |
task |
Control Center。トリガーごとに 1 回 | インストール、マイグレーション、テスト |
app |
Control Center。誰かが 起動 をクリックしたとき | デスクトップアプリ |
task コンポーネントは when リストを取ります。
| トリガー | 実行タイミング |
|---|---|
provision |
ワークツリーの作成時(後述のワークツリータスクを参照) |
create |
環境ごとに 1 回、およびリセット後にもう一度 |
start |
起動のたび |
change |
同期の後、変更されたパスが onChange に一致したとき |
manual |
要求時:実行、cc-env run <id>、environment_run_task |
archive |
ワークツリーが破棄される直前 |
開始時に何もすることがないタスクは アイドル と表示され、環境の開始中に表示されるステップ一覧からは外されます。対象は manual または change のタスク、あるいはすでに実行済みの create タスクです。
配列で指定したコマンドは argv なので、オプションの値がシェルを通ることはありません。文字列、または行の配列を持つ script は bash -lc で実行されます。{name}、{branch}、{stateDir}、{repo.<role>}、{port.<key>}、{opt.<key>}、{url.<role>} などのプレースホルダーは argv の中でのみ展開されます。シェルコマンドは同じ値を $CC_ENV_PORT_WEB のような CC_ENV_* 変数として読みます。このスペースの環境に含まれるコンポーネントで未知のプレースホルダーがあると、何も実行される前に起動が止まります。
各コマンドとスペースのターミナルには、CC_ENV_NAME、CC_ENV_STATE_DIR、CC_ENV_URL、CC_SPACE_ID、CC_ENV_REPO_<ROLE>、PR スペースでは CC_PR_NUMBER と CC_PR_IS_FORK も渡されます。compose コンポーネントがあれば COMPOSE_PROJECT_NAME と COMPOSE_FILE も渡されるので、タスク内の docker compose exec は正しいプロジェクトに届きます。
ロールと作業ディレクトリ
「ロールと作業ディレクトリ」というセクション定義はロールをワークスペースのリポジトリに結び付けるので、1 つのスタックが複数のリポジトリにまたがることができます。
"repos": { "api": { "repoId": "<api>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true }, "e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }}anchor: スペースにアンカーロールが 1 つ以上あれば環境を起動できます。2 つの定義が一致する場合は、起動する人が選びます。required: このリポジトリがないとスタックは動きません。whenMissing: スペースにロールがないときの動作です。addToSpaceはデフォルトブランチのリポジトリを追加し、requiredロールのデフォルトです。useSourceは登録済みのチェックアウトを渡します。読み取り専用として扱ってください。skipは変数を未設定のままにし、それ以外の場合のデフォルトです。- 起動には、スペース内のアンカーリポジトリに対する
write権限と、他のすべての結び付けられたリポジトリへの読み取りアクセスが必要です。
コマンドは、repos に宣言された最初のロールで実行され、スペースがたまたま持っている別のロールでは実行されないので、リポジトリが 1 つの定義ではこれを書く必要はありません。どのコンポーネントも "cwd": { "role": "e2e", "path": "packages/ui" } で上書きできます。どちらのフィールドも省略可能です。最初のロールがスペースに存在しない可能性がある場合(required ではなく、唯一のアンカーでもない場合)は、すべてのコンポーネントでロールを指定する必要があります。
ポートと URL
「ポートと URL」というセクションControl Center は何かが起動する前に、ホスト全体で共通の範囲(デフォルトは 42000 から 49999、32 個単位のブロック)からホストポートを割り当てます。ポートは環境が存在する間ずっと変わらず、compose のポートは 127.0.0.1 にのみバインドします。
- compose のポートは宣言不要です。
{port.postgres.5432}またはCC_ENV_PORT_POSTGRES_5432として読みます。 - その他のポートは使う場所で
"port": "web"または"ports": ["web", "hmr"]として宣言し、{port.web}として読みます。ポートを持つプロセスにはPORTとHOST=127.0.0.1も渡されます。
HTTP エンドポイントには、1 つのループバックポートで待ち受けるサーバーのルーター上の URL が付きます。
http://<endpoint>--<name>--<project>.localhost:<router port>http://web--fix-login--shop.localhost:7355<name>はブランチのスラッグで、PR スペースではpr-<n>です。<project>はnaming.project、なければ定義の名前です。*.localhostの名前はループバックを指すので hosts エントリも DNS も不要で、ホスト名によって環境間の Cookie が分離されます。- HTTP に応答する compose ポートは検出され、コンポーネントの
httpでその推定を上書きできます。プロセスには"endpoint": { "role": "web", "primary": true }が必要で、これにより{url.web}も使えるようになります。 - ブラウザー (VM) では Browser (VM) で開く を使います。そこでは
https://web--fix-login--shop.localhost/が同じルートに届きます。 - ラベル全体は 63 文字以内に収まるので、長い名前はハッシュで短縮されます。
- 2 つのエンドポイントに共通の親ドメインはありません。両方で 1 つの Cookie が必要なアプリは、1 つのエンドポイントから配信する必要があります。
OAuth リダイレクトのように事前登録が必要な URL には、"naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } で固定の名前セットを使えます。
policy は環境がいつ動くかを決めます。autoCreate は off、prSpaces、allSpaces のいずれか、idleStopMinutes のデフォルトは 240、followPrHead は head が動くと PR 環境を同期し、maxRunning(デフォルト 6)に達すると 開始 は最も長く使われていない環境の停止を提案します。
例:compose アプリ
「例:compose アプリ」というセクション1 つの compose ファイルから動く Web アプリと Postgres に、git で無視される .env、マイグレーション、テストタスクを加えた例です。seedFiles は、登録済みのチェックアウトから指定のファイルを新しいワークツリーごとにコピーします。
{ "contract": 1, "name": "Shop", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "naming": { "project": "shop" }, "seedFiles": [".env"], "components": [ { "kind": "compose", "id": "stack", "services": ["postgres", "web"], "healthchecks": { "postgres": ["pg_isready", "-U", "postgres"] } }, { "kind": "task", "id": "migrate", "when": ["create", "change"], "onChange": ["db/migrations/**"], "command": "docker compose exec -T web bin/migrate" }, { "kind": "task", "id": "test", "when": ["manual"], "command": "docker compose exec -T web bin/test" } ]}healthchecks を使うと、独自のヘルスチェックを持たないサービスでも次のコンポーネントを待たせられます。これがないと実行中のコンテナは準備完了とみなされ、起動中のデータベースより先にマイグレーションが走ることがあります。
開始と更新のたびに --remove-orphans 付きで up が実行されるので、compose ファイルから削除されたサービスは停止してポートを解放します。コンポーネントで "build": false を設定しない限り、開始時と更新時にイメージがビルドされます。
例:独自の CLI
「例:独自の CLI」というセクションコンテナ、ドメイン、TLS を自分で管理する架空のツール acme の例です。Control Center は {name} を渡し、それ以外はすべて status から知ります。ツールのホスト名を推測することも、/etc/hosts を編集することもありません。
{ "contract": 1, "name": "Acme", "repos": { "server": { "repoId": "<server>", "anchor": true, "required": true }, "web": { "repoId": "<web>", "anchor": true } }, "routing": { "mode": "tool", "domain": "acme.test", "upstream": "127.0.0.1:443", "tls": true, "caFile": "~/.acme/tls/ca.crt" }, "components": [ { "kind": "cli", "id": "acme", "verbs": { "create": ["acme", "env", "create", "{name}", { "if": "!interactive", "args": ["--json"] }, { "if": "repo.web", "args": ["--web-dir", "{repo.web}"] }], "start": ["acme", "env", "start", "{name}"], "stop": ["acme", "env", "stop", "{name}"], "destroy": ["acme", "env", "destroy", "{name}", "--yes"], "reset": ["acme", "env", "reset-db", "{name}"], "status": ["acme", "env", "status", "{name}", "--json"], "list": ["acme", "env", "ls", "--json"], "logs": ["acme", "env", "logs", "{name}", { "if": "service", "args": ["{service}"] }, "--tail", "{tail}", { "if": "follow", "args": ["--follow"] }], "exec": ["acme", "env", "exec", "{name}", "{service}", "{command}"] }, "interactive": ["create"], "keepsDataOnStop": false, "statusMap": { "state": [ { "when": { "path": "/status/ready", "equals": true }, "state": "ready" }, { "when": { "none": "/status/containers", "where": { "state": "running" } }, "state": "stopped" }, { "when": { "path": "/status/phase", "equals": "failed" }, "state": "failed" }, { "state": "starting" } ], "detail": "phase: {/status/phase}", "warnings": [ { "when": { "path": "/status/dnsWorking", "equals": false }, "message": "Not resolvable on this host" } ], "endpoints": [ { "role": "app", "label": "App", "url": "/urls/app", "primary": true }, { "role": "db", "hostPort": "/ports/db" } ], "services": "/status/containers/*/service", "list": "/*/slug", "missingErrorCodes": ["env.not-found"] } } ]}create、status、destroyは必須です。Control Center は読み取ったステータスからcreateかstartを選びます。どの動詞も argv の代わりに{ "shell": "…" }にできます。interactiveは、create、start、resetのうち、ターミナルで必要な入力を求められる動詞を指定します。開始 を押した人に対してそのような動詞が終了コード 3 で終了した場合、Control Center は同じ動詞をターミナルタブで再実行し、終了コード 0 で終わると開始が続行されます。そこでは条件interactiveが真になり、CC_ENV_INTERACTIVE=1が設定されるため、{ "if": "!interactive", "args": ["--json"] }はパイプ用の機械可読な出力を維持します。エージェントによる開始や自動の開始では、ターミナルは決して開かれず、環境は 対応が必要 と表示して待機します。destroyが失敗しても、続けてstatusがmissingを報告すれば環境は削除されるため、ツールが既に持っていない環境は常に削除できます。listを使うと、Control Center はツールが見失った環境に気づけます。listの中にその名前がなく、かつstatusがmissingを返したときに限り、消失とマークされます。一覧として読めない出力では何も変わりません。logsとexecの{service}は、-で始まらない 1 語でなければならず、ツールが何かを報告したことがあるなら、ツールが最後に報告したサービスのいずれかでなければなりません。statusMapはツール自身の JSON を JSON ポインターで読みます。*はすべての項目に一致します。状態ルールは順序付きで、最初の一致が優先されます。条件はpathとequals、またはanyかnoneとwhereです。keepsDataOnStop: falseはアイドル停止を無効にし、停止 にデータ損失の警告を追加します。停止でデータが失われる場合に設定します。routing.mode: "tool"はツールのホスト名をブラウザー (VM) とエージェントにつなぎます。ドメインは.test、.localhost、.internalのいずれかで終わる必要があり、その外の URL が報告されると破棄されます。
自分のツールなら statusMap を省き、このページの最後にあるステータス契約を出力できます。
例:pnpm モノレポ
「例:pnpm モノレポ」というセクションプロセスとタスクだけで、コンテナはありません。Web アプリは {url.api} で API を見つけます。
{ "contract": 1, "name": "Monorepo", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "naming": { "project": "mono" }, "options": [ { "key": "seed", "type": "bool", "default": true, "agentDefault": false } ], "components": [ { "kind": "task", "id": "install", "when": ["provision", "change"], "onChange": ["pnpm-lock.yaml"], "command": ["pnpm", "install", "--frozen-lockfile"] }, { "kind": "process", "id": "api", "label": "API", "port": "api", "cwd": { "path": "apps/api" }, "command": ["pnpm", "dev"], "endpoint": { "role": "api" }, "ready": { "http": "http://127.0.0.1:{port.api}/health", "timeout": 120 }, "restartOn": ["pnpm-lock.yaml"] }, { "kind": "task", "id": "seed", "when": ["create"], "enabledWhen": "opt.seed", "cwd": { "path": "apps/api" }, "command": ["pnpm", "db:seed"] }, { "kind": "process", "id": "web", "label": "Dev server", "port": "web", "cwd": { "path": "apps/web" }, "env": { "API_URL": "{url.api}" }, "command": ["pnpm", "dev", "--port", "{port.web}", "--host", "127.0.0.1"], "endpoint": { "role": "web", "primary": true }, "ready": { "http": "http://127.0.0.1:{port.web}/" } }, { "kind": "task", "id": "lint", "when": ["manual"], "command": ["pnpm", "lint"] } ]}- 各プロセスはターミナルタブで、開いて読んだり、スペース内のすべてのリポジトリへの書き込みアクセスがあれば入力したりできます(誰が何を保存できるか を参照)。タブを閉じても止まりません。
readyはhttp(完全な URL)、tcp(host:port)、logMatch(正規表現)を取ります。restartはon-failure(デフォルト)、always、neverのいずれかです。restartOnは変更されたパスが一致するとプロセスを再起動します。optionsは 開始 のフォームになり、agentDefaultはエージェントが開始した実行に適用されます。
例:デスクトップアプリ
「例:デスクトップアプリ」というセクションビルド手順のあるデスクトップアプリです。Control Center は OS のウィンドウレベルで動き、アプリ側にフックや SDK を必要としないので、どの技術で作られていても同じように扱えます。
{ "contract": 1, "name": "Studio", "repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } }, "components": [ { "kind": "task", "id": "build", "when": ["manual"], "command": ["pnpm", "build"] }, { "kind": "app", "id": "desktop", "label": "Studio", "prepare": "build", "command": ["dist/mac-arm64/Studio.app/Contents/MacOS/Studio"], "isolate": "home" } ]}アプリは環境と一緒には起動しません。誰かが 起動 をクリックすると、先に prepare が実行されます。再ビルドして再起動 はこの組をもう一度実行します。enabledWhen はアプリとその prepare タスクの両方に適用され、どちらかが無効のときは 起動 は拒否されます。アプリは、そのプロセスグループ内のいずれかのプロセスが動いている間は実行中とみなされるので、アプリを起動して終了するランチャーでも問題ありません。起動 の約 5 秒以内にすべてのプロセスが消えると、アプリは最後のログ行とともに失敗として表示されます。その後、正常終了は閉じた状態として表示され、クラッシュは最後のログ行を表示します。どちらも再起動はしません。サーバーの再起動ではアプリを閉じ、再起動することは決してなく、アイドル停止は実行中のアプリに触れません。
デスクトップアプリの権限と制限
「デスクトップアプリの権限と制限」というセクション- macOS では、システム設定で Control Center に画面収録とアクセシビリティを一度許可します。サーバーホストには GUI セッションが必要で、ヘッドレスサーバーはアプリの起動を拒否します。
- バイナリを直接起動します。
open -aはアプリを LaunchServices に渡すので、Control Center が追跡するプロセスツリーから外れるため、起動直後にアプリが失敗として表示されます。 - ウィンドウはディスプレイ上に残ります。macOS はすべてのディスプレイの外に置かれたウィンドウをキャプチャしないので、エージェントが使っているアプリはサーバーの画面に見えます。フォーカスは不要です。
"isolate": "home"はHOME、XDG_*、CFFIXED_USER_HOMEを通じてアプリに専用のホームを与え、2 つのスペースのコピーを並行して動かせます。NSUserDefaultsは隔離されないので、Cocoa の環境設定と Flutter のshared_preferencesはコピー間で共有されたままです。isolateは起動したプロセスにのみ適用されます。flutter runのようなツールチェーンのランチャーには本物のホームが必要なので、isolateはビルド済みバイナリと組み合わせてください。--user-data-dirのようなアプリ独自の設定があれば、そちらを優先します。- エージェントは
app_useでウィンドウを操作します。届くのはこの環境のプロセスツリーだけです。エージェントに見えるのはウィンドウで、デスクトップではありません。エージェントによる起動はアクションポリシーを通り、デフォルトでは確認を求めます。人が操作権を持っている間、エージェントの入力は止まります。 "input": "background"(デフォルト)はイベントをプロセスに送ります。"foreground"はウィンドウをアクティブにしてカーソルを奪います。
ワークツリータスク
「ワークツリータスク」というセクションprovision と archive のタスクは、リポジトリのセットアップとティアダウンをそのワークツリーとともに実行します。設定 → ワークスペース → リポジトリ のリポジトリの行にあるアイコンから、そのリポジトリの定義を開きます。
これらのタスクは環境ではなくワークツリーに従うので、誰も 開始 を押さないスペースでも実行されます。
provision |
archive |
|
|---|---|---|
| 実行 | ロールのワークツリーが作成されたとき(どのスペースでも) | そのワークツリーが破棄される直前 |
| 失敗時 | プロビジョニングが失敗し、ワークツリーは破棄される | 記録され、削除を妨げることはない |
| デフォルトのタイムアウト | 5 分 | 2 分 |
| 見えるもの | CC_WORKSPACE_PATH、CC_ROOT_PATH、CC_SPACE_*、CC_REPO_NAME |
同じ |
スタックのないリポジトリには、タスクを持つ定義だけが必要です。起動するものがないので、アンカーロールは不要です。
{ "contract": 1, "name": "Web", "repos": { "app": { "repoId": "<id>" } }, "components": [ { "kind": "task", "id": "setup", "when": ["provision"], "script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] } ]}- まだ環境がないので、これらのタスクでは
{name}、{port.*}、{url.*}、{opt.*}、enabledWhenを使えず、定義のenvも渡されません。 - 1 つのリポジトリの
provisionとarchiveタスクを持てる定義は 1 つだけです。他の定義はそれ以外の用途で結び付けられます。 "when": ["provision", "change"]はロックファイルが変わったときにも再インストールします。- タスクは
cwdロールのワークツリーに対して実行されるので、複数リポジトリの定義ではリポジトリごとに別々にセットアップできます。 - テスト実行では
CC_SCRIPT_TEST=1が設定されます。再試行はクリーンなワークツリーから始まるので、再実行に耐えるタスクを書いてください。
エージェント
「エージェント」というセクションエージェントに Docker ソケットが渡されることはありません。対象の定義があるスペースでは、実行の PATH に cc-env が入ります。スペースは実行から決まるので、エージェントは自分の環境にしか作用できず、各コマンドはアクションポリシーを通ります。
cc-env statuscc-env upcc-env downcc-env resetcc-env destroycc-env restart <process>cc-env logs <name>cc-env exec <service> -- <cmd>cc-env run <task> -- <args>compose コンポーネントがあると、docker シムが ps、logs、exec、port、restart、top の docker compose も許可します。許可されるのはこの環境自身の compose プロジェクトに対してだけです。動詞の前にフラグは置けず、各動詞は限られたオプションだけを受け付けます。logs は追跡できず、exec は -T(または --no-tty)だけを受け付けます。compose を別のファイルやプロジェクトに向けるオプション(-f、-p、--project-directory、--env-file、--profile)は、どこに現れても拒否されます。それ以外は終了コード 5 と「not available in Control Center agent runs」で終了します。
スキルが自前のツールを呼ぶリポジトリは、そのまま使い続けられます。cli コンポーネントの agentPassthrough ブロックで、エージェントが実行できるコマンドを宣言します。通過するのは承認された定義が宣言したコマンドだけで、それぞれホスト上で実行されるため、ホストでコマンドを実行 のルールが適用されます。このルールは既定で、まず確認を求めます。
"agentPassthrough": { "binary": "acme", "allow": [ { "argv": ["env", "ls"], "maps": "status", "nameFilter": true }, { "argv": ["env", "status|url"], "maps": "status", "positionalName": 2 }, { "argv": ["env", "create"], "maps": "up", "positionalName": 2, "pathFlags": ["--web-dir"], "denyFlags": ["--force"] }, { "argv": ["env", "logs"], "maps": "logs", "positionalName": 2, "denyFlags": ["--follow"] } ]}maps は適用するポリシーの操作を指定します。positionalName はその引数をこのスペースの環境に固定し、nameFilter は JSON 出力をそれに絞り込み、pathFlags の値はすべて実行のワークツリー内に解決される必要があります。どのルールにも一致しないコマンドは終了コード 5 で終わります。
同じ操作はツールとしても使えます:environment_status、environment_up、environment_down、environment_reset、environment_destroy、environment_restart、environment_exec、environment_logs、environment_run_task、environment_launch_app、environment_stop_app。サンドボックス内のエージェントは自分のポートに直接届き、環境のホスト名には実行のプロキシ経由で届きます。URL を推測させず、environment_status からエンドポイントを読むよう伝えてください。
フォークのプルリクエスト
「フォークのプルリクエスト」というセクションフォーク PR のコードは信頼できず、ホスト配置ではサーバーの OS ユーザーとして実行されます。何が起きるかは policy.forkPrs で決まります。
| 値 | 効果 | デフォルトの対象 |
|---|---|---|
rig |
compose ファイルは確認なしで VM 内で実行される | compose と task コンポーネントだけの定義 |
approval |
起動のたびに管理者が必要 | 他のすべての定義 |
deny |
拒否 | なし |
seedFilesは通常シークレットなので、フォークにはコピーされません。これをバインドする compose ファイルは、欠けているファイルを名前で報告します。provisionとarchiveのタスクはスキップされます。ポリシーがrigの場合は VM 内で実行されます。- ホスト配置では、フォークに対して
privileged、ホストの名前空間、Docker ソケットのバインド、devices、スペースのワークツリー外へのバインドが拒否されます。信頼済みのスペースでは警告だけです。
リグ配置
「リグ配置」というセクション"placement": "rig" は compose と task のコンポーネントを専用の microVM で実行します。process、cli、app のコンポーネントを含む定義は対象外です。compose ファイルは変更なしで実行され、ホストの Docker ソケットもオペレーターの認証情報もなく、ネットワークアクセスはイメージに必要なレジストリに限られます。ワークツリーはライブでマウントされます。
- arm64 ゲスト。 Apple Silicon ではゲストは arm64 なので、amd64 専用のイメージは動きません。
- プライベートレジストリは拒否されます。 ゲストにはレジストリの認証情報がないので、既知の公開レジストリ以外にあるイメージは VM の起動前に拒否されます。公開レジストリ上のプライベートリポジトリは、ゲストが取得するときに失敗します。
- 16 GiB のストレージ。 スタックのすべてのイメージとボリュームが 1 つの 16 GiB ディスクを共有し、増やすことはできません。
- 初回起動は遅い。 イメージレイヤーは VM ごとなので、初回起動ですべてを取得します。停止したリグはディスクを保持します。
- ベースイメージは読み取れる必要があります。 ベースイメージを変数で指定する Dockerfile は計画できません。ネットワークアクセスは起動時に固定されるためです。
- 有効期間。
policy.rigTtlHoursが VM を終了します。デフォルトは 24 時間です。
ツール作成者向けのステータス契約
「ツール作成者向けのステータス契約」というセクションstatusMap のない cli コンポーネントは、ネイティブ契約 cc-env/1 を想定します。status 動詞はこのオブジェクトを stdout に出力します。
{ "state": "ready", "detail": "migrations applied, HTTP 200", "endpoints": [ { "role": "app", "label": "App", "url": "https://fix-login.acme.test", "primary": true }, { "role": "postgres", "label": "Postgres", "hostPort": 49213 } ], "services": ["server", "postgres"], "needsRecreate": false, "error": { "code": "post-start-failed", "message": "…", "hint": "…", "command": "…" }}stateはready、starting、stopped、failed、missingのいずれかです。missingはcreateに、stoppedとfailedはstartにつながります。missingは終了コード 0 で報告してください。失敗したstatusはfailedとして扱われます。- 必須なのは
stateだけです。不明なフィールドは無視され、解析できない出力は生のテキストを詳細として低下状態で表示されます。 - URL はループバック、
*.localhost、またはrouting.domainの配下である必要があり、それ以外は破棄されます。 needsRecreate: trueは 再作成 を表示します。これはデータを破棄します。Control Center がこの値だけで動くことはありません。list動詞は、名前またはnameを持つオブジェクトの JSON 配列を出力します。
終了コードはすべての動詞に適用されます。
| コード | 意味 |
|---|---|
| 0 | OK |
| 3 | ターミナルで応答が必要です(sudo のパスワードなど)。interactive に列挙された動詞は、開始 を押した人のターミナルタブで再実行されます。それ以外の場合、ターミナルで実行 は、ツールの command を入力済みで未実行の状態でスペースのターミナルを開き、その後 再試行 でやり直します。Control Center が sudo を実行することはなく、プロンプトに応答することもありません |
| 4 | サインインが必要です。ツールの command に方法が書かれています |
| 5 | 依存しているものが利用できません(例:実行されていないコンテナランタイム) |
| その他 | 失敗 |
コード 3、4、5 は失敗ではありません。環境は 対応が必要 と表示して待機し、次の開始は前回止まった場所から再開されます。これらのいずれかで終了するタスクも同じ意味です。
進捗は改行区切りの JSON として stderr に出力します。
{"type":"step","id":"images","label":"Pull images","state":"running"}{"type":"log","stream":"stdout","line":"postgres Pulled"}{"type":"step","id":"images","label":"Pulled 4 images","state":"done"}{"type":"note","level":"warn","message":"Hosts entries stayed behind after destroy"}{"type":"error","code":"hosts-missing","message":"Add the hosts entry","hint":"Needs sudo","command":"sudo acme hosts add fix-login"}環境の開始中、パネルには開始で実行される各コンポーネントが一覧表示され、それぞれにスピナー、チェック、または × が付きます。step 行はツールが今何をしているかを示し、その label はツール自身の行の下に表示されます。ステップが行を追加することはありません。ステップの state は pending、running、done、failed のいずれかで、state を持たないステップは実行中として扱われます。同じ id(文字列または数値。ない場合は同じ label)で再度報告されたステップは、以前の内容を置き換えます。そのため、スピナーが 1 つだけのツールは同じ id を保ったまま label を変えられます。id がない場合、ステップは順番に続き、新しいステップが前のステップを終わらせます。コマンドが終了すると、まだ実行中のステップはコマンドの結果と同じ状態で終わります。
log 行は、ツールが JSON で包んだ出力を 1 行分運び、通常の出力テキストとして扱われます。note は実行の出力に表示され、"level": "warn" を持つものは警告として環境にも残ります。最後の行が error タイプなら構造化エラーになり、command がコピー用に提示され、出力の最後の 12 行が message の下に表示されます。ない場合、Control Center は stderr の最後の 20 行を表示します。JSON でないものはすべて通常のログ出力です。