insta

InstaCloud

エージェント実行モード（マネージド Platform）

ポリシーシステムは agent policy のみです。人間は通常の RBAC を使用し、ポリシー評価器に入るのはエージェントのリクエストのみです。以前の policy コマンドと承認用の --always フラグは削除されました。

エージェントとして CLI を実行するときは、セットアップや読み取り専用コマンドも含め、常に insta --agent <command> … を使用してください。例ではグローバルフラグを明示しています。npx を使用する場合は、npx -y insta@latest --agent <command> … とします。環境検出だけに頼らないでください。人間の管理者向けと明記されたコマンドは、人間に引き継ぐための指示であり、エージェントのツール呼び出しではありません。自分で実行したり、制限を回避するために --agent を外したりしないでください。 最初に、リンク済みプロジェクトで insta --agent agent setup を実行してください（または --project <id>／--create [name] を使用します）。これにより、Git で自動的に無視される .insta/agent-session.json に、プロジェクトに紐づいた24時間有効のセッションが保存されます。既存のユーザーログインに追加されるものです。セッションが存在しない、期限切れ、取り消し済み、または別のプロジェクトのものである場合は、セットアップ方法が示されて失敗します。拒否されたエージェントリクエストを --agent なしで再試行しないでください。

既知の Codex／Claude Code／Cursor 環境でもエージェントモードが有効になります。汎用 CI や TTY がない環境では有効になりません。MCP ツールの呼び出しは自動的にエージェントリクエストとして扱われます。現在のモードと保護対象ブランチは、insta --agent agent policy get --json で確認してください。すべてのプロジェクトは、初期状態で full_access を使用します。branch_specific（および明示的なルールを持つ同じモードである customize）では、保護対象への書き込みは禁止され、保護されていない対象へのリスクの高い操作には人間の承認が必要です。承認コマンドを人間の管理者に伝え、承認後に元のリクエストを変更せずに再試行してください。エージェントは自分自身のリクエストを承認できません。詳細と SQL の制限については、governance.md を参照してください。このプロトコルにはエージェントセッションをサポートするマネージド Platform バージョンが必要です。旧バージョン／OSS のエンドポイントはこれを実装していません。セッションエラーが起きても、実行主体を黙って切り替えないでください。

InstaCloud は、1つの CLI と1つの認証情報連携を通じて、プロジェクトのクラウドサービスを提供・管理します。insta CLI が通信するのは InstaCloud コントロールプレーンのみです。クラウドのバックエンドを直接設定する必要はありません。プロジェクトには、必要に応じて任意の数のサービスを追加できます。直接利用できる一般的なサービスの種類は次のとおりです。

