Gemini Cloud Agent

Vollständige Webanwendung zum Betrieb eines entfernten Linux-Computers mit Modellen über OpenRouter, OpenCode Zen, Google Gemini oder TokenRouter: mehrstufiger Chat, persistente Vercel Sandbox, Terminal, Dateien, private Uploads, verifizierbare Artefakte, Git, Vorschauen und MCP-Streamable-HTTP-Server.

Der Agent liefert nicht nur Befehle zurück, die der Benutzer ausführen soll. Wenn die Aufgabe Code oder Dateien erfordert, verwendet er echte Werkzeuge in der Sandbox, liest stdout/stderr, behebt Fehler, validiert das Ergebnis und veröffentlicht die Datei zum Herunterladen.

Was implementiert ist

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

• Mobile/Desktop-Oberfläche mit Seitenleiste, Chat, Tool-Karten, Protokollen, Upload, STOP, Fortsetzen, Verlauf, Artefakten und Downloads.

• OpenRouter Free Models Router als empfohlene Option, OpenCode Zen/Google Gemini/TokenRouter auswählbar, Function Calling und ToolLoopAgent aus dem AI SDK 7.

• Mehrstufige Schleife, begrenzt durch MAX_AGENT_STEPS.

• Vercel Sandbox 3 mit isolierter MicroVM, persistentem Dateisystem und nach Benutzer/Arbeitsbereich benannter Sandbox.

• Shell, Dateisystem, Git, Web/Download, Prozesse, Archive, Artefakte und Vorschau realer Ports.

• Supabase Auth mit Google, Postgres/RLS und privatem Storage.

• Direkter Upload über signierte URL, ohne das Body-Limit der Vercel Function zu überschreiten.

• Artefakte mit Größe, SHA-256, MIME, Datenbankeintrag und kurzer signierter URL.

• Remote-MCP ohne Zustand unter /mcp, aktuelles Streamable HTTP, OAuth 2.1 + PKCE/DCR und Kompatibilitäts-Bearer.

• MegaBrain Skills mit progressivem Katalog von 19 Claude-kompatiblen Fähigkeiten, in der Sandbox installierbaren Ressourcen und überprüfbarer Herkunft/Lizenz.

• Abbruch des Browsers, der an Modell/Befehl weitergegeben wird, und Unterbrechung der Sandbox.

• Lokale Sicherheitstests und echte Cloud-Testsuite für die fünf Pflichtszenarien.

Related MCP server: Containarium-Cloud

Architektur

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

Jeder Arbeitsbereich erhält einen Namen, der per SHA-256 aus user_id + workspace_id abgeleitet wird. persistent: true ermöglicht die Wiederherstellung des Dateisystems, nachdem die Sitzung beendet wurde. Anwendungsgeheimnisse werden nicht in die Sandbox injiziert.

Voraussetzungen

• Node.js 22+.

• Supabase-Projekt.

• Mindestens ein kompatibler API-Schlüssel: OpenRouter, OpenCode Zen, Google Gemini oder TokenRouter.

• Vercel-Projekt mit Zugriff auf die Sandbox.

• Lokal: Token, Team-ID und Projekt-ID von Vercel. Beim Deployment ist OIDC automatisch.

Der Computer des Endbenutzers ist nicht an der Ausführung beteiligt. Nach dem Deployment laufen Aufgaben und Builds in der Cloud.

Installation

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

Füllen Sie .env.local aus, wenden Sie die Migration an und führen Sie Folgendes aus:

npm run dev

Die Anwendung öffnet sich unter http://localhost:3000.

Umgebungsvariablen

Verwenden Sie .env.example als vollständige Quelle.

DEV_AUTH_BYPASS=true ist nur für die Entwicklung gedacht, erfordert die Service-Rolle und wird in der Produktion ignoriert.

Supabase

Datenbank und Storage

Verknüpfen Sie das Projekt und wenden Sie die Migration an:

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

Die Migration erstellt workspaces, conversations, messages, agent_runs, tool_calls, files, artifacts, sandboxes, Indizes, Constraints, Trigger und die privaten Buckets uploads/artifacts.

Die Tabellen erhalten explizite Grants für authenticated, da aktuelle Projekte neue Tabellen möglicherweise nicht automatisch freigeben. RLS verlangt weiterhin (select auth.uid()) = user_id bei SELECT, INSERT, UPDATE und DELETE.

