Gemini Cloud Agent

OpenRouter, OpenCode Zen, Google Gemini 또는 TokenRouter를 통해 원격 Linux 컴퓨터를 운영하는 완전한 웹 애플리케이션: 다단계 채팅, 지속형 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로 제한되는 다단계 루프.

• 격리된 microVM, 지속형 파일시스템, 사용자/워크스페이스별 명명된 샌드박스를 갖춘 Vercel Sandbox 3.

• 셸, 파일시스템, Git, 웹/다운로드, 프로세스, 아카이브, 아티팩트 및 실제 포트 미리보기.

• Google을 통한 Supabase Auth, Postgres/RLS 및 비공개 Storage.

• Vercel Function의 본문 크기 제한을 우회하는 서명된 URL을 통한 직접 업로드.

• 크기, SHA-256, MIME, 데이터베이스 기록 및 짧은 서명 URL을 갖춘 아티팩트.

• /mcp의 무상태 원격 MCP, 최신 Streamable HTTP, OAuth 2.1 + PKCE/DCR 및 호환 Bearer.

• 19가지 Claude 호환 기능의 점진적 카탈로그, 샌드박스에 설치 가능한 리소스, 감사 가능한 출처/라이선스를 갖춘 MegaBrain Skills.

• 모델/명령에 전파되는 브라우저 취소 및 샌드박스 중단.

• 로컬 보안 테스트 및 필수 5가지 시나리오에 대한 실제 클라우드 테스트 스위트.

Related MCP server: Containarium-Cloud

아키텍처

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 프로젝트.

• OpenRouter, OpenCode Zen, Google Gemini 또는 TokenRouter 중 하나 이상의 API 키.

• Sandbox에 액세스할 수 있는 Vercel 프로젝트.

• 로컬: Vercel 토큰, 팀 ID 및 프로젝트 ID. 배포 시 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는 개발 전용이며 서비스 역할이 필요하고 프로덕션에서는 무시됩니다.

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를 생성합니다.

현재 프로젝트는 새 테이블을 자동으로 노출하지 않을 수 있으므로 테이블에는 authenticated에 대한 명시적 권한이 부여됩니다. 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. 리디렉션 URL에 http://localhost:3000/auth/callback 및 프로덕션 URL을 포함합니다.

서버는 getSession()이 아닌 supabase.auth.getClaims()로 권한을 부여합니다.

업로드

버킷은 비공개이며 객체 경로의 첫 번째 세그먼트는 항상 auth.uid()입니다. 브라우저는 createSignedUploadUrl + uploadToSignedUrl을 사용하고, 서버는 인증된 객체를 다운로드하여 샌드박스에 구체화합니다. 따라서 최대 50MB의 업로드는 Vercel Function 본문에 포함되지 않습니다.

모델 및 에이전트 루프

기본적으로 OPENROUTER_API_KEY를 구성하고 OPENROUTER_MODEL=openrouter/free를 유지하세요. 이 경로는 도구를 포함한 호출 요구 사항을 지원하는 무료 모델을 선택합니다. 무료 모델은 가용성이 다양하고 한도가 낮습니다. 모델을 고정하려면 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/<이름>에 복사합니다.

버전 관리된 매니페스트는 234개 리소스 각각의 경로, 크기 및 SHA-256을 기록합니다. 14개의 공식 스킬은 사용될 때만 Anthropic의 고정 커밋에서 가져오며 각 바이트는 매니페스트에 대해 검증됩니다. 5개의 네이티브 스킬은 배포 자체에 있습니다. 이렇게 하면 업스트림 브랜치의 향후 변경 사항을 수용하지 않고도 배포를 가볍게 유지할 수 있습니다. 소스를 업데이트한 후 npm run skills:manifest로 매니페스트를 다시 생성하세요.

카탈로그는 anthropics/skills의 커밋 3b3fad96af16a10759d930941b4520ba0c40edae에서 2026년 8월 24일에 고정되었습니다:

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