• postgres — プランのリソース上限で作成されるリレーショナル DB です（どのプランでも、無料枠の範囲内で insta --agent postgres limits を使って移動できます。無料枠を超える場合は有料プランが必要です）。通常の Postgres です。以下のとおり、コンピュート環境にバインドする DATABASE_URL を使って、任意のドライバー／ORM から直接接続できます。ベンダーの SDK やスキルは不要です。この DB にはコンピュートの外部からもパブリックに接続できます。insta --agent postgres url は接続文字列を表示し、insta --agent postgres connect は psql セッションを開始します。これにより、ノート PC、マイグレーションスクリプト、または任意の外部ツールから、自分または人間が接続できます。データベースをスケール・トゥ・ゼロに切り替えた場合（新しいデータベースは常時稼働で作成されます）、プールの idleTimeoutMillis を一時停止までの時間より短くしてください（frameworks.md を参照）。
• storage — S3 互換のオブジェクト／Blob ストレージです。バインドされた AWS_*／BUCKET_NAME 環境変数を使って、任意の S3 ライブラリから接続できます。ベンダーの SDK は不要です。エンドポイントを明示的に設定してください。設定しないと、クライアントは実際の AWS に接続します。通常、各ブランチには個別にフォークされたバケットが割り当てられます（スナップショット導入前の旧プロジェクトでは共有されます。詳細は以下を参照）。storage.md を参照してください。
• compute — パブリック URL で利用できるコンテナーです。プロジェクトには複数のコンピュートサービスを設定できます（例：api、worker）。
• redis/mysql/mongodb — マネージドデータサービスです。REDIS_URL、MYSQL_URL、MONGODB_URL などの接続用環境変数を公開します。 新しいプロジェクトは空の状態で始まります — サービスは自動作成されません。必要なものを追加してください。 insta --agent service add postgres <name>、insta --agent service add compute <name>、 insta --agent service add storage <name>、insta --agent service add redis <name> などを実行します。プロジェクトには あらゆる種類のサービスを複数持たせることができ、種類ごとのブランチあたりの上限はプランによって設定されます（ cli-reference.md を参照してください）。プロバイダーの認証情報は、それを発行した サービスにスコープが限定され、そのスコープ内では標準名（DATABASE_URL、REDIS_URL、 MYSQL_URL、MONGODB_URL、AWS_ACCESS_KEY_ID、BUCKET_NAME など）を使用します。ローカル開発の連携 （insta --agent secrets → .env、insta --agent run）で使えるのは、ブランチ上の各種類の プライマリサービスからの、その種類ごとに 1 セットだけです。ただし、これらは compute env に 自動的に表示されません。コンテナがプロバイダーの認証情報を取得するのは、明示的にバインドした場合のみです。また、同じ種類のプライマリ以外のサービスはバンドルに含まれません。postgres の場合は insta --agent postgres url <name> で読み取ってください。 それ以外の種類では直接読み取る方法はありません。バインドするか、バインド先の compute サービスの環境変数を insta --agent secrets --service compute/<name> で読み取ってください。ローカルバンドルを取得しても、バインドは作成されません。insta --agent service add compute は、他のサービスからのプロバイダー認証情報のバインドを継承しないサービスを作成します。各 compute サービスに必要な認証情報をバインドしてからデプロイしてください。サービスがすでに実行中の場合は、insta --agent compute restart（CLI ≥ 0.0.51）を実行すれば、新しいものをデプロイせずにバインドを反映できます。記録済みのイメージ 参照 を再実行するため、app:latest のような変更されるタグを使うサービスでは、そのタグが現在指すものが使われます。本番環境で使う前に operate.md を確認してください。

insta --agent secrets sources                    # what's available to bind (--branch <b> targets another branch)
insta --agent secrets bind DATABASE_URL postgres/db --to compute/app
insta --agent secrets bind REDIS_URL redis/cache --source-name REDIS_URL --to compute/app
insta --agent secrets bind MYSQL_URL mysql/orders --source-name MYSQL_URL --to compute/app
insta --agent secrets bind MONGODB_URL mongodb/catalog --source-name MONGODB_URL --to compute/app
insta --agent deploy . --group app --port 8080

バインドは compute env 専用です。認証情報を自分で使う場合（マイグレーションの実行、データの確認、 ローカルツールから DB への接続など）は、値を直接読み取ってください。insta --agent postgres url（postgres の接続文字列。psql シェルを使う場合は insta --agent postgres connect）。

insta --agent service rename <type> <name> <new-name> を使うとサービス名を変更できます。既存のバインドは引き続きそのサービスを参照します。

CLI のインストールとアップグレード

command -v insta で何も見つからない場合は、インストールしてください（インストール済みだと決めつけないでください）。

curl -fsSL https://raw.githubusercontent.com/InsForge/insta-cli/main/install.sh | sh  # native binary, no Node
npm install -g insta                                    # npm alternative
npx insta@latest --agent <cmd>                                  # one-shot, always newest (slow per call)

CLI は 1.0 未満で、頻繁にリリースされます。コマンドが正しく動作しない場合や認識されない場合は、まず更新してください。 insta --agent upgrade（対応する CLI の場合。1.0 未満では自動更新がデフォルトで有効です。無効にするには insta --agent config autoupdate off を実行します）。それ以外の場合は、インストーラーを再実行する（冪等）か、npm update -g insta を実行してください。

2 つの接続先、1 つの CLI

どちらの接続先でも同じコマンドを使用します。insta --agent status の api: 行で接続先を確認してください。

