mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-04-22 11:04:42 -07:00
mkorwel
84 lines
2.9 KiB
Markdown
84 lines
2.9 KiB
Markdown
# Gemini Workspaces: High-Performance Remote Development 🚀
|
|
|
|
Welcome to the Gemini Workspaces platform! This guide will help you set up your
|
|
remote development environment, which allows you to offload heavy tasks (reviews, fixes,
|
|
preflight) to a dedicated, high-performance GCP worker.
|
|
|
|
## Prerequisites
|
|
|
|
1. **Google Cloud Access**: You will need a Google Cloud Project with billing enabled. You can use a shared team project or, **ideally, your own personal GCP project** for maximum isolation.
|
|
2. **GCloud CLI**: Authenticated locally (`gcloud auth login`).
|
|
3. **GitHub CLI**: Authenticated locally (`gh auth login`).
|
|
4. **Corporate Identity**: Run `gcert` (or your internal equivalent) recently to ensure SSH certificates are valid.
|
|
|
|
## Architecture: Persistent Cloud Workstations 🏗️
|
|
|
|
The system uses a **Workspace Provider** architecture to abstract the underlying infrastructure:
|
|
|
|
1. **GCE VM (Host)**: A high-performance machine running **Container-Optimized OS (COS)**.
|
|
2. **maintainer-worker (Container)**: A persistent Docker container acting as your remote workstation.
|
|
3. **Resilient Connectivity**: A verified corporate routing path using `nic0` and `.internal.gcpnode.com` for direct, high-speed access.
|
|
|
|
---
|
|
|
|
## Setup Workflow
|
|
|
|
### 1. The Turn-Key Setup
|
|
|
|
The entire environment can be initialized with a single command:
|
|
|
|
```bash
|
|
npm run workspace:setup
|
|
```
|
|
|
|
This interactive script will:
|
|
- **Phase 1: Configuration**: Auto-detect your repository origins, ask for your GCP project, and guide you through creating a secure GitHub token.
|
|
- **Phase 2: Infrastructure**: Automatically provision the "Magic" corporate network (VPC, Subnets, Firewalls) and the high-performance VM.
|
|
- **Phase 3: Initialization**: Synchronize your credentials and clone your repository into a persistent remote volume.
|
|
|
|
---
|
|
|
|
## Daily Workflow
|
|
|
|
### Running a Workspace Job
|
|
|
|
To perform a deep behavioral review or an agentic fix on your remote worker:
|
|
|
|
```bash
|
|
# For a review
|
|
npm run workspace <PR_NUMBER> review
|
|
|
|
# For an automated fix
|
|
npm run workspace <PR_NUMBER> fix
|
|
```
|
|
|
|
* **Isolation**: Each job runs in a dedicated **Git Worktree**.
|
|
* **Persistence**: Jobs run inside a `tmux` session. You can disconnect and reconnect without losing progress.
|
|
|
|
### Monitoring "Mission Control"
|
|
|
|
View the real-time state of your worker and all in-flight jobs:
|
|
|
|
```bash
|
|
npm run workspace:status
|
|
```
|
|
|
|
### Stopping Your Worker
|
|
|
|
To save costs, shut down your worker when finished. The orchestrator will automatically wake it up when you start a new task.
|
|
|
|
```bash
|
|
npm run workspace:fleet stop
|
|
```
|
|
|
|
---
|
|
|
|
## Resilience & Troubleshooting
|
|
|
|
### "SSH Connection Failed"
|
|
1. **Check Identity**: Run `gcert` to refresh your SSH credentials.
|
|
2. **Direct Path**: Ensure you are on the corporate network or VPN if required for `nic0` routing.
|
|
|
|
### "Worker Not Found"
|
|
The `setup` script will automatically offer to provision a worker if it can't find one. Simply follow the prompts.
|