mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-07-05 15:46:47 -07:00
mkorwel
76 lines
2.3 KiB
Markdown
76 lines
2.3 KiB
Markdown
# Gemini Workspaces: Maintainer Onboarding
|
|
|
|
Gemini Workspaces allow you to delegate heavy tasks (PR reviews, agentic fixes,
|
|
full builds) to a high-performance GCP worker. It uses a **Unified Data Disk**
|
|
architecture to ensure your work persists even if the VM is deleted or
|
|
recreated.
|
|
|
|
## 1. Local Prerequisites
|
|
|
|
Before starting, ensure you have:
|
|
|
|
- **GCloud CLI**: Authenticated (`gcloud auth login`).
|
|
- **GitHub CLI**: Authenticated (`gh auth login`).
|
|
- **Project Access**: A GCP Project ID where you have `Editor` or
|
|
`Compute Admin` roles.
|
|
|
|
## 2. Initialization
|
|
|
|
Run the setup script using the unified workspaces entry point:
|
|
|
|
```bash
|
|
npx tsx scripts/workspaces.ts setup
|
|
```
|
|
|
|
**What happens during setup:**
|
|
|
|
1. **Auth Discovery**: It will detect your `GEMINI_API_KEY` (from `~/.env`) and
|
|
`GH_TOKEN`.
|
|
2. **Project Choice**: You will be prompted for your GCP Project and Zone.
|
|
3. **Infrastructure Check**: It verifies if your worker
|
|
(`gcli-workspace-<user>`) exists.
|
|
4. **SSH Magic**: It generates a local `.gemini/workspaces/ssh_config` for
|
|
seamless access.
|
|
|
|
## 3. Provisioning
|
|
|
|
If the setup informs you that the worker was not found, provision it:
|
|
|
|
```bash
|
|
npx tsx scripts/workspaces.ts fleet provision
|
|
```
|
|
|
|
_This creates a VM with a 10GB Boot Disk and a 200GB Data Disk. Initialization
|
|
takes ~1 minute._
|
|
|
|
## 4. Finalizing Remote Setup
|
|
|
|
Run the setup script one last time to clone the repo and sync credentials:
|
|
|
|
```bash
|
|
npx tsx scripts/workspaces.ts setup
|
|
```
|
|
|
|
_When you see "ALL SYSTEMS GO!", your workspace is ready._
|
|
|
|
## 5. Daily Usage
|
|
|
|
Once initialized, you can launch tasks directly through `npm` or the entry
|
|
point:
|
|
|
|
- **Review a PR**: `npm run workspace <PR_NUMBER> review`
|
|
- **Launch a Shell**: `npm run workspace:shell <ID>`
|
|
- **Check Status**: `npm run workspace:status`
|
|
- **Cleanup All**: `npm run workspace:clean-all`
|
|
- **Kill Task**: `npm run workspace:kill <PR> <action>`
|
|
- **Stop Worker**: `npx tsx scripts/workspaces.ts fleet stop` (Recommended when
|
|
finished to save cost).
|
|
|
|
## Troubleshooting
|
|
|
|
- **Permission Denied (Docker)**: The orchestrator handles this by using
|
|
`sudo docker` internally.
|
|
- **Dubious Ownership**: The system automatically adds `/mnt/disks/data/main` to
|
|
Git's safe directory list.
|
|
- **Missing tsx**: Always prefer `npx tsx` when running scripts manually.
|