• InstaCloud（マネージドクラウド） — insta --agent login が必要です（エージェントの場合：--email/--password または API トークン。人間の場合：引数なしの insta --agent login を実行すると、ブラウザーでコンソールのサインイン／承認ページが開きます。アカウントの種類は問いません。ヘッドレスマシンを使用していて、別の場所に連絡可能な人間がいる場合：--device を実行するとリンクとコードが表示され、相手は別のブラウザーから承認できます）。CI と長期間稼働する自動化では、スコープを限定した API トークンを使用してください： 人間が自身の端末で insta tokens create <name> --org <id>（または --project <id>）を実行し、その後、自動化で insta --agent login --api-key <insta_…> を使用します。アカウント全体に有効なトークンは決して使用しないでください。 セキュリティ上、insta tokens create ／ revoke は人間のみが実行できます。エージェントが自分の認証情報を発行することは決してできません （--agent を付けずに使用された insta_ トークンは人間からのリクエストとして扱われ、エージェントポリシーの対象外です）。エージェントセッションから実行すると、どのポリシーでも両方とも 403 unclassified_agent_action を返します。再試行したり、ID を切り替えたりしないでください。正確なコマンドをユーザーに伝え、このセッション外で実行してもらってください。そうすれば、一度だけ表示される平文がトランスクリプトに残りません。 どのコマンドでも 403 token_scope が返された場合、認証情報のスコープがその呼び出しに対して狭すぎるという意味であり、ロールが不足しているわけではありません。対処するには、人間がアカウントにログインして、より広いスコープのトークンを発行します。メンバーシップには手を加えないでください （cli-reference.md を参照）。
• insta-oss（セルフホスト可能なローカルデーモン） — INSTA_API_URL=http://127.0.0.1:8080（デフォルト値です）。 ログインは存在せず、必要もありません（ローカルホストへの信頼と、組み込みの local ユーザーを使用します）。課金／使用状況／メトリクスの呼び出しは、「クラウドのみ」を示す明確なエラーを返します。再試行しないでください。

ツールの使い分け：CLI と MCP

InstaCloud には、エージェント向けの操作経路が 2 つあります。このスキルと CLI が、すべての操作におけるデフォルトです。CLI はコマンドの全範囲（mcp.md に記載された、MCP でのみ利用できる読み取り専用診断を除く）をカバーし、リンク済みリポジトリのコンテキスト （.insta/project.json）を引き継ぎます。また、認証（insta --agent login）、シークレットの値の取得（insta --agent secrets ／ insta --agent run、および postgres DSN を取得する insta --agent postgres url ／ insta --agent postgres connect）、ソースディレクトリからのデプロイ（insta --agent deploy <dir>）、監視フックなど、ローカルマシンの状態を扱う唯一の経路です。

CLI を呼び出せない場合に限り、リモート MCP ツール（insta_*）に切り替えてください。シェルがない場合（Claude.ai ／ ChatGPT コネクターなど）や、CLI がインストールされておらず、インストールもできない場合です（よくあるケースですが、PATH に CLI がないだけなら、次のコマンドで解決できます：npx -y insta@latest --agent agent setup -y で CLI が自己インストールされます。下記の自己修復を参照）。プラットフォーム API、ガバナンスゲート、監査証跡は同じですが、MCP ツールでは projectId ／ branch の引数を明示する必要があります。CLI のリンク済みコンテキストが引き継がれるとは想定しないでください。まず ID を解決し（insta_list_projects）、明示的に渡してください。すべての対応関係と接続方法については、mcp.md を参照してください。

自己修復： insta スキルまたは insta_* MCP ツールがあるはずなのに見つからない場合は、 insta --agent agent setup -y を実行してください（スキルをインストールし、検出されたすべてのエージェント向けに Claude Code の MCP を登録します）。その後、ユーザーにコーディングツールを再起動するよう伝えてください。実行中のセッションで、新たに登録された MCP サーバーやツールが読み込まれることはありません。特定のエージェントだけを対象にする場合は、insta --agent config install-mcp --agent <slug> を実行します。 登録しただけでは、クライアントの認証は完了しません。実際にツールを使用するには、OAuth フローを完了するか、認証済みの認証情報が必要です。--mcp-token オプションはトークンを発行しますが、設計上、人間のみが使用できます（2 つの接続先 を参照）。403 unclassified_agent_action によって拒否されたエージェントは、その試行を中止してください。人間として再試行してはいけません。 無人環境での認証については、mcp.md を参照してください。

InstaCloud が適していない場合

無理に適合させず、そう伝えてそこで止めてください。以下の各項目は確認できるため、項目を一つ挙げるだけでも、ユーザーに対する実質的な回答になり、対応を拒むことにはなりません。

