Skip to main content
Glama
Gemini-Cloud-Agent-MCP

Gemini-Cloud-Agent-MCP

by JOAO2666

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: 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 密钥: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 作为完整来源。

变量

用途

AI_PROVIDER

auto、openrouter、opencode、google 或 tokenrouter。

OPENROUTER_API_KEY

仅限服务器的 OpenRouter 密钥。

OPENROUTER_MODEL

默认为 openrouter/free,它会选择一个兼容的免费模型。

OPENCODE_ZEN_API_KEY

仅限服务器的 OpenCode Zen 密钥。

OPENCODE_ZEN_MODEL

默认为 nemotron-3-ultra-free。

TOKENROUTER_API_KEY

仅限服务器的 TokenRouter 密钥。

TOKENROUTER_MODEL

默认为 kimi-k2p6。

GEMINI_API_KEY

可选的 Gemini 密钥。

GEMINI_MODEL

当 provider 为 google 时使用的模型 ID。

NEXT_PUBLIC_SUPABASE_URL

Supabase URL。

NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY

当前的 publishable 密钥。

NEXT_PUBLIC_SUPABASE_ANON_KEY

旧版 anon 密钥的替代方案。

SUPABASE_SERVICE_ROLE_KEY

仅限服务器,用于 Web 界面和旧版 smoke tests。

VERCEL_TOKEN、VERCEL_TEAM_ID、VERCEL_PROJECT_ID

本地访问 Sandbox。

MCP_SECRET

OAuth 和兼容性 Bearer 密码,至少 24 个字符。

MCP_USER_ID

用作 MCP 沙箱隔离命名空间的稳定 UUID。

MAX_AGENT_STEPS

最大生成/工具轮数。

MAX_EXECUTION_SECONDS

每个命令的最大超时时间。

MAX_SANDBOX_MINUTES

会话的最长时间。

MAX_UPLOAD_SIZE

每次上传的最大字节数。

MAX_ARTIFACT_SIZE

每个工件的最大字节数。

MAX_WORKSPACE_DISK_BYTES

在操作之前/之后检查的限制。

MAX_TOOL_OUTPUT_CHARS

发送给模型/日志的 stdout/stderr 截断长度。

SANDBOX_VCPUS

vCPU;内存与 vCPU 绑定。

SANDBOX_EXPOSED_PORTS

最多 15 个预览端口。

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。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to create, manage, and execute code in isolated Firecracker microVM sandboxes via the MCP protocol, with support for sandbox lifecycle and file operations.
      4
      Apache 2.0
    • A
      license
      B
      quality
      B
      maintenance
      Provides an MCP control plane for a dedicated Linux VM, enabling shell-equivalent command execution, bounded filesystem and Git workspace operations, persistent process and coding-agent orchestration, artifact presentation, and optional upstream MCP bridge re-exports.
      27
      1
      ISC
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to operate disposable Linux computers via MCP, providing tools for shell, file read/write, directory listing, and port exposure. It also supports browser automation and integration with any MCP-compatible client.
      Apache 2.0