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 限制的多步骤循环。

• Vercel Sandbox 3，具有隔离的 microVM、持久化文件系统，以及按用户/工作区命名的沙箱。

• Shell、文件系统、Git、Web/下载、进程、归档、工件和真实端口预览。

• 支持 Google 登录的 Supabase Auth、Postgres/RLS 和私有 Storage。

• 通过签名 URL 直接上传，不经过 Vercel Function 的 body 限制。

• 工件包含大小、SHA-256、MIME、数据库记录和短签名 URL。

• 位于 /mcp 的无状态远程 MCP、当前 Streamable HTTP、OAuth 2.1 + PKCE/DCR 和兼容性 Bearer。

• MegaBrain Skills，具有 19 种 Claude 兼容能力的渐进式目录、可在沙箱中安装的资源以及可审计的来源/许可证。

• 浏览器取消操作传播到模型/命令，并中断沙箱。

• 本地安全测试和针对五个必需场景的真实云测试套件。

Related MCP server: Containarium-Cloud

架构

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 密钥：OpenRouter、OpenCode Zen、Google Gemini 或 TokenRouter。

• 具有 Sandbox 访问权限的 Vercel 项目。

• 本地：Vercel token、team ID 和 project ID。部署时，OIDC 是自动的。

最终用户的计算机不参与执行。部署后，任务和构建在云端运行。

安装

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

填写 .env.local，应用 migration，然后运行：

npm run dev

应用程序在 http://localhost:3000 打开。

环境变量

使用 .env.example 作为完整来源。

DEV_AUTH_BYPASS=true 仅用于开发，需要 service role，在生产环境中会被忽略。

Supabase

数据库和 Storage

关联项目并应用 migration：

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

该 migration 会创建 workspaces、conversations、messages、agent_runs、tool_calls、files、artifacts、sandboxes、索引、约束、触发器以及私有 bucket uploads/artifacts。

这些表会获得对 authenticated 的显式 grants，因为当前项目可能不会自动暴露新表。RLS 仍然要求在 SELECT、INSERT、UPDATE 和 DELETE 中满足 (select auth.uid()) = user_id。

Google 登录

1. 在 Supabase 中：Authentication → Providers → Google。

2. 配置 Google 的 Client ID/Secret。

3. 在 Google Cloud Console 中添加 Supabase 指示的回调地址。

4. 在 redirect URLs 中包含 http://localhost:3000/auth/callback 和生产 URL。

服务器使用 supabase.auth.getClaims() 进行授权，而不是 getSession()。

上传

Bucket 是私有的；object path 的第一个段始终是 auth.uid()。浏览器使用 createSignedUploadUrl + uploadToSignedUrl；之后服务器下载已认证的对象并将其物化到沙箱中。这样，最大 50 MB 的上传不会进入 Vercel Function 的 body。

模型和代理循环

默认情况下，配置 OPENROUTER_API_KEY 并保持 OPENROUTER_MODEL=openrouter/free。该路由会选择一个满足调用要求（包括 tools）的免费模型。免费模型可用性不稳定且限制较低；要固定模型，请使用 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/<名称>。

一个带版本号的 manifest 记录了 234 个资源中每一个的路径、大小和 SHA-256。14 个官方技能仅在使用时从 Anthropic 的固定 commit 获取，每个字节都会对照 manifest 进行验证；5 个原生技能位于部署本身中。这样既保持了部署的轻量，又不会接受上游分支的未来更改。更新来源后，使用 npm run skills:manifest 重新生成 manifest。

目录已于 2026 年 8 月 24 日固定在 anthropics/skills 的 commit 3b3fad96af16a10759d930941b4520ba0c40edae 上：

• 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。

四个官方的文档类技能仅限 source-available，并禁止在 Anthropic 服务之外复制/再分发；doc-coauthoring 不发布再分发许可证。因此，这五个技能为 MegaBrain 进行了原创性重新实现，在保持覆盖范围的同时不包含受限材料。审计信息位于 skills/PROVENANCE.json，每个官方包都保留其 LICENSE.txt 和第三方声明。

Vercel Sandbox

该项目使用当前 SDK 的通用镜像、持久化沙箱和 /workspace。创建时配置 vCPU、超时和端口。隔离是 Firecracker microVM；Vercel 计划的限制优先于应用程序配置。

在开发环境中，填写三个 Vercel 凭据。在 Vercel 部署中，SDK 自动使用 OIDC。

对于 Android/重型工具链，请使用自定义 OCI/VCR 镜像，其中已安装 JDK、Android command-line tools、SDK 和 Gradle。没有自定义镜像时，代理可以在持久化沙箱中安装依赖项，但受时间和磁盘限制。

工具

• 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 在 microVM 中调用 bash -lc，绝不会在 Next.js 进程中调用。支持已存在/已安装的工具，如 Python、pip、Node、npm、Git、curl、zip、Java 和 Gradle。

工件

artifact_publish(path) 解析/保护路径，读取真实文件，拒绝空/超大文件，计算 SHA-256，检测 MIME，发送到私有 bucket，在 Postgres 中记录，并返回 /api/artifacts/:id/download。下载会验证用户并创建 60 秒的签名 URL。