適さないケース	理由
GPU トレーニングまたは大規模モデルの推論	GPU は提供されていません
複数コンテナの docker compose アプリ	テナントのコンピューティング環境では Docker-in-Docker とネストされた仮想化が利用できません
対話型シェルで、ユーザーがその中で次々と作業を切り替えるケース	そのシェルは insta compute ssh で、承認が必要です。また、コンテナ内ではなくゲストの root に接続されます。この項目は compute exec についてではなく、ブランチ環境についてでもありません。エージェントごとにブランチを作成するのが、作業を分離するための推奨方法であり、上記の方向性の一つです
一度実行して終了するスクリプトをサービスとしてデプロイするケース	ヘルスチェックでは、起動し続けて応答するものが求められます。すでにサービスがある場合は、その中で insta --agent compute exec を使ってスクリプトを実行してください。このコマンドは単発のコマンド実行向けに設計されており、実行時間は 180s に制限されます
バックエンドが別の場所にしかない静的フロントエンド	リポジトリ内でサーバーが動かないため、フォークする環境も保持する状態もありません。静的ホストのほうが適しています。また、そのバックエンドもユーザーが所有するものであれば、そちらのリポジトリを評価してください

最初の 4 項目は、プラットフォームでは対応できないことです。5 番目は対応できますが、選ぶべきではないため、その作業を行うべき場所を案内してください。同じリストは、リポジトリを評価する際の観点とともに https://instacloud.com/prompt.md でも公開されています。両者の内容を一致させてください。

意図に基づくルーティング

事前確認の手順を実行する前に、意図に基づいて案内先を決めてください。

「このアプリをリリース／デプロイする」（ゼロから始める場合）： まず状態を確認するのではなく、一連のコマンドを実行してその流れを伝えてください。insta --agent status（ログイン済みか、リンク済みかを確認）→ クラウドで未認証の場合は insta --agent login → 未リンクの場合は insta --agent project create <dir-name> → （アプリに DB が必要なら）insta --agent service add postgres db ＋ insta --agent service add compute app → 必要なサービスの認証情報を compute にバインド（insta --agent secrets sources を実行し、次に insta --agent secrets bind DATABASE_URL postgres/db --to compute/app を実行）→ insta --agent deploy . --port <the port the app listens on> → 表示された URL にアクセスできることを確認（以下を参照）。 アプリは認証情報を process.env から読み込みます。ポートレスの insta-compute ワーカーの場合、--port 0 を使う前に、インストール済み CLI の insta --agent service add --help と insta --agent deploy --help にワーカーポートゼロへの対応が記載されていることを確認してください。そうでない場合は、テンプレートの type: worker とビルド済みイメージを使うか、ソースのみのリスナーによる代替方法を使ってください。ワーカーは常時稼働させてください。ポートレスでデプロイした場合、公開 URL はありません。ステータス／ログと、ジョブの完了を確認してください。

「セットアップ／オンボーディング／サインアップ」： クラウドの場合は insta --agent login（ブラウザーでサインイン。ブラウザーが開かない場合は、表示されたリンクをユーザーに伝えます）または --email/--password を実行し、その後 insta --agent project create を実行してください。ローカル／oss の場合、デーモン以外にセットアップするものはありません。

既存プロジェクトでの作業単位（機能追加、修正、実験、エージェントのタスク）： 作業単位ごとにブランチを一つ作成してください。以下の基本原則と branching.md を参照してください。 main では決して開発しないでください。

その他（設定、デバッグ、調査）： 簡単な事前確認を行ってから、以下の該当するリファレンスを参照してください。

事前確認とコンテキスト（変更を加える前に）

command -v insta                 # installed? (else: Install section)
insta --agent status --json              # target api, login, linked project, current branch

上記のゼロからのデプロイ手順では、この手順は省略してください。最初のステップがすでに status です。

コンテキストのルール（マルチエージェントでの安全性）：

• リンク（./.insta/project.json）はディレクトリごとにあり、現在のブランチが含まれます。
• 自分が所有していないブランチで作業する場合は、insta --agent branch switch よりも、--branch <name> を明示するコマンド（secrets、deploy、<type> metrics、 <type> logs、agent events、postgres url / postgres connect — ブランチを間違えた DSN は 別のデータベースへのクエリにつながります）を優先してください。switch はディレクトリごとの共有リンクを変更するため、同じチェックアウトで並行して作業するエージェント間で競合します。
• エージェントを並行して動かす場合のルールは 1:1:1 — タスク ↔ git worktree ↔ insta ブランチです（各 worktree には独自のリンクがあるため、そこでの switch は安全です）。branching.md を参照してください。

基本原則