Google Auth

1. In Supabase: Authentication → Providers → Google.

2. Client-ID/Secret von Google konfigurieren.

3. Fügen Sie den von Supabase angegebenen Callback in der Google Cloud Console hinzu.

4. Fügen Sie http://localhost:3000/auth/callback und die Produktions-URL zu den Redirect-URLs hinzu.

Der Server autorisiert mit supabase.auth.getClaims(), nicht mit getSession().

Uploads

Die Buckets sind privat; das erste Segment des Objektpfads ist immer auth.uid(). Der Browser verwendet createSignedUploadUrl + uploadToSignedUrl; danach lädt der Server das authentifizierte Objekt herunter und materialisiert es in der Sandbox. So gelangen Uploads von bis zu 50 MB nicht in den Body der Vercel Function.

Modell und Agent-Schleife

Konfigurieren Sie standardmäßig OPENROUTER_API_KEY und behalten Sie OPENROUTER_MODEL=openrouter/free bei. Diese Route wählt ein kostenloses Modell, das die Anforderungen des Aufrufs erfüllt, einschließlich Tools. Kostenlose Modelle haben variable Verfügbarkeit und niedrige Limits; um ein Modell festzulegen, verwenden Sie eine aktuelle :free-ID aus dem OpenRouter-Katalog.

AI_PROVIDER=auto wählt den ersten vorhandenen Schlüssel in dieser Reihenfolge: OpenRouter, OpenCode Zen, Google und TokenRouter. Um eine Integration festzulegen, verwenden Sie den entsprechenden Namen. OpenCode Zen verwendet den offiziellen OpenAI-kompatiblen Endpunkt und standardmäßig ein kostenloses Modell. Google Gemini akzeptiert die in GEMINI_MODEL konfigurierten Modelle. TokenRouter verwendet seinen OpenAI-kompatiblen Endpunkt.

Die Auswahl befindet sich in src/lib/ai/provider.ts, und kein Schlüssel wird an den Browser oder die Sandbox gesendet.

Das System-Prompt verpflichtet den Agenten, den entfernten Computer zu verwenden, Ergebnisse zu prüfen, stderr zu behandeln, Fehler zu beheben, Dateien zu validieren, artifact_publish aufzurufen, private Überlegungen zu verbergen und ohne Autorisierung keinen externen Push durchzuführen.

Die Schleife endet, wenn das Modell abschließt, eine unmögliche Bedingung/ein Abbruch auftritt oder MAX_AGENT_STEPS erreicht wird.

MegaBrain Skills

Der Agent und der MCP legen einen Katalog von Skills offen, der bei Bedarf geladen wird. Nur Name und Beschreibung sind immer im Kontext; skill_read lädt die relevanten Anweisungen, skill_resources fragt Skripte/Referenzen/Assets ab und skill_install kopiert das vollständige Paket nach /workspace/metadata/skills/<name>, wenn es in der MicroVM ausgeführt werden muss.

Ein versioniertes Manifest registriert Pfad, Größe und SHA-256 jeder der 234 Ressourcen. Die 14 offiziellen Skills werden nur bei Verwendung aus dem festgelegten Commit von Anthropic bezogen, und jedes Byte wird gegen das Manifest verifiziert; die 5 nativen Skills befinden sich im Deployment selbst. Das hält das Deployment leicht, ohne zukünftige Änderungen des Upstream-Zweigs zu akzeptieren. Regenerieren Sie das Manifest nach der Aktualisierung der Quellen mit npm run skills:manifest.

Der Katalog wurde am 24.08.2026 im Commit 3b3fad96af16a10759d930941b4520ba0c40edae von anthropics/skills festgelegt:

• 14 offizielle 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 und webapp-testing.

• 5 äquivalente native Implementierungen: doc-coauthoring, docx, pdf, pptx und xlsx.

Die vier offiziellen dokumentarischen Skills sind nur source-available und verbieten Kopie/Weiterverbreitung außerhalb der Anthropic-Dienste; doc-coauthoring veröffentlicht keine Weiterverbreitungslizenz. Deshalb wurden diese fünf für MegaBrain original neu implementiert, wobei die Abdeckung erhalten bleibt, ohne eingeschränktes Material einzubinden. Die Prüfung befindet sich in skills/PROVENANCE.json, und jedes offizielle Paket behält seine LICENSE.txt und Hinweise auf Dritte.

