Gemini Cloud Agent

Aplicación web completa para operar un ordenador Linux remoto con modelos vía OpenRouter, OpenCode Zen, Google Gemini o TokenRouter: chat multi-paso, Vercel Sandbox persistente, terminal, archivos, subidas privadas, artefactos verificables, Git, previsualizaciones y servidor MCP Streamable HTTP.

El agente no devuelve solo comandos para que el usuario los ejecute. Cuando la tarea requiere código o archivos, usa herramientas reales en el sandbox, lee stdout/stderr, corrige fallos, valida el resultado y publica el archivo para descarga.

Lo que está implementado

• Next.js 16, React 19, TypeScript, Tailwind CSS 4 y shadcn/ui.

• Interfaz móvil/escritorio con barra lateral, chat, tarjetas de herramientas, registros, subida, STOP, continuar, historial, artefactos y descargas.

• OpenRouter Free Models Router como opción recomendada, OpenCode Zen/Google Gemini/TokenRouter seleccionables, function calling y ToolLoopAgent del AI SDK 7.

• Bucle multi-paso limitado por MAX_AGENT_STEPS.

• Vercel Sandbox 3 con microVM aislada, filesystem persistente y sandbox nombrado por usuario/workspace.

• Shell, filesystem, Git, web/descarga, procesos, archivos, artefactos y previsualización de puertos reales.

• Supabase Auth con Google, Postgres/RLS y Storage privado.

• Subida directa por URL firmada, sin pasar por el límite de body de la Vercel Function.

• Artefactos con tamaño, SHA-256, MIME, registro en la base de datos y URL firmada corta.

• MCP remoto stateless en /mcp, Streamable HTTP actual, OAuth 2.1 + PKCE/DCR y Bearer de compatibilidad.

• MegaBrain Skills con catálogo progresivo de 19 capacidades Claude-compatible, recursos instalables en el sandbox y origen/licencia auditables.

• Cancelación del navegador propagada al modelo/comando e interrupción del sandbox.

• Pruebas locales de seguridad y suite cloud real para los cinco escenarios obligatorios.

Related MCP server: Containarium-Cloud

Arquitectura

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

Cada workspace recibe un nombre derivado por SHA-256 de user_id + workspace_id. persistent: true permite restaurar el filesystem después de que la sesión se detenga. Los secretos de la aplicación no se inyectan en el sandbox.

Requisitos previos

• Node.js 22+.

• Proyecto Supabase.

• Al menos una API key compatible: OpenRouter, OpenCode Zen, Google Gemini o TokenRouter.

• Proyecto Vercel con acceso al Sandbox.

• Localmente: token, team ID y project ID de Vercel. En el deploy, OIDC es automático.

El ordenador del usuario final no participa en la ejecución. Después del deploy, las tareas y builds se ejecutan en la nube.

Instalación

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

Rellene .env.local, aplique la migration y ejecute:

npm run dev

La aplicación se abre en http://localhost:3000.

Variables de entorno

Use .env.example como fuente completa.

DEV_AUTH_BYPASS=true es solo para desarrollo, requiere service role y se ignora en producción.

Supabase

Base de datos y Storage

Vincule el proyecto y aplique la migration:

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

La migration crea workspaces, conversations, messages, agent_runs, tool_calls, files, artifacts, sandboxes, índices, constraints, triggers y los buckets privados uploads/artifacts.

Las tablas reciben grants explícitos para authenticated, porque los proyectos actuales pueden no exponer tablas nuevas automáticamente. RLS sigue exigiendo (select auth.uid()) = user_id en SELECT, INSERT, UPDATE y DELETE.

Google Auth

1. En Supabase: Authentication → Providers → Google.

2. Configure Client ID/Secret de Google.

3. Añada la callback indicada por Supabase en Google Cloud Console.

4. Incluya http://localhost:3000/auth/callback y la URL de producción en las redirect URLs.

El servidor autoriza con supabase.auth.getClaims(), no con getSession().

Subidas

Los buckets son privados; el primer segmento del object path es siempre auth.uid(). El navegador usa createSignedUploadUrl + uploadToSignedUrl; después el servidor descarga el objeto autenticado y lo materializa en el sandbox. Así, subidas de hasta 50 MB no entran en el body de la Vercel Function.

