Gemini Cloud Agent

Полноценное веб-приложение для управления удалённым Linux-компьютером с помощью моделей через OpenRouter, OpenCode Zen, Google Gemini или TokenRouter: многошаговый чат, постоянная 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 и ToolLoopAgent из AI SDK 7.

• Многошаговый цикл, ограниченный MAX_AGENT_STEPS.

• Vercel Sandbox 3 с изолированной microVM, постоянной файловой системой и песочницей, именованной по пользователю/рабочей области.

• Shell, файловая система, Git, веб/загрузки, процессы, архивы, артефакты и превью реальных портов.

• Supabase Auth с Google, Postgres/RLS и приватным Storage.

• Прямая загрузка по подписанному URL, без ограничения размера тела Vercel Function.

• Артефакты с размером, 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

Каждая рабочая область получает имя, производное от SHA-256 от user_id + workspace_id. persistent: true позволяет восстановить файловую систему после остановки сессии. Секреты приложения не внедряются в песочницу.

Предварительные требования

• Node.js 22+.

• Проект Supabase.

• Как минимум один совместимый API-ключ: OpenRouter, OpenCode Zen, Google Gemini или TokenRouter.

• Проект Vercel с доступом к Sandbox.

• Локально: токен, team ID и project ID Vercel. При деплое OIDC автоматический.

Компьютер конечного пользователя не участвует в выполнении. После деплоя задачи и сборки выполняются в облаке.

Установка

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

Заполните .env.local, примените миграцию и запустите:

npm run dev

Приложение откроется на http://localhost:3000.

Переменные окружения

Используйте .env.example как полный источник.

DEV_AUTH_BYPASS=true только для разработки, требует service role и игнорируется в продакшене.

Supabase

База данных и Storage

Привяжите проект и примените миграцию:

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

Миграция создаёт workspaces, conversations, messages, agent_runs, tool_calls, files, artifacts, sandboxes, индексы, ограничения, триггеры и приватные бакеты uploads/artifacts.

Таблицы получают явные grants для authenticated, так как текущие проекты могут не открывать новые таблицы автоматически. RLS по-прежнему требует (select auth.uid()) = user_id для SELECT, INSERT, UPDATE и DELETE.

Google Auth

1. В Supabase: Authentication → Providers → Google.

2. Настройте Client ID/Secret от Google.

3. Добавьте callback, указанный Supabase, в Google Cloud Console.

4. Включите http://localhost:3000/auth/callback и URL продакшена в redirect URLs.

Сервер авторизуется через supabase.auth.getClaims(), а не через getSession().

Загрузки

Бакеты приватные; первый сегмент пути объекта всегда auth.uid(). Браузер использует createSignedUploadUrl + uploadToSignedUrl; затем сервер скачивает аутентифицированный объект и материализует его в песочнице. Так загрузки до 50 МБ не попадают в тело Vercel Function.

Модель и цикл агента

По умолчанию настройте OPENROUTER_API_KEY и оставьте OPENROUTER_MODEL=openrouter/free. Этот маршрут выбирает бесплатную модель, поддерживающую требования вызова, включая инструменты. Бесплатные модели имеют переменную доступность и низкие лимиты; чтобы зафиксировать модель, используйте актуальный ID :free из каталога OpenRouter.

AI_PROVIDER=auto выбирает первый присутствующий ключ в этом порядке: OpenRouter, OpenCode Zen, Google и TokenRouter. Чтобы зафиксировать интеграцию, используйте соответствующее имя. OpenCode Zen использует официальный OpenAI-совместимый endpoint и бесплатную модель по умолчанию. Google Gemini принимает модели, настроенные в GEMINI_MODEL. TokenRouter использует свой OpenAI-совместимый endpoint.

Выбор находится в src/lib/ai/provider.ts, и ни один ключ не отправляется в браузер или песочницу.

Системный промпт обязывает агента использовать удалённый компьютер, проверять результаты, обрабатывать stderr, исправлять ошибки, проверять файлы, вызывать artifact_publish, скрывать приватные рассуждения и не делать внешний push без авторизации.

Цикл завершается, когда модель завершает работу, возникает невозможное условие/отмена или достигается MAX_AGENT_STEPS.

MegaBrain Skills