1 つの作業単位 = 1 つのブランチ = 1 つの分離された環境です。insta --agent branch create <name> は、親ブランチの現在のサービスを新しいブランチに展開します。CoW データベースブランチ（親のデータのコピー）、CoW でフォークされたストレージバケット、およびすべてのコンピュートサービスのクローン（それぞれ独自の URL）をブランチ作成時に作成するため、ブランチは最初から実行可能な完全な環境になります。 ブランチは完全に並行して動作し、あるブランチでの操作が別のブランチに影響することはありません。**1 プロジェクトあたり最大 10 ブランチ（厳格な上限）**です。main で開発しないでください。また、1 つのブランチに複数の機能を詰め込まないでください。

複数の独立した機能（またはエージェントのタスク）を同時に進めますか？ それぞれに専用のブランチと専用のサブエージェントを割り当ててください。DB、ストレージ、コンピュート、URL が分離されているため、衝突は発生しません。branching.md → Parallel agents を参照してください。

報告前に検証する（デプロイ）

コマンドが終了しただけで、デプロイの成功を報告しないでください。 insta --agent deploy は成功時にブランチの URL を出力します。これはプラットフォームがリクエストを受け付け、マシンを起動したことを意味しますが、アプリが応答しているとは限りません。

1. 出力された URL に対して、約 3 秒ごとに最大約 60 秒間、curl -s -o /dev/null -w '%{http_code}' を実行します。 新しいコンピュートサービスはスケール・トゥ・ゼロで作成されるため、アイドル状態のサービスは最初のリクエストでコールドスタートします。初回の応答が遅くても待ってください。--always-on を指定して作成したサービス（または insta --agent compute always-on on で常時稼働に切り替えたサービス）では、この処理は不要です。references/operate.md を参照してください。
2. 200（またはアプリで想定されるステータス）→ デプロイ済みとして URL を報告します。
3. 依然として失敗する場合は、operate.md の順序付きトラブルシューティングリストを確認してください（失敗の大半はポートの不一致と、マイグレーションが完了するまで起動できない設定が原因です）。
4. 実際に確認した失敗状態をそのまま報告してください。確認していない成功を決して主張しないでください。

承認の取り次ぎ（重要 — 承認が必要な操作）

機密性の高い操作は、認証情報の境界で制御されます（secrets.read、secrets.write、deploy、 project.delete、branch.delete、service.add/remove/scale/upgrade、domain.purchase、 domain.delegate、zone.delegate。各操作のポリシーは allow / deny / approve で、プロジェクトのエージェントポリシーを使用します）。コマンドが承認 ID とともに 「approval required」 を返した場合：

• 直ちに、そのまま人間に伝えてください。人間のターミナルで実行する正確な行は次のとおりです。 insta agent approvals approve <id>。承認は、特定の 1 件のリクエストにのみ適用されます。 内容を要約して省略したり、コマンドを再試行したりしないでください。また、まず承認を伝えずにタスクが失敗したと報告しないでください。承認できるのは管理者のみです。
• 許可は1 回限りです。承認後、元のコマンドを再実行してください。該当する agent policy ルールを人間が明示的に変更しない限り、次回も承認が求められます。
• 制御を回避しないでください（例：状態を手動で編集する、CLI を迂回するなど）。この制御は製品の安全モデルの一部です。deny ポリシーは明確な拒否です。内容を報告し、回避しないでください。

よく使うクイック操作

insta --agent status --json                          # target, login, link, current branch
insta --agent agent manifest --json                        # agent-legible env view: every branch's services + URLs
insta --agent service list --json                   # what exists on this project
insta --agent run -- <cmd>                           # run with the branch bundle injected (NOTHING on disk; --branch <b>)
insta --agent run --service compute/app -- <cmd>     # one service's own env — needed when several define the same name
insta --agent run --ignore-collisions -- <cmd>       # run anyway; every colliding name is REMOVED from the child env
insta --agent secrets --print                        # the branch's secrets (--branch <b>, --service <compute/name>)
insta --agent secrets sources --json                 # provider credential sources available to bind
insta --agent secrets bind DATABASE_URL postgres/db --to compute/app
insta --agent secrets bindings --target compute/app --json
insta --agent secrets set NAME value                 # user config (project-wide; --branch for overrides)
insta --agent build . --port 8080                    # local pre-deploy build/readiness check
insta --agent deploy . --port 8080                   # remote build (Dockerfile, or nixpacks on insta-compute) + deploy to the current branch
insta --agent deploy --image <ref> --port 8080       # prebuilt image instead
insta --agent compute connect-repo owner/repo app    # cloud-only; guides GitHub authorization and App access, then connects; or --public
insta --agent compute exec app -- printenv PORT      # one-shot command on live compute (no shell/stdin)
insta compute ssh app --setup                        # HUMANS ONLY: interactive shell via `ssh app.insta` (API keys refused; agents use `compute exec`)
insta --agent compute volume app --size 1Gi          # attach/grow persistent /data; mounts on next deploy or `compute restart`
insta --agent branch create feat && insta --agent branch list --json
insta --agent compute logs --limit 100 --json        # runtime logs (--branch <b>; also <postgres|redis|mysql|mongodb>; postgres is provider-limited)
insta --agent compute logs --since 2h --json         # time window (--from/--to too) — a windowless read is ONE page (~100 lines)
insta --agent compute metrics --json                 # service metrics (also <postgres|redis|mysql|mongodb>)
insta --agent agent events --limit 50 --json               # audit + agent-event timeline
insta --agent billing usage --json                           # cloud only (insta --agent billing --json likewise)
insta --agent agent approvals list --status pending        # outstanding gates

