gemini-cli/docs/architecture/workspaces/hub-service.md

Detailed Design: Workspace Hub Service

1. Introduction

The Workspace Hub is a serverless application (deployed on Cloud Run) that manages the fleet of remote execution environments. It is designed as a deployable, self-service feature for developers and teams.

2. API Endpoints

Method	Endpoint	Description
GET	/workspaces	List all workspaces for the authenticated user.
POST	/workspaces	Request creation of a new GCE-backed workspace.
DELETE	/workspaces/:id	Destroy the VM and clean up Firestore state.
POST	/workspaces/:id/stop	Suspend the GCE instance (cost-saving).
POST	/workspaces/:id/start	Resume a suspended instance.
GET	/workspaces/:id/status	Get real-time status from GCE and Firestore.

3. Firestore State Store

The Hub maintains a centralized state to enable multi-device synchronization.

• Collection: workspaces
  • id: Unique identifier (UUID).
  • owner_id: Google User ID (from OAuth).
  • instance_name: GCE VM name.
  • zone: GCE Zone (e.g., us-west1-a).
  • image_tag: Docker image tag currently in use.
  • machine_type: GCE Machine type (e.g., e2-standard-4).
  • status: One of PROVISIONING, READY, SUSPENDED, ERROR.
  • last_connected_at: Timestamp for auto-cleanup logic.
  • metadata: { repo: string, branch: string, device_id: string }.

4. GCE Lifecycle Management

The Hub uses the GCP Compute Engine Node.js SDK to interact with VMs.

Provisioning

1. Verify the user has quota and permissions.
2. Call instances.insert with "Container-on-VM" configuration.
3. Inject cloud-init or metadata scripts to:
   • Setup SSH (via IAP).
   • Configure the memory-only mount for secrets.
   • Notify the Hub when the container is ready.

Auto-Cleanup (TTL)

• A periodic Cloud Scheduler job triggers a /cleanup endpoint on the Hub.
• Idle workspaces (based on last_connected_at) are automatically stopped or deleted to prevent unnecessary GCP costs.

5. Multi-Tenancy Implementation

• Team Mode: The Hub's service account must have "Compute Admin" roles on the shared project.
• Access Control: Every API request is checked against the owner_id in Firestore. Only the owner (or an admin in team mode) can modify or delete a workspace.
• Resource Isolation: Each workspace is an independent VM. There is no sharing of CPU/Memory between workspaces.

6. Deployment

The Hub is provided as a Terraform module (/terraform/workspace-hub/) for automated setup of:

• Cloud Run service.
• Firestore database.
• Artifact Registry (for Workspace Images).
• IAM roles and permissions.