Gemini Cloud Agent

OpenRouter、OpenCode Zen、Google Gemini、または TokenRouter を介したモデルを使用してリモート Linux コンピュータを操作するための完全な Web アプリケーション: マルチステップチャット、永続的な Vercel Sandbox、ターミナル、ファイル、プライベートアップロード、検証可能なアーティファクト、Git、プレビュー、MCP Streamable HTTP サーバー。

エージェントは、ユーザーが実行するコマンドを返すだけではありません。タスクにコードやファイルが必要な場合、サンドボックス内の実際のツールを使用し、stdout/stderr を読み取り、障害を修正し、結果を検証して、ファイルをダウンロード用に公開します。

実装されているもの

• Next.js 16、React 19、TypeScript、Tailwind CSS 4、shadcn/ui。

• モバイル/デスクトップインターフェース: サイドバー、チャット、ツールカード、ログ、アップロード、STOP、続行、履歴、アーティファクト、ダウンロード。

• 推奨オプションとしての OpenRouter Free Models Router、選択可能な OpenCode Zen/Google Gemini/TokenRouter、function calling、AI SDK 7 の ToolLoopAgent。

• MAX_AGENT_STEPS によって制限されるマルチステップループ。

• 分離された microVM、永続的なファイルシステム、ユーザー/ワークスペースごとに名前が付けられたサンドボックスを備えた Vercel Sandbox 3。

• シェル、ファイルシステム、Git、Web/ダウンロード、プロセス、アーカイブ、アーティファクト、実際のポートプレビュー。

• Google を使用した Supabase Auth、Postgres/RLS、プライベート Storage。

• 署名付き URL による直接アップロード。Vercel Function のボディ制限を回避。

• サイズ、SHA-256、MIME、データベース記録、短い署名付き URL を持つアーティファクト。

• /mcp 上のステートレスなリモート MCP、最新の Streamable HTTP、OAuth 2.1 + PKCE/DCR、互換性のための Bearer。

• 19 の Claude 互換機能の段階的カタログを備えた MegaBrain Skills、サンドボックスにインストール可能なリソース、監査可能な出所/ライセンス。

• ブラウザのキャンセルをモデル/コマンドに伝播し、サンドボックスを中断。

• ローカルセキュリティテストと、必須の 5 つのシナリオに対する実際のクラウドスイート。

Related MCP server: sandbox-as-a-service-mcp

アーキテクチャ

Browser / celular
      │
      ├── Supabase Auth (Google)
      ▼
Next.js UI + Route Handlers
      ├── Postgres/RLS ─ mensagens, runs, tools, workspaces
      ├── Storage privado ─ uploads e artifacts
      ▼
ToolLoopAgent (AI SDK) ─ OpenRouter / OpenCode Zen / Google / TokenRouter
      │ tool              ▲ resultado real
      ▼                   │
Tool layer ─ Vercel Sandbox (microVM Linux persistente)
      ├── /workspace/uploads
      ├── /workspace/source
      ├── /workspace/output
      ├── /workspace/temp
      ├── /workspace/logs
      └── /workspace/metadata

Clientes MCP ─ OAuth/Bearer ─ POST /mcp ─ Vercel Sandbox persistente

各ワークスペースには、user_id + workspace_id から SHA-256 で導出された名前が付けられます。persistent: true により、セッションが停止した後もファイルシステムを復元できます。アプリケーションのシークレットはサンドボックスに注入されません。

前提条件

• Node.js 22+。

• Supabase プロジェクト。

• 互換性のある API キーが少なくとも 1 つ: OpenRouter、OpenCode Zen、Google Gemini、または TokenRouter。

• Sandbox にアクセスできる Vercel プロジェクト。

• ローカル: Vercel トークン、チーム ID、プロジェクト ID。デプロイでは、OIDC は自動です。

エンドユーザーのコンピュータは実行に関与しません。デプロイ後、タスクとビルドはクラウドで実行されます。

インストール

git clone <seu-repositorio>
cd gemini-cloud-agent
npm install
cp .env.example .env.local

