MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-05-12 21:03:05 -07:00
Code Issues Packages Projects Releases Wiki Activity

docs(workspaces): update onboarding to reflect unified architecture and npx usage

Browse Source
This commit is contained in:
mkorwel
2026-03-18 21:57:27 -07:00
parent 8cd24bf667
commit dfbe583050
1 changed files with 33 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files
MAINTAINER_ONBOARDING.md
+33 -65
View File
@@ -1,83 +1,51 @@
# Gemini Workspaces: High-Performance Remote Development 🚀 # Gemini Workspaces: Maintainer Onboarding
Welcome to the Gemini Workspaces platform! This guide will help you set up your Gemini Workspaces allow you to offload 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.
remote development environment, which allows you to offload heavy tasks (reviews, fixes,
preflight) to a dedicated, high-performance GCP worker.
## Prerequisites ## 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.
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. Initialization
2. **GCloud CLI**: Authenticated locally (`gcloud auth login`). Run the setup script using `npx tsx` to ensure all dependencies are available:
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 ```bash
npm run workspace:setup npx tsx .gemini/skills/workspaces/scripts/setup.ts
``` ```
This interactive script will: **What happens during setup:**
- **Phase 1: Configuration**: Auto-detect your repository origins, ask for your GCP project, and guide you through creating a secure GitHub token. 1. **Auth Discovery**: It will detect your `GEMINI_API_KEY` (from `~/.env`) and `GH_TOKEN`.
- **Phase 2: Infrastructure**: Automatically provision the "Magic" corporate network (VPC, Subnets, Firewalls) and the high-performance VM. 2. **Project Choice**: You will be prompted for your GCP Project and Zone.
- **Phase 3: Initialization**: Synchronize your credentials and clone your repository into a persistent remote volume. 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:
## Daily Workflow
### Running a Workspace Job
To perform a deep behavioral review or an agentic fix on your remote worker:
```bash ```bash
# For a review npx tsx .gemini/skills/workspaces/scripts/fleet.ts provision
npm run workspace <PR_NUMBER> review
# For an automated fix
npm run workspace <PR_NUMBER> fix
``` ```
*This creates a VM with a 10GB Boot Disk and a 200GB Data Disk. Initialization takes ~1 minute.*
* **Isolation**: Each job runs in a dedicated **Git Worktree**. ## 4. Finalizing Remote Setup
* **Persistence**: Jobs run inside a `tmux` session. You can disconnect and reconnect without losing progress. Run the setup script one last time to clone the repo and sync credentials:
### Monitoring "Mission Control"
View the real-time state of your worker and all in-flight jobs:
```bash ```bash
npm run workspace:status npx tsx .gemini/skills/workspaces/scripts/setup.ts
``` ```
*When you see "ALL SYSTEMS GO!", your workspace is ready.*
### Stopping Your Worker ## 5. Daily Usage
Once initialized, you can launch tasks directly through `npm`:
To save costs, shut down your worker when finished. The orchestrator will automatically wake it up when you start a new task. * **Review a PR**: `npm run workspace <PR_NUMBER> review`
* **Fix a PR**: `npm run workspace <PR_NUMBER> fix`
* **Check Status**: `npx tsx .gemini/skills/workspaces/scripts/status.ts`
* **Stop Worker**: `npx tsx .gemini/skills/workspaces/scripts/fleet.ts stop` (Recommended when finished to save cost).
```bash ## Troubleshooting
npm run workspace:fleet stop * **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.
---
## 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.