Агент и MCP предоставляют каталог навыков, загружаемый по требованию. Только имя и описание всегда находятся в контексте; skill_read загружает соответствующие инструкции, skill_resources запрашивает скрипты/справочники/ресурсы, а skill_install копирует полный пакет в /workspace/metadata/skills/<имя>, когда его нужно выполнить в microVM.

Версионированный манифест регистрирует путь, размер и SHA-256 каждого из 234 ресурсов. 14 официальных навыков получаются из зафиксированного коммита Anthropic только при использовании, и каждый байт проверяется по манифесту; 5 нативных навыков находятся в самом деплое. Это сохраняет лёгкость деплоя без принятия будущих изменений из вышестоящей ветки. Перегенерируйте манифест после обновления источников с помощью npm run skills:manifest.

Каталог зафиксирован 24/08/2026 в коммите 3b3fad96af16a10759d930941b4520ba0c40edae из anthropics/skills:

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

Четыре официальных документальных навыка доступны только в исходном виде и запрещают копирование/распространение вне сервисов Anthropic; doc-coauthoring не публикует лицензию на распространение. Поэтому эти пять были оригинально перереализованы для MegaBrain, сохраняя покрытие без включения ограниченных материалов. Аудит находится в skills/PROVENANCE.json, и каждый официальный пакет сохраняет свой LICENSE.txt и уведомления третьих сторон.

Vercel Sandbox

Проект использует текущий универсальный образ SDK, постоянную песочницу и /workspace. Создание настраивает vCPU, таймаут и порты. Изоляция — это microVM Firecracker; лимиты плана 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 вызывает bash -lc в microVM, никогда в процессе Next.js. Поддерживает присутствующие/установленные инструменты, такие как Python, pip, Node, npm, Git, curl, zip, Java и Gradle.

Артефакты

artifact_publish(path) разрешает/защищает путь, читает реальный файл, отклоняет пустые/слишком большие, вычисляет SHA-256, определяет MIME, отправляет в приватный бакет, регистрирует в Postgres и возвращает /api/artifacts/:id/download. Загрузка проверяет пользователя и создаёт подписанный URL на 60 секунд.

Панель предлагает Download только для реальных записей artifacts.

APKG

Не существует поддельного генератора. Агент устанавливает реальную библиотеку, например genanki, генерирует пакет, проверяет ZIP/базу/размер/хэш и публикует. Облачный набор тестов охватывает колоду Teste с тремя карточками.

APK Android

Агент может установить JDK/Gradle/Android SDK и выполнить ./gradlew assembleDebug. Рекомендуется предварительно разогретый VCR-образ. Push и запасной вариант GitHub Actions не автоматические: они требуют учетных данных и явного разрешения на ветку/push. MVP предлагает clone/status/diff в публичном доступе без внешней мутации.

Preview

Запустите сервер в песочнице в фоновом/detached режиме и используйте 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 и refresh token. Это позволяет добавить только URL в Gemini Spark.

В 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 для терминала и файлов, и секрет никогда не отправляется в микроВМ или модели.

goal_run использует только настроенные бесплатные провайдеры/модели, когда ZERO_COST_MODE=true. Новые или измененные файлы в /workspace/output публикуются автоматически. Результат содержит подписанный download_url, действительный в течение 24 часов; после истечения срока выполните artifact_publish снова, чтобы создать новую ссылку. workspace_delete завершает и удаляет указанный компьютер, поэтому его следует использовать только тогда, когда это удаление действительно необходимо.

Для сквозной проверки публичной установки — OAuth, каталог MCP, реальный Linux, автономная цель, содержимое файла, подписанная загрузка и очистка — выполните:

npm run test:cloud

Деплой Vercel

1. Отправьте репозиторий в ваш Git-провайдер.

2. Импортируйте в панель управления Vercel.

3. Настройте переменные продакшена.

4. Подтвердите доступ к Sandbox.

5. Настройте callback продакшена в Supabase/Google.

6. Выполните деплой.

Эквивалентная локальная проверка:

npm run typecheck
npm run lint
npm test
npm run build

Маршруты объявляют увеличенную длительность, но фактический лимит зависит от тарифа. Команды выполняются в песочнице; веб-функция остается активной во время цикла/потока.

Безопасность

• Произвольный код — только в Vercel Sandbox.

• Никакие env/секреты приложения не внедряются в песочницу.

• RLS во всех таблицах и Storage для каждого пользователя.

• Service role — только на сервере.

• shell_execute требует сессию Supabase в веб-интерфейсе или OAuth/Bearer в MCP.

