gemini-cli/MAINTAINER_ONBOARDING.md

Maintainer Onboarding: High-Performance Offload System 🚀

Welcome to the Gemini CLI maintainer team! This guide will help you set up your remote development environment, which offloads heavy tasks (reviews, fixes, preflight) to a dedicated 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. IAP Permissions: Ensure you have the IAP-secured Tunnel User role on your chosen project.
5. Corporate Identity: Run gcert (or your internal equivalent) recently to ensure SSH certificates are valid.

Architecture: Hybrid VM + Container 🏗️

The offload system uses a Worker 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 dual-path strategy that uses Fast-Path SSH by default and automatically falls back to IAP Tunneling if direct access is blocked.

---

Setup Workflow

1. Initial Configuration (Discovery)

This interactive script configures your local environment to recognize the remote worker.

npm run offload:setup

• What it does: Generates .gemini/offload_ssh_config, verifies project access, and establishes the initial identity handshake.
• Connectivity: If direct internal SSH fails, it will attempt to verify access via an IAP tunnel.

2. Provisioning Your Worker (Infrastructure)

Spin up your dedicated, high-performance VM. If it already exists, this command will verify its health.

npm run offload:fleet provision

• Specs: n2-standard-8, 200GB PD-Balanced disk.
• Self-Healing: It uses a COS startup script to ensure the maintainer-worker container is always running.

3. Remote Initialization

Once provisioned, return to the setup script to finalize the remote environment.

npm run offload:setup

• Auth Sync: Pushes your google_accounts.json to the worker.
• Scoped Token: Generates a magic link for a GitHub PAT and stores it securely on the worker.
• Repo Clone: Performs a filtered (shallow) clone of the repository onto the remote disk.

---

Daily Workflow

Running an Offloaded Job

To perform a deep behavioral review or an agentic fix on your remote worker:

# For a review
npm run offload <PR_NUMBER> review

# For an automated fix
npm run offload <PR_NUMBER> implement

• Isolation: Each job runs in a dedicated Git Worktree (~/dev/worktrees/offload-<id>).
• Persistence: Jobs run inside a tmux session on the remote host. You can disconnect and reconnect without losing progress.

Monitoring "Mission Control"

View the real-time state of your worker and all in-flight jobs:

npm run offload: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.

npm run offload:fleet stop

---

Resilience & Troubleshooting

"SSH Connection Failed"

If the setup or orchestrator reports a connection failure:

1. Check Identity: Run gcert to refresh your SSH credentials.
2. IAP Fallback: The system should automatically attempt IAP tunneling. If it still fails, verify your GCP project permissions.
3. Waking Up: If the worker was stopped, the first command may take ~30 seconds to wake the VM.

"Worker Not Found"

If offload:setup can't find your worker, ensure you have run npm run offload:fleet provision at least once in the current project.