Vercel Sandbox

Das Projekt verwendet das aktuelle universelle SDK-Image, eine persistente Sandbox und /workspace. Die Erstellung konfiguriert vCPU, Timeout und Ports. Die Isolierung ist eine Firecracker-MicroVM; Limits des Vercel-Plans haben Vorrang vor der Anwendungskonfiguration.

In der Entwicklung füllen Sie die drei Vercel-Anmeldeinformationen aus. Beim Vercel-Deployment verwendet das SDK automatisch OIDC.

Für Android/schwere Toolchains verwenden Sie ein eigenes OCI/VCR-Image mit bereits installiertem JDK, Android-Command-Line-Tools, SDK und Gradle. Ohne benutzerdefiniertes Image kann der Agent Abhängigkeiten in der persistenten Sandbox installieren, abhängig von Zeit und Speicherplatz.

Werkzeuge

• 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 ruft bash -lc in der MicroVM auf, niemals im Next.js-Prozess. Unterstützt vorhandene/installierte Werkzeuge wie Python, pip, Node, npm, Git, curl, zip, Java und Gradle.

Artefakte

artifact_publish(path) löst den Pfad auf/schützt ihn, liest die echte Datei, lehnt leere/zu große Dateien ab, berechnet SHA-256, erkennt MIME, sendet an den privaten Bucket, registriert in Postgres und gibt /api/artifacts/:id/download zurück. Der Download validiert den Benutzer und erstellt eine 60 Sekunden gültige signierte URL.

Das Bedienfeld bietet Download nur für echte Einträge in artifacts an.

APKG

Es gibt keinen Fake-Generator. Der Agent installiert eine echte Bibliothek wie genanki, erzeugt das Paket, prüft ZIP/Datenbank/Größe/Hash und veröffentlicht es. Die Cloud-Suite deckt ein Deck Teste mit drei Karten ab.

APK Android

Der Agent kann JDK/Gradle/Android SDK installieren und ./gradlew assembleDebug ausführen. Ein vorgewärmtes VCR-Image wird empfohlen. Push und Fallback GitHub Actions sind nicht automatisch: Sie erfordern Anmeldedaten und explizite Autorisierung für Branch/Push. Das MVP bietet öffentliches Klonen/Status/Diff ohne externe Mutation.

Vorschau

Starten Sie den Server in der Sandbox im Hintergrund/detached und verwenden Sie expose_port. Der Port muss in SANDBOX_EXPOSED_PORTS enthalten sein. Der Link verwendet sandbox.domain(port) und existiert, solange die Sitzung aktiv ist.

Abbruch

STOP bricht den HTTP-Stream ab. vercel.json aktiviert supportsCancellation; das AbortSignal erreicht das Modell und den Befehl. Die Anwendung ruft sandbox.stop() auf und beendet damit Prozesse der Sitzung. Das persistente Dateisystem kann danach wiederhergestellt werden.

Remote-MCP

Endpunkt dieser Installation: https://gemini-cloud-agent.vercel.app/mcp.

Der Transport ist zustandsloses Streamable HTTP. POST wird unterstützt; GET/DELETE geben 405 zurück. Der Server veröffentlicht OAuth-Discovery, dynamische Client-Registrierung, Authorization Code + PKCE und Refresh Token. Dadurch kann nur die URL in Gemini Spark hinzugefügt werden.

In Gemini Spark:

1. Öffnen Sie Settings & help → Connected Apps.

2. Wählen Sie unter Custom apps for Spark die Option Add a custom app.

3. Fügen Sie https://gemini-cloud-agent.vercel.app/mcp ein und fahren Sie fort.

4. Geben Sie auf dem Bildschirm Autorizar Gemini Cloud Agent den Wert von MCP_SECRET an.