.env.local に入力し、マイグレーションを適用して、実行します:

npm run dev

アプリケーションは http://localhost:3000 で開きます。

環境変数

完全なソースとして .env.example を使用してください。

DEV_AUTH_BYPASS=true は開発専用であり、サービスロールが必要で、本番環境では無視されます。

Supabase

データベースと Storage

プロジェクトをリンクして、マイグレーションを適用します:

npx supabase login
npx supabase link --project-ref <project-ref>
npx supabase db push

マイグレーションは、workspaces、conversations、messages、agent_runs、tool_calls、files、artifacts、sandboxes、インデックス、制約、トリガー、およびプライベートバケット uploads/artifacts を作成します。

現在のプロジェクトでは新しいテーブルが自動的に公開されない可能性があるため、テーブルには authenticated への明示的な grants が与えられます。RLS は、SELECT、INSERT、UPDATE、DELETE で引き続き (select auth.uid()) = user_id を要求します。

Google Auth

1. Supabase で: Authentication → Providers → Google。

2. Google の Client ID/Secret を設定します。

3. Google Cloud Console で Supabase が示すコールバックを追加します。

4. リダイレクト URL に http://localhost:3000/auth/callback と本番 URL を含めます。

サーバーは getSession() ではなく supabase.auth.getClaims() で認証します。

アップロード

バケットはプライベートです。オブジェクトパスの最初のセグメントは常に auth.uid() です。ブラウザは createSignedUploadUrl + uploadToSignedUrl を使用します。その後、サーバーは認証されたオブジェクトをダウンロードしてサンドボックスに具体化します。これにより、最大 50 MB のアップロードが Vercel Function のボディに入りません。

モデルとエージェントループ

デフォルトでは、OPENROUTER_API_KEY を設定し、OPENROUTER_MODEL=openrouter/free を維持します。このルートは、ツールを含む呼び出しの要件をサポートする無料モデルを選択します。無料モデルは可用性が変動し、制限が低い場合があります。モデルを固定するには、OpenRouter カタログの現在の :free ID を使用します。

AI_PROVIDER=auto は、この順序で存在する最初のキーを選択します: OpenRouter、OpenCode Zen、Google、TokenRouter。統合を固定するには、対応する名前を使用します。OpenCode Zen は公式の OpenAI 互換エンドポイントとデフォルトの無料モデルを使用します。Google Gemini は GEMINI_MODEL で設定されたモデルを受け入れます。TokenRouter は OpenAI 互換エンドポイントを使用します。

選択は src/lib/ai/provider.ts にあり、キーはブラウザやサンドボックスに送信されません。

システムプロンプトは、エージェントにリモートコンピュータの使用、結果の検査、stderr の処理、障害の修正、ファイルの検証、artifact_publish の呼び出し、プライベートな推論の非表示、許可なしの外部プッシュの禁止を強制します。

ループは、モデルが完了したとき、不可能な条件/キャンセルが発生したとき、または MAX_AGENT_STEPS に達したときに終了します。

MegaBrain Skills

エージェントと MCP は、オンデマンドでロードされるスキルカタログを公開します。名前と説明のみが常にコンテキストにあります。skill_read は関連する手順をロードし、skill_resources はスクリプト/参照/アセットを照会し、skill_install は microVM で実行する必要がある場合に完全なパッケージを /workspace/metadata/skills/<名前> にコピーします。

バージョン管理されたマニフェストは、234 のリソースそれぞれのパス、サイズ、SHA-256 を記録します。14 の公式スキルは、使用時のみ Anthropic の固定コミットから取得され、各バイトがマニフェストに対して検証されます。5 つのネイティブスキルはデプロイメント自体にあります。これにより、アップストリームブランチの将来の変更を受け入れずに、デプロイを軽量に保ちます。ソースを更新した後、npm run skills:manifest でマニフェストを再生成します。

カタログは、anthropics/skills のコミット 3b3fad96af16a10759d930941b4520ba0c40edae で 2026 年 8 月 24 日に固定されました:

• 14 の公式 Apache 2.0 スキル: academy-guide、algorithmic-art、brand-guidelines、canvas-design、claude-api、discernment-nudge、frontend-design、internal-comms、mcp-builder、skill-creator、slack-gif-creator、theme-factory、web-artifacts-builder、webapp-testing。

• 5 つの同等のネイティブ実装: doc-coauthoring、docx、pdf、pptx、xlsx。

4 つの公式ドキュメントスキルはソース利用可能のみであり、Anthropic サービス外でのコピー/再配布を禁止しています。doc-coauthoring は再配布ライセンスを公開していません。そのため、これら 5 つは MegaBrain 用に独自に再実装され、制限された素材を組み込まずにカバレッジを維持しています。監査は skills/PROVENANCE.json にあり、各公式パッケージは独自の LICENSE.txt とサードパーティの通知を保持しています。

Vercel Sandbox

プロジェクトは、SDK の現在のユニバーサルイメージ、永続的なサンドボックス、/workspace を使用します。作成時に vCPU、タイムアウト、ポートを設定します。分離は Firecracker microVM です。Vercel プランの制限がアプリケーション設定よりも優先されます。

開発では、3 つの Vercel 資格情報を入力します。Vercel デプロイでは、SDK は OIDC を自動的に使用します。

Android/重いツールチェーンの場合は、JDK、Android command-line tools、SDK、Gradle がすでにインストールされた独自の OCI/VCR イメージを使用します。カスタムイメージがない場合、エージェントは永続的なサンドボックスに依存関係をインストールできますが、時間とディスクの制約があります。

ツール

• skill_list、skill_read、skill_resources、skill_install

• workspace_info

• shell_execute

• file_list、file_read、file_write、file_edit、file_delete

• mkdir、move_file、copy_file

• artifact_list、artifact_publish

• git_clone、git_status、git_diff

• download_url、web_fetch

• create_archive、extract_archive

• process_list、process_kill

• expose_port

shell_execute は、Next.js プロセスではなく、microVM で bash -lc を呼び出します。Python、pip、Node、npm、Git、curl、zip、Java、Gradle など、存在する/インストールされたツールをサポートします。

アーティファクト

artifact_publish(path) はパスを解決/保護し、実際のファイルを読み取り、空/過大なサイズを拒否し、SHA-256 を計算し、MIME を検出し、プライベートバケットに送信し、Postgres に記録し、/api/artifacts/:id/download を返します。ダウンロードはユーザーを検証し、60 秒間有効な署名付き URL を作成します。

パネルは、artifacts の実際のレコードに対してのみダウンロードを提供します。

APKG

偽のジェネレーターは存在しない。エージェントはgenankiなどの実際のライブラリをインストールし、パッケージを生成し、ZIP/データベース/サイズ/ハッシュを検証して公開する。クラウドスイートは3枚のカードを持つTesteデッキをカバーする。

Android APK

エージェントはJDK/Gradle/Android SDKをインストールし、./gradlew assembleDebugを実行できる。事前にウォームアップされたVCRイメージが推奨される。PushとフォールバックのGitHub Actionsは自動ではない。認証情報とブランチ/pushに対する明示的な承認が必要である。MVPは外部への変更なしで公開のclone/status/diffを提供する。

プレビュー

サンドボックス内でサーバーをバックグラウンド/デタッチで起動し、expose_portを使用する。ポートはSANDBOX_EXPOSED_PORTSに含まれている必要がある。リンクはsandbox.domain(port)を使用し、セッションがアクティブな間存在する。

キャンセル

STOPはHTTPストリームをキャンセルする。vercel.jsonはsupportsCancellationを有効にし、AbortSignalはモデルとコマンドに到達する。アプリケーションはsandbox.stop()を呼び出し、セッションのプロセスを終了する。永続ファイルシステムは後で復元できる。

リモートMCP

このインストールのエンドポイント: https://gemini-cloud-agent.vercel.app/mcp

トランスポートはステートレスなStreamable HTTPである。POSTがサポートされ、GET/DELETEは405を返す。サーバーはOAuthディスカバリー、動的クライアント登録、Authorization Code + PKCE、リフレッシュトークンを公開する。これにより、Gemini SparkでURLを追加するだけでよい。