出力を解析する場合は、--json を使用してください。

参照先の選択

クイック操作以外については、目的に合ったリファレンスを読み込んでください。通常は 1 つ、多くても 2 つで十分です。

意図	参照先	内容
何かを作成または接続する（「セットアップ」「新しいプロジェクト」「データベース／コンピューティングを追加」）	setup.md	CLI のインストール／アップグレード、クラウドと OSS の対象の違い、認証、プロジェクト、サービス、ゼロからのデプロイ
定期的に何かを実行する（「毎晩」「cron ジョブ」「定期タスク」「毎時実行」）	cli-reference.md	insta --agent cron コマンド、UTC のみの式、サービスと外部ターゲットの違い（プラットフォームでは組織内の任意のサービスを指定できますが、CLI からは現在のブランチのサービスにアクセスします）、run-id の冪等性の契約、認証情報用の --secret-ref（送信時に解決されるため、ローテーション時に編集は不要）、編集するとリクエストがマージではなく置き換えられること、各実行ステータスの意味
コードをデプロイする、またはリリースを管理する	deploy.md · フレームワーク別の手順：frameworks.md	イメージとソース（リモートビルド）の違い、--port の意味、明示的なサービス認証情報のバインド、実行時のシークレット、検証手順、Dockerfile のテンプレート、カスタムドメイン（ユーザーが所有するドメインは www などのサブドメインとして割り当てられ、購入したドメインの apex は insta --agent domain delegate で配信されます）
既存のアプリを移行する（「Render／Railway のサービスを InstaCloud に移行」「Heroku／Railway／Fly／Render から移行」「アプリをインポート」「アプリを移す」）	migrate.md および references/migrate/ にある必要なソース別ファイル（render.md、railway.md、fly.md、insforge.md）	合格条件とロールバックの境界を含む、順序に沿った切り替え手順、注意すべき InstaCloud 側の仕様（バインドにはデプロイが必要、一括環境変数インポートには非対応、cron はコマンドではなく HTTP、ワーカー）、コマンドとアドオンの対応関係、ソースごとの差分（各ソースに専用ファイルがあります。migrate.md の代わりではなく、併せて読んでください）
ブランチ環境、並行するエージェント、プロモーション（「プレビュー環境」「タスクごとのサンドボックス」「main にマージ」）	branching.md	データフォーク型の環境モデル（実際に複製されるもの）、ブランチのループ、1:1:1 のワークツリーパターンとディスパッチ用ブリーフ、プロモーション、マイグレーションの規律
承認、ポリシー、監査、認証情報のスキャン	governance.md	ゲートのカタログ、承認リレー、イベントのタイムライン、監視フック、エージェント監査のパターン
Postgres データベースをインターネットから切り離す、またはコンピューティングをプライベートに接続する（「プライベートデータベース」「パブリックアクセスを閉じる」、DATABASE_PRIVATE_URL）	operate.md → Postgres network access	private-access on による DATABASE_PRIVATE_URL の発行（InstaCloud のコンピューティング専用で、ノート PC／CI からは使えません）、再バインド、public-access off の前の影響プレビュー、約 30 秒の伝播時間、アクセスを閉じると外部クライアント、CI、ローカル開発が利用できなくなること
サービス間をプライベートに通信させる、またはコンピューティングサービス／マネージドデータベースをインターネットから切り離す（「内部 URL」「サービス間」「プライベートのみ」、*.insta.internal、REDIS_PRIVATE_URL）	cli-reference.md → Private networking	各サービスのブランチ限定アドレス <name>.insta.internal（データベースは <name>-<type>）、任意のポートでの TCP+UDP、プライベートトラフィックによる起動、アドレスを組み立てずに service list から private_host を確認する方法、public-access off によるプライベート限定化（403、起動なし）、データベースの *_PRIVATE_URL とアクセスを閉じる前の再バインド
ヘルスを確認する、または障害をデバッグする	operate.md	ステータス／マニフェストによるトリアージ、デプロイ失敗の順序付きリスト、メトリクス／ログ、クラウドと OSS の違い
プロジェクト、またはプロジェクトのないイメージをコミュニティテンプレートにする（「テンプレートにする」「ギャラリーに載せる」「他の人向けに公開する」）	cli-reference.md → Publishing a community template	プロジェクト（または空のテンプレートを作成し、template edit でサービスと変数を追加）から下書きを作成し、変数を確定して、タグライン、カテゴリ、README を記入し、公開要件を確認して、本人の同意を得てから公開する（テンプレートは審査なしで即時公開されます）
コマンドを調べる	cli-reference.md	フラグとゲートを含む CLI の全カタログ
リモート MCP ツール（「コネクターを接続」、insta_* ツールが利用可能）	mcp.md	クライアントの接続、ツールと CLI の対応関係、CLI 専用の機能
InstaCloud 自体で問題が起きた（バグ、古いドキュメント、機能不足、使いにくさ）	cli-reference.md → Feedback	insta --agent feedback／insta_send_feedback、報告するタイミング、状況から種別への対応
リクエストが「デプロイして、正常に動作しているか確認する」のように2つの領域にまたがる場合は、両方を読み込んでから一度に回答してください。