4개의 공식 문서 스킬은 소스 사용 가능만 하며 Anthropic 서비스 외부에서 복사/재배포를 금지합니다. doc-coauthoring은 재배포 라이선스를 게시하지 않습니다. 따라서 이 5개는 제한된 자료를 통합하지 않고도 적용 범위를 유지하면서 MegaBrain용으로 원래 다시 구현되었습니다. 감사는 skills/PROVENANCE.json에 있으며 각 공식 패키지는 자체 LICENSE.txt 및 타사 고지를 유지합니다.

Vercel Sandbox

프로젝트는 현재 SDK의 범용 이미지, 지속형 샌드박스 및 /workspace를 사용합니다. 생성 시 vCPU, 시간 초과 및 포트를 구성합니다. 격리는 Firecracker microVM입니다. Vercel 플랜 한도가 애플리케이션 구성보다 우선합니다.

개발 중에는 세 가지 Vercel 자격 증명을 채우세요. Vercel 배포에서 SDK는 OIDC를 자동으로 사용합니다.

Android/무거운 툴체인의 경우 JDK, Android command-line tools, SDK 및 Gradle이 이미 설치된 자체 OCI/VCR 이미지를 사용하세요. 사용자 지정 이미지가 없으면 에이전트는 지속형 샌드박스에 종속성을 설치할 수 있으며 시간과 디스크의 제약을 받습니다.

도구

• 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는 Next.js 프로세스가 아닌 microVM에서 bash -lc를 호출합니다. Python, pip, Node, npm, Git, curl, zip, Java 및 Gradle과 같은 존재/설치된 도구를 지원합니다.

아티팩트

artifact_publish(path)는 경로를 확인/보호하고, 실제 파일을 읽고, 비어 있거나 너무 큰 파일을 거부하고, SHA-256을 계산하고, MIME을 감지하고, 비공개 버킷에 전송하고, Postgres에 기록하고, /api/artifacts/:id/download를 반환합니다. 다운로드는 사용자를 검증하고 60초 동안 서명된 URL을 생성합니다.

패널은 artifacts의 실제 레코드에 대해서만 다운로드를 제공합니다.

APKG

가짜 생성기는 없습니다. 에이전트는 genanki 같은 실제 라이브러리를 설치하고, 패키지를 생성한 다음 ZIP/DB/크기/해시를 검증하고 게시합니다. 클라우드 스위트는 Teste 덱 하나에 카드 세 개를 포함합니다.

Android APK

에이전트는 JDK/Gradle/Android SDK를 설치하고 ./gradlew assembleDebug를 실행할 수 있습니다. 사전 워밍업된 VCR 이미지가 권장됩니다. Push 및 GitHub Actions 폴백은 자동이 아닙니다. 자격 증명과 브랜치/push에 대한 명시적 권한이 필요합니다. MVP는 외부 변경 없이 공개 clone/status/diff를 제공합니다.

미리보기

샌드박스에서 백그라운드/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을 게시합니다. 이를 통해 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. Gemini Cloud Agent 권한 부여 화면에서 MCP_SECRET 값을 입력합니다.

연결은 목록에 존재한다고 해서 자동으로 활성화되지 않습니다. 연결한 후 /goal 또는 /meta를 사용하고 전체 결과를 설명하세요. 두 프롬프트 모두 요청을 goal_run으로 전달하며, 이는 컴퓨터를 생성/재사용하고, 스킬을 선택하고, 명령을 실행하고, 결과물을 검증하고, 파일을 단일 복합 호출로 게시합니다. 프롬프트 메뉴가 표시되지 않으면 자연어로 요청하세요: @Gemini Cloud Agent use goal_run for ....

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를 사용하지 않으며, 비밀은 마이크로VM이나 모델에 절대 전송되지 않습니다.

goal_run은 ZERO_COST_MODE=true일 때 구성된 무료 제공자/모델만 사용합니다. /workspace/output의 새 파일 또는 변경된 파일은 자동으로 게시됩니다. 결과에는 24시간 동안 유효한 서명된 download_url이 포함됩니다. 만료 후에는 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

라우트는 확장된 기간 선언하지만 실제 제한은 플랜에 따라 다릅니다. 명령은 샌드박스에서 실행됩니다. 웹 함수는 루프스트림 동안 계속 활성 상태입니다.

##안

• 임의 코드는 Vel Sandbox에서만 실행됩니다.

• 애플리케이션의 env/secret은 샌드박스에 주입되지 않습니다.