Modelo y bucle del agente

Por defecto, configure OPENROUTER_API_KEY y mantenga OPENROUTER_MODEL=openrouter/free. Esta ruta elige un modelo gratuito que soporte los requisitos de la llamada, incluidas las herramientas. Los modelos gratuitos tienen disponibilidad variable y límites bajos; para fijar un modelo, use un ID :free actual del catálogo de OpenRouter.

AI_PROVIDER=auto selecciona la primera clave presente en este orden: OpenRouter, OpenCode Zen, Google y TokenRouter. Para fijar una integración, use el nombre correspondiente. OpenCode Zen usa el endpoint OpenAI-compatible oficial y un modelo gratuito por defecto. Google Gemini acepta los modelos configurados en GEMINI_MODEL. TokenRouter usa su endpoint OpenAI-compatible.

La selección está en src/lib/ai/provider.ts y ninguna clave se envía al navegador ni al sandbox.

El system prompt obliga al agente a usar el ordenador remoto, inspeccionar resultados, tratar stderr, corregir fallos, validar archivos, llamar a artifact_publish, ocultar razonamiento privado y no hacer push externo sin autorización.

El bucle termina cuando el modelo concluye, ocurre una condición imposible/cancelación o se alcanza MAX_AGENT_STEPS.

MegaBrain Skills

El agente y el MCP exponen un catálogo de skills cargado bajo demanda. Solo nombre y descripción están siempre en el contexto; skill_read carga las instrucciones relevantes, skill_resources consulta scripts/referencias/assets y skill_install copia el paquete completo a /workspace/metadata/skills/<nombre> cuando necesita ejecutarse en la microVM.

Un manifiesto versionado registra ruta, tamaño y SHA-256 de cada uno de los 234 recursos. Las 14 skills oficiales se obtienen del commit fijado de Anthropic solo cuando se usan y cada byte se verifica contra el manifiesto; las 5 skills nativas están en el propio deployment. Esto mantiene el deploy ligero sin aceptar cambios futuros de la rama upstream. Regenera el manifiesto tras actualizar las fuentes con npm run skills:manifest.

El catálogo se fijó el 24/08/2026 en el commit 3b3fad96af16a10759d930941b4520ba0c40edae de anthropics/skills:

• 14 skills oficiales 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 y webapp-testing.

• 5 implementaciones nativas equivalentes: doc-coauthoring, docx, pdf, pptx y xlsx.

Las cuatro skills documentales oficiales son solo source-available y prohíben copia/redistribución fuera de los servicios de Anthropic; doc-coauthoring no publica licencia de redistribución. Por eso esas cinco se reimplementaron originalmente para MegaBrain, manteniendo la cobertura sin incorporar material restringido. La auditoría está en skills/PROVENANCE.json, y cada paquete oficial mantiene su LICENSE.txt y avisos de terceros.

Vercel Sandbox

El proyecto usa la imagen universal actual del SDK, sandbox persistente y /workspace. La creación configura vCPU, timeout y puertos. El aislamiento es una microVM Firecracker; los límites del plan Vercel prevalecen sobre la configuración de la aplicación.

En desarrollo, rellene las tres credenciales de Vercel. En el deploy de Vercel, el SDK usa OIDC automáticamente.

Para Android/toolchains pesadas, use una imagen OCI/VCR propia con JDK, Android command-line tools, SDK y Gradle ya instalados. Sin imagen personalizada, el agente puede instalar dependencias en el sandbox persistente, sujeto a tiempo y disco.

Herramientas

• 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 llama a bash -lc en la microVM, nunca en el proceso Next.js. Soporta herramientas presentes/instaladas como Python, pip, Node, npm, Git, curl, zip, Java y Gradle.

Artefactos

artifact_publish(path) resuelve/protege el path, lee el archivo real, rechaza vacío/tamaño excesivo, calcula SHA-256, detecta MIME, envía al bucket privado, registra en Postgres y devuelve /api/artifacts/:id/download. La descarga valida al usuario y crea una URL firmada por 60 segundos.

El panel solo ofrece Descargar para registros reales de artifacts.

