mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-03-25 21:41:12 -07:00
45 lines
2.4 KiB
Markdown
45 lines
2.4 KiB
Markdown
# Gemini CLI Workspaces: High-Level Architecture Overview
|
|
|
|
## 1. Introduction
|
|
Gemini CLI Workspaces provides a distributed, persistent, and multi-device compute layer for `gemini-cli`. It enables developers to provision, manage, and "teleport" into remote execution environments hosted on GCP.
|
|
|
|
## 2. Core Vision
|
|
- **Persistence:** Sessions survive local device disconnects or terminal restarts.
|
|
- **Portability:** Start a task on one device (e.g., Laptop) and seamlessly re-attach from another (e.g., Surface/Tablet).
|
|
- **Scale:** Offload heavy compute (builds, tests, evals) to remote GCE instances.
|
|
- **Consistency:** Pre-built container images ensure every workspace has the exact same tools and environment.
|
|
|
|
## 3. High-Level Architecture
|
|
The architecture is centered around a **Workspace Hub**, which acts as the fleet manager, and **Remote Workspaces**, which are containerized GCE VMs.
|
|
|
|
```mermaid
|
|
graph TD
|
|
A[Local Device: gemini-cli] -->|API Calls| B(Workspace Hub: Cloud Run)
|
|
A -->|SSH/IAP| C(Remote Workspace: GCE VM)
|
|
B -->|Provision/Monitor| C
|
|
B -->|State Persistence| D(Firestore)
|
|
C -->|Pull Image| E(Artifact Registry)
|
|
```
|
|
|
|
## 4. Multi-Tenancy Models
|
|
The Workspace Hub is a self-service, deployable feature that supports several grains of multi-tenancy:
|
|
|
|
### A. Per-User (Personal Cloud)
|
|
- **Deployment:** Each developer deploys their own Workspace Hub in a personal GCP project.
|
|
- **Isolation:** Absolute. All VMs and secrets belong to the individual.
|
|
|
|
### B. Per-Team (Shared Infrastructure)
|
|
- **Deployment:** A single Hub managed by a team/org.
|
|
- **Tenancy:** Identity-based partitioning. The Hub filters instances based on the authenticated user's Google ID.
|
|
- **Isolation:** Instances are tagged with `owner_id`. Users can only manage their own environments.
|
|
|
|
### C. Per-Repository (Project Environments)
|
|
- **Deployment:** Tied to a specific repo (e.g., for PR reviews or ephemeral test envs).
|
|
- **Tenancy:** Project-context isolation. Users can connect to any workspace associated with the repository context.
|
|
|
|
## 5. Multi-Device Portability
|
|
Since the Workspace Hub stores the state centrally (Firestore), any device with the authenticated `gemini-cli` can:
|
|
1. Query the Hub for the list of active workspaces.
|
|
2. Initiate a connection to a remote VM started by *another* device.
|
|
3. Sync its local `~/.gemini` settings and GitHub PAT to ensure a consistent experience on the remote side.
|