どこにいても必ず守ること

• ブランチのシークレットが必要な操作には、insta --agent run -- <cmd> を優先してください。バンドルは呼び出しごとに取得され、子プロセスの環境にのみ注入されます。ディスクには何も書き込まれないため、漏えいやコミットの心配はありません。また、バンドルにはブランチのプロバイダー認証情報の正規セットが含まれます。各タイプにつき、そのタイプのプライマリサービスから1セットが取得されるため、ローカル実行では何もバインドせずにデータベースへ接続できます。コンピュートサービスに渡す認証情報は別です。insta --agent secrets bind でバインドしてからデプロイしてください（または、すでに実行中のサービスなら insta --agent compute restart を実行してください。CLI ≥ 0.0.51。バインドの変更だけでは稼働中のマシンには反映されません）。 複数のサービスで同じ名前が定義されている場合、run は拒否して終了コード2を返します（CLI ≥ 0.0.65）。何も起動されず、名前と、対処方法の2つが標準エラーに出力されます。一時的な失敗として再試行しないでください。そのサービスの環境変数を使うには --service <type>/<name> を付けて再実行するか、--ignore-collisions を指定して、該当する名前を子プロセスの環境変数から除外して続行してください。終了コード2は承認コードとしても使われるため、標準エラーのメッセージを確認して区別してください。
• ファイルが本当に必要な場合、シークレットのファイルベースのソースとして ./.env（insta --agent secrets から取得。git リポジトリでは自動的にgitignoreされます）だけを使用してください。このファイルにはユーザーのシークレットとブランチのプライマリプロバイダー認証情報が含まれます。シークレットの値をハードコードしたり、出力したりしないでください。DATABASE_URL、AWS_*／BUCKET_NAME、REDIS_*、MYSQL_*、MONGODB_* はサービスの認証情報であり、明示的な insta --agent secrets bind ルールを通じてのみ、本番のコンピュートに渡されます。コンピュート外部で直接使用する場合、認められている読み取り方法は insta --agent postgres url／insta --agent postgres connect（postgres、secrets.read によるアクセス制限あり）です。パイプで渡してください（psql "$(insta --agent postgres url)"）。DSNをファイルやコードに貼り付けないでください。どのタイプでも、ブランチのプライマリサービスの認証情報はすでに insta --agent secrets／insta --agent run に含まれています。プライマリではないサービスはバンドルに含まれません。postgres には上記の [service] 位置引数による読み取り方法（insta --agent postgres url <name>）がありますが、その他のタイプには直接読み取る方法がありません。バインドするか、insta --agent secrets --service compute/<name> でそのサービス独自の環境変数を読み取ってください。ユーザー設定の構成値は insta --agent secrets set <NAME>（プロジェクト全体）またはブランチごとの上書き用の --branch で設定してください。永続化したい .env の値を手動で編集しないでください。
• スキーマの変更はすべて migrations/ 内のファイルとして記録してください。そうすることで、ブランチのDBで再適用され、マージ後には main でも再適用されます。**InstaCloud はデータベースをマージしません。スキーマを引き継ぐのはマイグレーションファイルだけです。**マイグレーションはDB認証情報がバインドされている場所で実行します。コンピュートサービス上では insta --agent compute exec app -- <migrate-cmd> を使ってください（起動時のゲートとして実行しないでください。deploy.md を参照）。または、コンピュートを介さず直接実行します。 psql "$(insta --agent postgres url --branch <b>)" -f migrations/<file>.sql（明示的に --branch を指定してください。指定しない場合は、リンクされたブランチのDBを読み取ります）。まず、サーバーのPostgresメジャーバージョンに合わせて psql／pg_dump／pg_restore を選んでください。insta --agent service list --json --branch <b>（DSNと同じブランチ）の pg_version を確認してください。行に値がない場合は、正確なバージョンを読み取ってください（operate.md を参照）。