Gemini Sparkの場合:

1. Settings & help → Connected Appsを開く。

2. Custom apps for Sparkで、Add a custom appを選択する。

3. https://gemini-cloud-agent.vercel.app/mcpを貼り付けて進む。

4. Autorizar Gemini Cloud Agent画面で、MCP_SECRETの値を入力する。

接続はリストに存在するだけで自動的に有効化されるわけではない。接続後、/goalまたは/metaを使用し、完全な結果を説明する。2つのプロンプトはリクエストをgoal_runに転送し、goal_runはコンピューターを作成/再利用し、スキルを選択し、コマンドを実行し、成果物を検証し、単一の複合呼び出しでファイルを公開する。プロンプトメニューが表示されない場合は、自然言語で依頼する: @Gemini Cloud Agent use goal_run para ...。

ツールを使用する前に表示されるセキュリティ確認はGemini/Googleが制御する。サーバーはAllowをクリックしたり、その保護を無効化したりすることはできない。複合フローはタスク全体を1回の初期確認に削減する。破壊的なアクションは引き続き明示的である。

古いクライアントはBearerを直接使用することもできる:

Authorization: Bearer SEU_MCP_SECRET

互換性設定:

{
  "name": "CloudComputer",
  "url": "https://SEU-DOMINIO/mcp",
  "headers": { "Authorization": "Bearer SEU_MCP_SECRET" }
}

ツール: goal_run、skill_list、skill_read、skill_resources、skill_install、workspace_create、workspace_delete、workspace_info、shell_execute、file_list、file_read、file_write、file_edit、git_clone、artifact_list、artifact_publish。

すべてworkspace_idで動作する。各IDはMCP_USER_IDの名前空間内の名前付きサンドボックスにマッピングされる。MCPはターミナルとファイルについてSupabaseに依存せず、シークレットがマイクロVMやモデルに送信されることは決してない。

goal_runは、ZERO_COST_MODE=trueの場合、設定された無料プロバイダー/モデルのみを使用する。/workspace/output内の新規または変更されたファイルは自動的に公開される。結果には署名付きのdownload_urlが含まれ、24時間有効である。期限切れ後は、artifact_publishを再度実行して別のリンクを生成する。workspace_deleteは指定されたコンピューターを終了して削除するため、その削除が本当に必要な場合にのみ使用すべきである。

公開インストールをエンドツーエンドで検証するには — OAuth、MCPカタログ、実際のLinux、自律的なgoal、ファイルコンテンツ、署名付きダウンロード、クリーンアップ — 以下を実行する:

npm run test:cloud

Vercelデプロイ

1. リポジトリをGitプロバイダーに送信する。

2. Vercelダッシュボードにインポートする。

3. 本番環境変数を設定する。

4. Sandboxへのアクセスを確認する。

5. Supabase/Googleで本番コールバックを設定する。

6. デプロイする。

同等のローカル検証:

npm run typecheck
npm run lint
npm test
npm run build

ルートは延長された期間を宣言するが、実効制限はプランに依存する。コマンドはサンドボックスで実行され、Web関数はループ/ストリーム中は稼働し続ける。

セキュリティ

• 任意のコードはVercel Sandbox内のみ。

• アプリケーションのenv/シークレットはサンドボックスに注入されない。

• すべてのテーブルとStorageでユーザーごとのRLS。

• Service roleはサーバーのみ。

• shell_executeはWebインターフェースでSupabaseセッション、MCPでOAuth/Bearerを要求する。

• MCPシークレットは定数時間で比較される。

• パスは/workspaceに正規化/制限され、ルート削除はブロックされる。

• ツールのURLはlocalhost、リンクローカル、プライベートIPをブロックする。

• ZIP/TARは展開前にトラバーサルに対して検証される。

• タイムアウト、ステップ、vCPU/メモリ、アップロード、アーティファクト、ディスク、読み取り、出力が制限される。

• ログはコンテンツを切り詰め、トークン/シークレット/パスワード/APIキーを編集する。