APKG

No existe generador falso. El agente instala una biblioteca real, como genanki, genera el paquete, verifica ZIP/banco/tamaño/hash y publica. La suite cloud cubre un mazo Teste con tres tarjetas.

APK Android

El agente puede instalar JDK/Gradle/Android SDK y ejecutar ./gradlew assembleDebug. Se recomienda una imagen VCR precalentada. Push y fallback GitHub Actions no son automáticos: exigen credenciales y autorización explícita para branch/push. El MVP ofrece clone/status/diff público sin mutación externa.

Preview

Inicie el servidor en el sandbox en background/detached y use expose_port. El puerto debe constar en SANDBOX_EXPOSED_PORTS. El enlace usa sandbox.domain(port) y existe mientras la sesión esté activa.

Cancelación

STOP cancela el stream HTTP. vercel.json habilita supportsCancellation; el AbortSignal llega al modelo y al comando. La aplicación llama a sandbox.stop(), matando procesos de la sesión. El filesystem persistente puede restaurarse después.

MCP remoto

Endpoint de esta instalación: https://gemini-cloud-agent.vercel.app/mcp.

El transporte es Streamable HTTP stateless. POST es soportado; GET/DELETE devuelven 405. El servidor publica descubrimiento OAuth, registro dinámico de cliente, Authorization Code + PKCE y refresh token. Esto permite añadir solo la URL en Gemini Spark.

En Gemini Spark:

1. Abra Settings & help → Connected Apps.

2. En Custom apps for Spark, elija Add a custom app.

3. Pegue https://gemini-cloud-agent.vercel.app/mcp y avance.

4. En la pantalla Autorizar Gemini Cloud Agent, indique el valor de MCP_SECRET.

La conexión no se activa automáticamente solo por existir en la lista. Después de conectarla, use /goal o /meta y describa el resultado completo. Los dos prompts reenvían la solicitud a goal_run, que crea/reutiliza el ordenador, elige skills, ejecuta comandos, verifica la entrega y publica los archivos en una única llamada compuesta. Si el menú de prompts no aparece, pida en lenguaje natural: @Gemini Cloud Agent use goal_run para ....

Gemini/Google controla la confirmación de seguridad mostrada antes de usar una herramienta. El servidor no puede hacer clic en Allow ni desactivar esa protección. El flujo compuesto reduce una tarea entera a una confirmación inicial; las acciones destructivas siguen siendo explícitas.

Los clientes antiguos también pueden usar el Bearer directamente:

Authorization: Bearer SEU_MCP_SECRET

Configuración de compatibilidad:

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

Tools: 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.

Todas operan con workspace_id. Cada ID mapea a una sandbox nombrada dentro del namespace de MCP_USER_ID. El MCP no depende de Supabase para terminal y archivos, y el secreto nunca se envía a la microVM ni al modelo.

goal_run usa solo los proveedores/modelos gratuitos configurados cuando ZERO_COST_MODE=true. Los archivos nuevos o modificados en /workspace/output se publican automáticamente. El resultado trae un download_url firmado, válido por 24 horas; después del vencimiento, ejecute artifact_publish nuevamente para generar otro enlace. workspace_delete cierra y borra el ordenador indicado, por lo que solo debe usarse cuando esa eliminación sea realmente deseada.

Para validar la instalación pública de extremo a extremo — OAuth, catálogo MCP, Linux real, goal autónomo, contenido del archivo, descarga firmada y limpieza — ejecute:

npm run test:cloud

Deploy Vercel

1. Envíe el repositorio a su proveedor Git.

2. Impórtelo en el Dashboard Vercel.

3. Configure las variables de producción.

4. Confirme acceso al Sandbox.

5. Configure la callback de producción en Supabase/Google.

6. Haga deploy.

Validación local equivalente:

npm run typecheck
npm run lint
npm test
npm run build

Las rutas declaran duración extendida, pero el límite efectivo depende del plan. Los comandos corren en la sandbox; la función web permanece viva durante el loop/stream.

Seguridad

• Código arbitrario solo en Vercel Sandbox.

• Ningún env/secret de la aplicación se inyecta en la sandbox.

• RLS en todas las tablas y Storage por usuario.