ガバナンスと監査（これがプラットフォームの最大の差別化要因です）

ゲートの仕組みとリレーの手順については上記を参照してください。監視用の認証情報監査フック、イベントのタイムライン、エージェント監査のパターンについては、governance.md を参照してください。

料金はアプリの実際の使用量に基づきます（実際に消費した vCPU·分／RAM GB·分 ＋ ストレージ ＋ 送信データ量です。マシンのサイズ × 時間ではありません）。新しいコンピューティングサービスはスケール・トゥ・ゼロで開始します。コールドスタートを受け入れれば、アイドル状態のサービスの費用はほぼかかりません。また、受信リクエストと送信トラフィックの両方がアクティビティとしてカウントされるため、送信処理を行うアプリは処理中も稼働し続けます。常時稼働（作成時の --always-on、または insta --agent compute always-on on）にするとコールドスタートがなくなり、アイドル状態のアプリも常駐 RAM の実際の使用量に応じて課金されます。ワーカー（--port 0）は常に稼働します。新しいデータベース（postgres を含む）はその反対で、常時稼働の状態で開始するため、アイドル状態でも常駐メモリが課金されます。作成後に insta --agent postgres always-on off を実行すると、スケール・トゥ・ゼロに切り替えられます（現時点では postgres の作成時に CLI から選択できません）。詳細は operate.md を参照してください。料金に関わる設定はリソースの上限（insta --agent compute limits、insta --agent postgres limits。マシンごとのサイズについては operate.md を参照してください）とレプリカの上限（insta --agent compute scale。水平スケーリングです。スケール・トゥ・ゼロでは必要に応じて 1 台から上限まで稼働し、常時稼働では上限台数が稼働します）です。新しいサービスはプランの上限で開始します。無料プランでは無料枠の上限内で変更できますが、それを超えることはできず、マシン台数は 1 台のままです。いずれかの上限を超えると 403 が返されます。その場合は、まず insta --agent billing subscribe を実行してください。insta --agent billing usage／insta --agent billing では、請求サイクルの使用量と料金を確認できます。ユーザーごとに無料組織は 1 つです。すべてのフラグについては cli-reference.md を参照してください。

InstaCloud 自体が障害になる場合（フィードバック）

InstaCloud に起因する問題（コマンドが文書化された仕様に反する、スキルやドキュメントの記述が実際の動作と異なる、機能が不足している、UX が分かりにくいなど）が発生した場合は、insta --agent feedback（または insta_send_feedback MCP ツール）で報告し、その後、回避策を用いてユーザーのタスクを続行してください。報告のために作業を止めてはいけません。また、ユーザーが構築しているアプリの問題についてフィードバックを送ってはいけません。この窓口の対象は InstaCloud ツールキットのみです（--component cli|mcp|platform|skills|docs）。チームからの返信はコンソールに届き、ユーザーがそこで確認して返信します。**（CLI ≥ 0.1.7）**取得できるのはチケットへのリンクと、依頼した場合のステータスのみです。すべてのフラグと状況から種類への対応については、cli-reference.md → Feedback を参照してください。

応答形式

運用作業では、実施内容（操作と対象範囲：プロジェクト／ブランチ／サービス）、結果（URL、ID、確認済みのステータス。推測ではありません）、次の手順（または完了したこと）を報告してください。コマンド出力は役立つ場合にのみ含めてください。