• リモートへのpush/commitはデフォルトでは公開されない。

ディスクは操作の前後でチェックされる。Sandboxの物理的な制限が、急速に増大するコマンド実行中の障壁となる。高リスクの本番環境では、networkPolicyも必要なドメインに制限する。

コストと無料枠

• ダッシュボードにアクティブな制限が表示される。

• ステップ/タイムアウトにより、ループや放置されたセッションを防ぐ。

• 出力/読み取りの制限により、モデルに送信されるコンテキストが削減される。

• Supabase Freeには現在、データベース、ストレージ、エグレスのクォータが含まれる。ファイルあたりの最大アップロードは50 MB。現在の表を確認すること。

• OpenRouter Free Modelsは共有制限が低く、本番環境には適さない。各モデルの可用性は異なる。

• Geminiを使用する場合、AI Studioに表示されるプロジェクト/モデルごとのクォータがある。

• Vercel SandboxはアクティブなCPUに対して課金され、プランは期間/リソースを制限する。アプリケーションを公開する前にクォータを確認すること。

出典: OpenRouter free models、Supabase pricing、Gemini rate limits、Vercel Sandbox。

テスト

ローカル、クラウドなし:

npm test

トラバーサル、プライベートURL、サニタイズ、編集を検証する。

実際のクラウド:

npm run test:cloud

このコマンドは公開本番エンドポイントを使用し、OAuth、MCP初期化、スキルの読み取り/インストール、ワークスペース作成、ファイルの書き込みと読み取り、Linuxコマンド、自律的なgoal_run、自動公開、署名付きダウンロード、バイト単位の正確な比較を実行する。最後に、自分が作成した一時ワークスペースのみを削除する。

TEST_USER_IDと追加のローカル認証情報に依存する旧管理スイートは、npm run test:cloud:extendedとして引き続き利用可能である。

既知の制限

• shell_executeはstdoutとstderrをイベントログとインターフェースのターミナルに段階的に送信する。ターミナルは監視用であり、手動入力のための対話型PTYは公開しない。

• 永続ファイルシステムはVercelプランの機能/スナップショットに依存する。

• Android SDKはユニバーサルイメージで保証されない。予測可能性のために独自のVCRを使用すること。

• 認証済みGitHub/push/Actionsには明示的な認可フローが必要である。

• PDFはサンドボックス内にインストールされたライブラリで処理され、信頼できないコンテンツをWebプロセス外に保持する。

• クラウドスモークテストは、予期しないコスト/外部書き込みを避けるため、シークレットなしではCIで実行されない。

トラブルシューティング

Supabaseが設定されていない

URLと公開可能/匿名キーを確認し、マイグレーションを適用してサーバーを再起動する。

Googleログインがホーム画面に戻る

プロバイダー、SupabaseのリダイレクトURL、Googleのコールバックを確認する。本番環境では正確にhttps://SEU-DOMINIO/auth/callbackを使用する。

401/403または空のテーブル

マイグレーションを実行する。Data APIのgrants、RLSポリシー、JWTが同じuser_idを持つことを確認する。

署名付きアップロードが失敗する

バケット/ポリシー、プランの制限、MAX_UPLOAD_SIZEを確認する。パスの最初のセグメントはユーザーのUUIDでなければならない。

サンドボックスがローカルで認証されない

Vercelのトークン/チーム/プロジェクトを確認する。デプロイではOIDCを優先し、トークンを不必要にコピーしない。

コマンドがタイムアウトする

プランの制限内でMAX_EXECUTION_SECONDSを増やすか、依存関係が事前インストールされたイメージを使用する。

MCPが401/503を返す

401: OAuthを完了するか、正しいBearerを送信する。503: MCP_SECRETまたはMCP_USER_IDが欠落している。UUIDはMCPサンドボックスの名前空間にすぎず、auth.usersに存在する必要はない。

アーティファクトが表示されない

エージェントがartifact_publishを呼び出す必要がある。tool_calls、バケットのポリシー、MAX_ARTIFACT_SIZEを確認する。