Gemini Cloud Agent

Complete web application to operate a remote Linux computer with models via OpenRouter, OpenCode Zen, Google Gemini or TokenRouter: multi-step chat, persistent Vercel Sandbox, terminal, files, private uploads, verifiable artifacts, Git, previews and MCP Streamable HTTP server.

The agent does not just return commands for the user to run. When the task requires code or files, it uses real tools in the sandbox, reads stdout/stderr, fixes failures, validates the result and publishes the file for download.

What is implemented

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

• Mobile/desktop interface with sidebar, chat, tool cards, logs, upload, STOP, continue, history, artifacts and downloads.

• OpenRouter Free Models Router as recommended option, selectable OpenCode Zen/Google Gemini/TokenRouter, function calling and ToolLoopAgent from AI SDK 7.

• Multi-step loop limited by MAX_AGENT_STEPS.

• Vercel Sandbox 3 with isolated microVM, persistent filesystem and sandbox named per user/workspace.

• Shell, filesystem, Git, web/download, processes, archives, artifacts and real port preview.

• Supabase Auth with Google, Postgres/RLS and private Storage.

• Direct upload via signed URL, without crossing the Vercel Function body limit.

• Artifacts with size, SHA-256, MIME, database record and short signed URL.

• Remote stateless MCP at /mcp, current Streamable HTTP, OAuth 2.1 + PKCE/DCR and compatibility Bearer.

• MegaBrain Skills with progressive catalog of 19 Claude-compatible capabilities, installable resources in the sandbox and auditable origin/license.

• Browser cancellation propagated to the model/command and sandbox interruption.

• Local security tests and real cloud suite for the five mandatory scenarios.

Related MCP server: Containarium-Cloud

Architecture

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

Each workspace receives a name derived by SHA-256 from user_id + workspace_id. persistent: true allows restoring the filesystem after the session stops. Application secrets are not injected into the sandbox.

Prerequisites

• Node.js 22+.

• Supabase project.

• At least one compatible API key: OpenRouter, OpenCode Zen, Google Gemini or TokenRouter.

• Vercel project with Sandbox access.

• Locally: Vercel token, team ID and project ID. On deploy, OIDC is automatic.

The end user's computer does not take part in execution. After deployment, tasks and builds run in the cloud.

Installation

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

Fill in .env.local, apply the migration and run:

npm run dev

The application opens at http://localhost:3000.

Environment variables

Use .env.example as the complete source.

DEV_AUTH_BYPASS=true is for development only, requires service role and is ignored in production.

Supabase

Database and Storage

Link the project and apply the migration:

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

The migration creates workspaces, conversations, messages, agent_runs, tool_calls, files, artifacts, sandboxes, indexes, constraints, triggers and the private buckets uploads/artifacts.

The tables receive explicit grants for authenticated, since current projects may not expose new tables automatically. RLS still requires (select auth.uid()) = user_id on SELECT, INSERT, UPDATE and DELETE.

Google Auth

1. In Supabase: Authentication → Providers → Google.

2. Configure Google Client ID/Secret.

3. Add the callback indicated by Supabase in the Google Cloud Console.

4. Include http://localhost:3000/auth/callback and the production URL in the redirect URLs.

The server authorizes with supabase.auth.getClaims(), not getSession().

Uploads

The buckets are private; the first segment of the object path is always auth.uid(). The browser uses createSignedUploadUrl + uploadToSignedUrl; then the server downloads the authenticated object and materializes it in the sandbox. This way, uploads up to 50 MB do not enter the Vercel Function body.

Model and agent loop

By default, set OPENROUTER_API_KEY and keep OPENROUTER_MODEL=openrouter/free. This route picks a free model that supports the call requirements, including tools. Free models have variable availability and low limits; to pin a model, use a current :free ID from the OpenRouter catalog.

AI_PROVIDER=auto selects the first key present in this order: OpenRouter, OpenCode Zen, Google and TokenRouter. To pin an integration, use the corresponding name. OpenCode Zen uses the official OpenAI-compatible endpoint and a free model by default. Google Gemini accepts the models configured in GEMINI_MODEL. TokenRouter uses its OpenAI-compatible endpoint.

The selection lives in src/lib/ai/provider.ts and no key is sent to the browser or the sandbox.

The system prompt forces the agent to use the remote computer, inspect results, handle stderr, fix failures, validate files, call artifact_publish, hide private reasoning and not push externally without authorization.

The loop ends when the model concludes, an impossible condition/cancellation occurs, or MAX_AGENT_STEPS is reached.

MegaBrain Skills