面板仅对 artifacts 中的真实记录提供下载选项。

APKG

不存在虚假生成器。代理会安装一个真实的库，比如 genanki，生成包，检查 ZIP/数据库/大小/哈希并发布。云端套件覆盖一个名为 Teste 的牌组，包含三张卡片。

Android APK

代理可以安装 JDK/Gradle/Android SDK 并运行 ./gradlew assembleDebug。建议使用预热的 VCR 镜像。推送和 GitHub Actions 回退不是自动的：它们需要凭据以及对分支/推送的明确授权。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 并描述完整结果。这两个提示会将请求转发给 goal_run，它在一次复合调用中创建/复用计算机、选择技能、执行命令、验证交付并发布文件。如果提示菜单没有出现，请用自然语言请求：@Gemini Cloud Agent use goal_run para ...。

Gemini/Google 控制使用工具前显示的安全确认。服务器无法点击 Allow，也无法禁用此保护。复合流程将整个任务缩减为一次初始确认；破坏性操作仍然明确。

旧客户端也可以直接使用 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，并且密钥永远不会发送到 microVM 或模型。

当 ZERO_COST_MODE=true 时，goal_run 只使用配置的免费提供商/模型。/workspace/output 中新增或更改的文件会自动发布。结果包含一个签名的 download_url，有效期为 24 小时；过期后，再次执行 artifact_publish 以生成另一个链接。workspace_delete 会终止并删除指定的计算机，因此只有在确实需要删除时才应使用。

要端到端验证公共安装——OAuth、MCP 目录、真实 Linux、自主 goal、文件内容、签名下载和清理——请执行：

npm run test:cloud

Vercel 部署

1. 将仓库推送到你的 Git 提供商。

2. 在 Vercel Dashboard 中导入。

3. 配置生产环境变量。

4. 确认 Sandbox 访问权限。

5. 在 Supabase/Google 中配置生产回调。

6. 进行部署。

等效的本地验证：

npm run typecheck
npm run lint
npm test
npm run build

路由声明了扩展时长，但实际限制取决于套餐。命令在沙箱中运行；Web 函数在循环/流期间保持存活。

安全

• 任意代码仅在 Vercel Sandbox 中执行。

• 应用程序的任何 env/secret 都不会注入沙箱。

• 所有表均启用 RLS，Storage 按用户隔离。

• Service role 仅在服务器上使用。

• shell_execute 在 Web 界面中需要 Supabase 会话，或在 MCP 中需要 OAuth/Bearer。

• MCP secret 以恒定时间比较。

• 路径已规范化并限制在 /workspace；禁止删除根目录。

• 工具 URL 会阻止 localhost、link-local 和私有 IP。

• 在解压前会对 ZIP/TAR 进行路径穿越验证。

• 超时、步骤、vCPU/内存、上传、artifact、磁盘、读取和输出均有限制。

• 日志会截断内容，并对 token/secret/password/API key 进行脱敏。

• 默认不公开远程 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 初始化、技能读取/安装、workspace 创建、文件写入和读取、Linux 命令、自主 goal_run、自动发布、签名下载以及字节级精确比较。最后，它只删除自己创建的临时 workspace。

旧的管理套件依赖于 TEST_USER_ID 和额外的本地凭据，仍可作为 npm run test:cloud:extended 使用。

已知限制

• shell_execute 会逐步将 stdout 和 stderr 传输到事件日志和界面终端。该终端仅用于跟随，不提供交互式 PTY 供手动输入。

• 持久化文件系统依赖于 Vercel 套餐的功能/快照。

• 通用镜像不保证提供 Android SDK；为了可预测性，请使用自己的 VCR。

• 经过身份验证的 GitHub/push/Actions 需要明确的授权流程。

• PDF 由沙箱内安装的库处理，从而将不可信内容隔离在 Web 进程之外。

• 云端冒烟测试在没有 secrets 时不会在 CI 中运行，以避免意外成本/外部写入。

故障排查

Supabase 未配置

检查 URL 和可发布/匿名密钥，应用迁移，然后重启服务器。

Google 登录返回初始屏幕

检查 provider、Supabase 重定向 URL 和 Google 回调。在生产环境中，请精确使用 https://SEU-DOMINIO/auth/callback。

401/403 或空表

运行迁移。确认 Data API 授权、RLS 策略，以及 JWT 具有相同的 user_id。

签名上传失败

检查 buckets/policies、套餐限制和 MAX_UPLOAD_SIZE。路径的第一个段应为用户的 UUID。

Sandbox 无法在本地通过认证

检查 Vercel 的 token/team/project。在部署时，优先使用 OIDC，不要不必要地复制令牌。

命令超时

在套餐限制内增加 MAX_EXECUTION_SECONDS，或使用预装依赖项的镜像。

MCP 返回 401/503

401：完成 OAuth 或发送正确的 Bearer。503：缺少 MCP_SECRET 或 MCP_USER_ID。该 UUID 只是 MCP 沙箱的命名空间，不需要存在于 auth.users 中。

Artifact 不出现

代理需要调用 artifact_publish。检查 tool_calls、bucket 策略和 MAX_ARTIFACT_SIZE。