Die Verbindung wird nicht automatisch aktiviert, nur weil sie in der Liste vorhanden ist. Nachdem Sie sie verbunden haben, verwenden Sie /goal oder /meta und beschreiben Sie das vollständige Ergebnis. Die beiden Prompts leiten die Anfrage an goal_run weiter, das den Computer erstellt/wiederverwendet, Skills auswählt, Befehle ausführt, die Lieferung überprüft und die Dateien in einem einzigen zusammengesetzten Aufruf veröffentlicht. Wenn das Prompt-Menü nicht erscheint, fragen Sie in natürlicher Sprache: @Gemini Cloud Agent use goal_run para ....

Gemini/Google steuert die Sicherheitsbestätigung, die vor der Verwendung eines Tools angezeigt wird. Der Server kann weder auf Allow klicken noch diesen Schutz deaktivieren. Der zusammengesetzte Ablauf reduziert eine gesamte Aufgabe auf eine anfängliche Bestätigung; destruktive Aktionen bleiben explizit.

Ältere Clients können das Bearer-Token auch direkt verwenden:

Authorization: Bearer SEU_MCP_SECRET

Kompatibilitätskonfiguration:

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

Alle arbeiten mit workspace_id. Jede ID wird auf eine benannte Sandbox im Namespace von MCP_USER_ID abgebildet. Das MCP ist für Terminal und Dateien nicht von Supabase abhängig, und das Geheimnis wird niemals an die MicroVM oder das Modell gesendet.

goal_run verwendet nur die konfigurierten kostenlosen Anbieter/Modelle, wenn ZERO_COST_MODE=true. Neue oder geänderte Dateien in /workspace/output werden automatisch veröffentlicht. Das Ergebnis enthält eine signierte download_url, die 24 Stunden gültig ist; nach Ablauf führen Sie artifact_publish erneut aus, um einen weiteren Link zu erzeugen. workspace_delete beendet und löscht den angegebenen Computer und sollte daher nur verwendet werden, wenn diese Löschung wirklich gewünscht ist.

Um die öffentliche Installation Ende-zu-Ende zu validieren — OAuth, MCP-Katalog, echtes Linux, autonomes Ziel, Dateiinhalt, signierter Download und Bereinigung — führen Sie aus:

npm run test:cloud

Vercel-Deploy

1. Senden Sie das Repository an Ihren Git-Anbieter.

2. Importieren Sie es im Vercel-Dashboard.

3. Konfigurieren Sie die Produktionsvariablen.

4. Bestätigen Sie den Sandbox-Zugriff.

5. Konfigurieren Sie die Produktions-Callback in Supabase/Google.

6. Führen Sie das Deploy durch.

Entsprechende lokale Validierung:

npm run typecheck
npm run lint
npm test
npm run build

Die Routen deklarieren erweiterte Dauer, aber das effektive Limit hängt vom Plan ab. Befehle laufen in der Sandbox; die Web-Funktion bleibt während der Schleife/des Streams aktiv.

Sicherheit

• Beliebiger Code nur in der Vercel-Sandbox.

• Keine Env/Secrets der Anwendung werden in die Sandbox injiziert.

• RLS auf allen Tabellen und Storage pro Benutzer.

• Service-Rolle nur auf dem Server.

• shell_execute erfordert eine Supabase-Sitzung in der Weboberfläche oder OAuth/Bearer im MCP.

• MCP-Secret wird in konstanter Zeit verglichen.

• Pfade werden normalisiert/auf /workspace beschränkt; Löschung des Root-Verzeichnisses ist blockiert.

• Tool-URLs blockieren localhost, Link-Local und private IPs.

• ZIP/TAR wird vor dem Extrahieren auf Traversal geprüft.

• Timeouts, Schritte, vCPU/Speicher, Upload, Artefakt, Datenträger, Lesen und Ausgabe sind begrenzt.

• Logs kürzen Inhalte und schwärzen Token/Secret/Passwort/API-Key.

• Remote-Push/Commit ist standardmäßig nicht exponiert.

Der Datenträger wird vor/nach den Operationen geprüft; das physische Sandbox-Limit ist die Barriere während eines schnell wachsenden Befehls. In risikoreicher Produktion beschränken Sie auch die networkPolicy auf notwendige Domänen.

Kosten und kostenlose Stufen

• Das Dashboard zeigt die aktiven Limits.

• Schritte/Timeouts verhindern Schleifen und verlassene Sitzungen.