The agent and the MCP expose a skills catalog loaded on demand. Only name and description are always in context; skill_read loads the relevant instructions, skill_resources queries scripts/references/assets and skill_install copies the full package to /workspace/metadata/skills/<name> when it needs to run in the microVM.

A versioned manifest records path, size and SHA-256 for each of the 234 resources. The 14 official skills are fetched from the pinned Anthropic commit only when used and every byte is verified against the manifest; the 5 native skills live in the deployment itself. This keeps the deployment light without accepting future changes from the upstream branch. Regenerate the manifest after updating sources with npm run skills:manifest.

The catalog was pinned on 24/08/2026 at commit 3b3fad96af16a10759d930941b4520ba0c40edae from anthropics/skills:

• 14 official Apache 2.0 skills: 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 and webapp-testing.

• 5 equivalent native implementations: doc-coauthoring, docx, pdf, pptx and xlsx.

The four official documentary skills are source-available only and prohibit copying/redistribution outside Anthropic services; doc-coauthoring does not publish a redistribution license. Therefore these five were originally reimplemented for MegaBrain, keeping coverage without incorporating restricted material. The audit is in skills/PROVENANCE.json, and each official package keeps its LICENSE.txt and third-party notices.

Vercel Sandbox

The project uses the current universal SDK image, persistent sandbox and /workspace. Creation configures vCPU, timeout and ports. Isolation is a Firecracker microVM; Vercel plan limits prevail over application configuration.

In development, fill in the three Vercel credentials. On Vercel deploy, the SDK uses OIDC automatically.

For Android/heavy toolchains, use your own OCI/VCR image with JDK, Android command-line tools, SDK and Gradle already installed. Without a custom image, the agent can install dependencies in the persistent sandbox, subject to time and disk.

Tools

• 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 calls bash -lc in the microVM, never in the Next.js process. It supports present/installed tools such as Python, pip, Node, npm, Git, curl, zip, Java and Gradle.

Artifacts

artifact_publish(path) resolves/protects the path, reads the real file, rejects empty/oversized, computes SHA-256, detects MIME, uploads to the private bucket, records in Postgres and returns /api/artifacts/:id/download. The download validates the user and creates a signed URL for 60 seconds.

The panel only offers Download for real artifacts records.

APKG

There is no fake generator. The agent installs a real library, such as genanki, generates the package, verifies ZIP/database/size/hash, and publishes it. The cloud suite covers a Teste deck with three cards.

Android APK

The agent can install JDK/Gradle/Android SDK and run ./gradlew assembleDebug. A pre-warmed VCR image is recommended. Push and GitHub Actions fallback are not automatic: they require credentials and explicit authorization for branch/push. The MVP offers public clone/status/diff without external mutation.

Preview

Start the server in the sandbox in background/detached mode and use expose_port. The port must be listed in SANDBOX_EXPOSED_PORTS. The link uses sandbox.domain(port) and exists while the session is active.

Cancellation

STOP cancels the HTTP stream. vercel.json enables supportsCancellation; the AbortSignal reaches the model and the command. The application calls sandbox.stop(), killing the session's processes. The persistent filesystem can be restored later.

Remote MCP

Endpoint of this installation: https://gemini-cloud-agent.vercel.app/mcp.

The transport is stateless Streamable HTTP. POST is supported; GET/DELETE return 405. The server publishes OAuth discovery, dynamic client registration, Authorization Code + PKCE, and refresh token. This allows adding just the URL in Gemini Spark.

In Gemini Spark:

1. Open Settings & help → Connected Apps.

2. Under Custom apps for Spark, choose Add a custom app.

3. Paste https://gemini-cloud-agent.vercel.app/mcp and proceed.

4. On the Authorize Gemini Cloud Agent screen, enter the MCP_SECRET value.

The connection is not activated automatically just by existing in the list. After connecting it, use /goal or /meta and describe the complete result. Both prompts forward the request to goal_run, which creates/reuses the computer, chooses skills, runs commands, verifies the delivery, and publishes the files in a single composite call. If the prompts menu does not appear, ask in natural language: @Gemini Cloud Agent use goal_run para ....

Gemini/Google controls the security confirmation shown before using a tool. The server cannot click Allow or disable this protection. The composite flow reduces an entire task to a single initial confirmation; destructive actions remain explicit.

Legacy clients can also use the Bearer directly:

Authorization: Bearer SEU_MCP_SECRET

Compatibility configuration:

{
  "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.

All operate with workspace_id. Each ID maps to a named sandbox within the MCP_USER_ID namespace. The MCP does not depend on Supabase for terminal and files, and the secret is never sent to the microVM or the model.

goal_run uses only the configured free providers/models when ZERO_COST_MODE=true. New or changed files in /workspace/output are published automatically. The result includes a signed download_url, valid for 24 hours; after it expires, run artifact_publish again to generate another link. workspace_delete shuts down and deletes the indicated computer, so it should only be used when that deletion is truly desired.

To validate the public installation end to end — OAuth, MCP catalog, real Linux, autonomous goal, file content, signed download, and cleanup — run:

npm run test:cloud

Vercel Deploy

1. Push the repository to your Git provider.

2. Import it in the Vercel Dashboard.

3. Configure the production variables.

4. Confirm Sandbox access.

5. Configure the production callback in Supabase/Google.

6. Deploy.

Equivalent local validation:

npm run typecheck
npm run lint
npm test
npm run build

The routes declare extended duration, but the effective limit depends on the plan. Commands run in the sandbox; the web function stays alive during the loop/stream.

Security

• Arbitrary code only in the Vercel Sandbox.

• No application env/secret is injected into the sandbox.

• RLS on all tables and per-user Storage.

• Service role only on the server.

• shell_execute requires a Supabase session in the web UI or OAuth/Bearer in the MCP.

• MCP secret compared in constant time.

• Paths normalized/restricted to /workspace; root deletion blocked.

• Tool URLs block localhost, link-local, and private IPs.

• ZIP/TAR is validated against traversal before extracting.

• Timeouts, steps, vCPU/memory, upload, artifact, disk, read, and output are limited.

• Logs truncate content and redact token/secret/password/API key.

• Remote push/commit is not exposed by default.

The disk is checked before/after operations; the Sandbox's physical limit is the barrier during a command that grows quickly. In high-risk production, also restrict networkPolicy to necessary domains.

Costs and free tiers

• The dashboard shows the active limits.

• Steps/timeouts prevent loops and abandoned sessions.

• Limited output/read reduce the context sent to the model.

• Supabase Free currently includes database, storage, and egress quotas; maximum upload per file is 50 MB. Confirm the current table.

• OpenRouter Free Models has a low shared limit and is not recommended for production; availability of each model varies.

• Gemini, when used, has per-project/model quotas visible in AI Studio.

• Vercel Sandbox charges for active CPU and plans limit duration/resources. Confirm quotas before opening the application to the public.

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

Tests

Local, without cloud:

npm test

They verify traversal, private URLs, sanitization, and redaction.

Real cloud:

npm run test:cloud

The command uses the public production endpoint and performs OAuth, MCP initialization, skill read/install, workspace creation, file write and read, Linux command, autonomous goal_run, automatic publishing, signed download, and exact byte comparison. At the end, it removes only the temporary workspace it created itself.

The legacy administrative suite, which depends on TEST_USER_ID and additional local credentials, remains available as npm run test:cloud:extended.

Known limitations

• shell_execute streams stdout and stderr progressively to the event log and to the UI terminal. The terminal is for monitoring and does not expose an interactive PTY for manual input.

• Persistent filesystem depends on the Vercel plan's feature/snapshots.

• Android SDK is not guaranteed in the universal image; use your own VCR for predictability.

• Authenticated GitHub/push/Actions requires an explicit authorization flow.

• PDFs are processed by libraries installed inside the sandbox, keeping untrusted content out of the web process.

• Cloud smoke tests do not run in CI without secrets to avoid unexpected cost/external writes.

Troubleshooting

Supabase not configured

Check the URL and publishable/anon key, apply the migration, and restart the server.

Google login returns to the home screen

Check the provider, Supabase redirect URL, and Google callback. In production, use exactly https://SEU-DOMINIO/auth/callback.

401/403 or empty tables

Run the migration. Confirm Data API grants, RLS policies, and that the JWT has the same user_id.

Signed upload fails

Check buckets/policies, the plan limit, and MAX_UPLOAD_SIZE. The first path segment must be the user's UUID.

Sandbox does not authenticate locally

Check the Vercel token/team/project. In deployment, prefer OIDC and do not copy tokens unnecessarily.

Command expires

Increase MAX_EXECUTION_SECONDS within the plan limit or use an image with pre-installed dependencies.

MCP returns 401/503

401: complete the OAuth or send the correct Bearer. 503: MCP_SECRET or MCP_USER_ID is missing. The UUID is only the namespace for MCP sandboxes and does not need to exist in auth.users.

Artifact does not appear

The agent needs to call artifact_publish. Check tool_calls, the bucket policy, and MAX_ARTIFACT_SIZE.