• 모든 테이블과 Storage에 RLS가 사용자별로 적용됩니다.

• Service은 서버에서만 사용됩니다.

• shell_execute는 웹 인터페이스에서 Supabase 세션 또는 MCP에서 OAuth/Bearer를 요구합니다.

• M secret은 상수 시간 비교로 확인됩니다.

• 경로는 /works로 정규화/제한됩니다. 루트 삭제는 차단됩니다.

• 도 URL은 localhost, link-local 및 사설 IP를 차단합니다.

• ZIP/TAR은 추출 전에 traversal 검증을 거칩니다.

• 초과, 단계, vCPU/메모리, 업로드, 아티팩트, 디스크, 읽기 및 출력이 제한됩니다.

• 로그는 콘텐츠를 잘라내고 token/secretassword/API를 삭제합니다.

• 원격 push/commit은 기본적으로 노출되지 않습니다.

디스크는 작업 전후에 검사됩니다. Sandbox의 물리적 제한은 빠르게 증가하는 명령 중의 장벽입니다. 고위험 프로덕션에서는 networkPolicy도 필요한 도메인으로 제한하세요.

비용 및 무료 티어

• 대시보드에 활성 한도가 표시됩니다.

• 단계/시간 초과는 루프와 방치된 세션을 방지합니다.

• 제한된 출력/읽기는 모델로 전송되는 컨텍스트를 줄입니다.

• Supabase Free는 현재 데이터베이스, 스토리지 및 이그레스 할당량을 포함합니다. 파일당 최대 업로드는 50MB입니다. 현재 표를 확인하세요.

• 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 test:cloud:extended로 계속 사용할 수 있습니다.

##려진 제한 사항

• shell_execute는 stdout과 stderr를 이벤트 로그와 인터페이스 터미널로진적으로 전송합니다. 터미널은 추적용이며 수동 입력을 위한 대화형 PTY를 노출하지 않습니다.

• 영구 파일시스템은 Vercel 플랜의 기능/스냅샷에 다릅니다.

• Android SDK는 범용 이미지에서 보장되지 않습니다. 예측 가능성을 위해체 VCR을 사용하세요.

• GitHub 인증/push/Actions는 명시적 권한 흐름이 필요합니다.

• PDF는 샌드박스 내부에된 라이브러리로 처리되어 신뢰할 수 없는 콘텐츠를 웹 프로세스 외부에 유지합니다.

• 클라우드 스모크 테스트는 예상치 못한 비용/외부 쓰기를 방지하기 위해 secrets 없이 CI에서 실행되지 않습니다.

문제 해결

Supabase가 구성되지 않음

URL과 공개/anon 키를하고, migration을 적용하고, 서버를 다시 시작하세요.

Google 로그인이 시작 화면으로 돌아감

제공자, Supabase 리디렉션 URL 및 Google 콜백을 확인하세요. 프로덕션에서는 정확히 https://YOUR-DOMAIN/auth/callback을 사용하세요.

401/403 또는 빈 테이블

Migration을 실행하세요. Data API grants, RLS 정책을 확인하고 JWT에 동일한 user_id가 있는지 확인하세요.

서명된 업로드 실패

버킷/정책, 플랜 한도 및 MAX_UPLOAD_SIZE를 확인하세요. 경로의 첫 번째 세그먼트는 사용자 UUID여야 합니다.

Sandbox가 로컬에서 인증되지 않음

Vercel token/team/project를 확인하세요. 배포 시 OIDC를 선호하고 불필요하게 토큰을 복사하지 마세요.

명령 시간 초과

플랜 한도 내에서 _EXECUTION_SECONDS를 늘리거나 사전 설치된 종속성이 있는 이미지를 사용하세요.

MCP가 401/503 반환

401: OAuth를 완료하거나 올바른 Bearer를 보내세요. 503: MCP_SECRET 또는 MCP_USER_ID가 없습니다. UUID는 MCP 샌드박스의 네임스페이스일 뿐이며auth.users`에 존재할 필요는 없습니다.

아티팩트가 표시되지 않음

에이전트가 artifact_publish를 호출해야 합니다. tool_calls, 버킷 정책 및 MAX_ARTIFACT_SIZE를 확인하세요.