• Service role solo en el servidor.

• shell_execute exige sesión Supabase en la interfaz web o OAuth/Bearer en el MCP.

• MCP secret comparado en tiempo constante.

• Paths normalizados/restringidos a /workspace; exclusión del root bloqueada.

• URLs de tools bloquean localhost, link-local e IPs privadas.

• ZIP/TAR se valida contra traversal antes de extraer.

• Timeouts, steps, vCPU/memoria, upload, artifact, disco, lectura y output limitados.

• Logs truncan contenido y redactan token/secret/password/API key.

• Push/commit remoto no se expone por defecto.

El disco se verifica antes/después de las operaciones; el límite físico del Sandbox es la barrera durante un comando que crece rápidamente. En producción de alto riesgo, restrinja también la networkPolicy a dominios necesarios.

Costos y free tiers

• El panel muestra los límites activos.

• Steps/timeouts evitan bucles y sesiones abandonadas.

• Output/lectura limitados reducen el contexto enviado al modelo.

• Supabase Free actualmente incluye cuotas de base de datos, storage y egress; el upload máximo por archivo es 50 MB. Confirme la tabla actual.

• OpenRouter Free Models tiene un límite compartido bajo y no es indicado para producción; la disponibilidad de cada modelo varía.

• Gemini, cuando se usa, tiene cuotas por proyecto/modelo visibles en AI Studio.

• Vercel Sandbox cobra CPU activa y los planes limitan duración/recursos. Confirme cuotas antes de abrir la aplicación al público.

Fuentes: OpenRouter free models, Supabase pricing, Gemini rate limits, Vercel Sandbox.

Pruebas

Locales, sin cloud:

npm test

Verifican traversal, URLs privadas, sanitización y redacción.

Cloud real:

npm run test:cloud

El comando usa el endpoint público de producción y realiza OAuth, inicialización MCP, lectura/instalación de skill, creación de workspace, escritura y lectura de archivo, comando Linux, goal_run autónomo, publicación automática, descarga firmada y comparación exacta de los bytes. Al final, elimina solo el workspace temporal que él mismo creó.

La suite administrativa antigua, que depende de TEST_USER_ID y credenciales locales adicionales, sigue disponible como npm run test:cloud:extended.

Limitaciones conocidas

• shell_execute transmite stdout y stderr progresivamente al event log y al terminal de la interfaz. El terminal es de seguimiento y no expone una PTY interactiva para entrada manual.

• Filesystem persistente depende del recurso/snapshots del plan Vercel.

• Android SDK no está garantizado en la imagen universal; use VCR propia para previsibilidad.

• GitHub autenticado/push/Actions requiere flujo explícito de autorización.

• Los PDFs se procesan con bibliotecas instaladas dentro de la sandbox, manteniendo contenido no confiable fuera del proceso web.

• Smoke tests cloud no corren en CI sin secrets para evitar costo/escritura externa inesperada.

Troubleshooting

Supabase no configurado

Revise URL y clave publicable/anon, aplique la migration y reinicie el servidor.

Login Google vuelve a la pantalla inicial

Revise provider, redirect URL de Supabase y callback de Google. En producción use exactamente https://SU-DOMINIO/auth/callback.

401/403 o tablas vacías

Ejecute la migration. Confirme grants del Data API, políticas RLS y que el JWT tenga el mismo user_id.

Upload firmado falla

Revise buckets/policies, límite del plan y MAX_UPLOAD_SIZE. El primer segmento del path debe ser el UUID del usuario.

Sandbox no autentica localmente

Revise token/team/project de Vercel. En el deploy, prefiera OIDC y no copie tokens innecesariamente.

Comando expira

Aumente MAX_EXECUTION_SECONDS dentro del límite del plan o use imagen con dependencias preinstaladas.

MCP devuelve 401/503

401: complete el OAuth o envíe el Bearer correcto. 503: MCP_SECRET o MCP_USER_ID está ausente. El UUID es solo el namespace de las sandboxes MCP y no necesita existir en auth.users.

Artifact no aparece

El agente debe llamar a artifact_publish. Verifique tool_calls, policy del bucket y MAX_ARTIFACT_SIZE.