• MCP-секрет сравнивается за постоянное время.

• Пути нормализованы/ограничены /workspace; удаление корня заблокировано.

• URL-адреса инструментов блокируют localhost, link-local и частные IP-адреса.

• ZIP/TAR проверяется на traversal перед распаковкой.

• Ограничены таймауты, шаги, vCPU/память, загрузка, артефакты, диск, чтение и вывод.

• Журналы усекают содержимое и редактируют token/secret/password/API key.

• Удаленный push/commit не доступен по умолчанию.

Диск проверяется до/после операций; физический лимит Sandbox является барьером во время быстро растущей команды. В высокорисковом продакшене также ограничьте networkPolicy необходимыми доменами.

Затраты и бесплатные тарифы

• Панель управления показывает активные лимиты.

• Шаги/таймауты предотвращают бесконечные циклы и заброшенные сессии.

• Ограниченные вывод/чтение уменьшают контекст, отправляемый модели.

• Supabase Free в настоящее время включает квоты на базу данных, хранилище и исходящий трафик; максимальный размер загрузки на файл — 50 МБ. Подтвердите актуальную таблицу.

• OpenRouter Free Models имеет низкий общий лимит и не рекомендуется для продакшена; доступность каждой модели варьируется.

• Gemini, при использовании, имеет квоты на проект/модель, видимые в AI Studio.

• Vercel Sandbox взимает плату за активный CPU, а тарифы ограничивают длительность/ресурсы. Подтвердите квоты перед открытием приложения для публики.

Источники: OpenRouter free models, Supabase pricing, Gemini rate limits, Vercel Sandbox.

Тесты

Локальные, без облака:

npm test

Проверяют traversal, частные URL, санитизацию и редактирование.

Реальное облако:

npm run test:cloud

Команда использует публичную продакшн-конечную точку и выполняет OAuth, инициализацию MCP, чтение/установку навыка, создание рабочего пространства, запись и чтение файла, команду Linux, автономный goal_run, автоматическую публикацию, подписанную загрузку и точное сравнение байтов. В конце удаляет только временное рабочее пространство, которое она сама создала.

Старый административный набор тестов, который зависит от TEST_USER_ID и дополнительных локальных учетных данных, по-прежнему доступен как npm run test:cloud:extended.

Известные ограничения

• shell_execute передает stdout и stderr постепенно в журнал событий и в терминал интерфейса. Терминал предназначен для наблюдения и не предоставляет интерактивный PTY для ручного ввода.

• Постоянное файловое хранилище зависит от функции/снимков тарифа Vercel.

• Android SDK не гарантирован в универсальном образе; используйте собственный VCR для предсказуемости.

• Аутентифицированный GitHub/push/Actions требует явного потока авторизации.

• PDF-файлы обрабатываются библиотеками, установленными внутри песочницы, что сохраняет ненадежное содержимое вне веб-процесса.

• Облачные smoke-тесты не запускаются в CI без секретов, чтобы избежать непредвиденных затрат/внешней записи.

Устранение неполадок

Supabase не настроен

Проверьте URL и публичный/anon ключ, примените миграцию и перезапустите сервер.

Вход через Google возвращает на начальный экран

Проверьте провайдера, redirect URL Supabase и callback Google. В продакшене используйте точно https://ВАШ-ДОМЕН/auth/callback.

401/403 или пустые таблицы

Выполните миграцию. Подтвердите grants Data API, политики RLS и что JWT содержит тот же user_id.

Подписанная загрузка не удается

Проверьте buckets/политики, лимит тарифа и MAX_UPLOAD_SIZE. Первый сегмент пути должен быть UUID пользователя.

Песочница не аутентифицируется локально

Проверьте token/team/project Vercel. При деплое предпочитайте OIDC и не копируйте токены без необходимости.

Команда истекает по времени

Увеличьте MAX_EXECUTION_SECONDS в пределах лимита тарифа или используйте образ с предустановленными зависимостями.

MCP возвращает 401/503

401: завершите OAuth или отправьте правильный Bearer. 503: MCP_SECRET или MCP_USER_ID отсутствует. UUID — это только пространство имен для MCP-песочниц и не обязательно должен существовать в auth.users.

Артефакт не появляется

Агенту необходимо вызвать artifact_publish. Проверьте tool_calls, политику bucket и MAX_ARTIFACT_SIZE.