• Begrenzte Ausgabe/Lesung reduzieren den an das Modell gesendeten Kontext.

• Supabase Free umfasst derzeit Datenbank-, Storage- und Egress-Kontingente; maximaler Upload pro Datei beträgt 50 MB. Bestätigen Sie die aktuelle Tabelle.

• OpenRouter Free Models hat ein niedriges gemeinsames Limit und ist nicht für die Produktion geeignet; die Verfügbarkeit jedes Modells variiert.

• Gemini hat, wenn verwendet, Kontingente pro Projekt/Modell, die im AI Studio sichtbar sind.

• Vercel Sandbox berechnet aktive CPU, und Pläne begrenzen Dauer/Ressourcen. Bestätigen Sie Kontingente, bevor Sie die Anwendung öffentlich öffnen.

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

Tests

Lokal, ohne Cloud:

npm test

Sie prüfen Traversal, private URLs, Sanitisierung und Schwärzung.

Echte Cloud:

npm run test:cloud

Der Befehl verwendet den öffentlichen Produktionsendpunkt und führt OAuth, MCP-Initialisierung, Lesen/Installieren von Skills, Erstellen eines Workspace, Schreiben und Lesen von Dateien, Linux-Befehl, autonomes goal_run, automatische Veröffentlichung, signierten Download und exakten Byte-Vergleich durch. Am Ende entfernt er nur den temporären Workspace, den er selbst erstellt hat.

Die alte administrative Suite, die von TEST_USER_ID und zusätzlichen lokalen Anmeldedaten abhängt, bleibt als npm run test:cloud:extended verfügbar.

Bekannte Einschränkungen

• shell_execute überträgt stdout und stderr progressiv an das Ereignisprotokoll und an das Terminal der Oberfläche. Das Terminal dient der Beobachtung und bietet keine interaktive PTY für manuelle Eingabe.

• Persistente Dateisysteme hängen von der Funktion/Snapshots des Vercel-Plans ab.

• Android SDK ist im universellen Image nicht garantiert; verwenden Sie für Vorhersagbarkeit ein eigenes VCR.

• Authentifiziertes GitHub/Push/Actions erfordert einen expliziten Autorisierungsablauf.

• PDFs werden von Bibliotheken verarbeitet, die in der Sandbox installiert sind, wodurch nicht vertrauenswürdige Inhalte außerhalb des Web-Prozesses bleiben.

• Cloud-Smoke-Tests laufen ohne Secrets nicht im CI, um unerwartete Kosten/externe Schreibvorgänge zu vermeiden.

Fehlerbehebung

Supabase nicht konfiguriert

Überprüfen Sie URL und veröffentlichbaren/anon-Schlüssel, wenden Sie die Migration an und starten Sie den Server neu.

Google-Login kehrt zum Startbildschirm zurück

Überprüfen Sie Anbieter, Supabase-Redirect-URL und Google-Callback. Verwenden Sie in Produktion genau https://IHRE-DOMÄNE/auth/callback.

401/403 oder leere Tabellen

Führen Sie die Migration aus. Bestätigen Sie Data-API-Grants, RLS-Richtlinien und dass das JWT dieselbe user_id enthält.

Signierter Upload schlägt fehl

Überprüfen Sie Buckets/Richtlinien, Planlimit und MAX_UPLOAD_SIZE. Das erste Pfadsegment muss die Benutzer-UUID sein.

Sandbox authentifiziert lokal nicht

Überprüfen Sie Vercel-Token/Team/Projekt. Verwenden Sie beim Deploy bevorzugt OIDC und kopieren Sie keine Tokens unnötig.

Befehl läuft ab

Erhöhen Sie MAX_EXECUTION_SECONDS innerhalb des Planlimits oder verwenden Sie ein Image mit vorinstallierten Abhängigkeiten.

MCP gibt 401/503 zurück

401: Schließen Sie OAuth ab oder senden Sie das korrekte Bearer-Token. 503: MCP_SECRET oder MCP_USER_ID fehlt. Die UUID ist nur der Namespace der MCP-Sandboxes und muss nicht in auth.users existieren.

Artefakt erscheint nicht

Der Agent muss artifact_publish aufrufen. Überprüfen Sie tool_calls, Bucket-Richtlinie und MAX_ARTIFACT_SIZE.