gemini-cli/docs/architecture/workspaces/sync-and-auth.md

Detailed Design: Sync & Authentication Mechanism

1. Introduction

A core requirement for Gemini CLI Workspaces is the secure and seamless synchronization of developer settings and repository credentials between the local machine and the remote environment.

2. Configuration Sync (~/.gemini/)

To maintain a consistent experience, the local CLI synchronizes the developer's environment to the remote workspace.

Sync Strategy

• Trigger: Initial creation and subsequent connections via gemini workspace connect.
• Mechanism: Secure rsync over SSH tunnel.
• Scope:
  • ~/.gemini/settings.json (aliases, UI preferences).
  • ~/.gemini/commands/ (custom user commands).
  • ~/.gemini/skills/ (custom user-defined skills).
• Exclusions:
  • .gemini/logs/ (local device specific).
  • .gemini/cache/ (can be large and re-generated).
  • Sensitive files containing the word *secret* or *key* (these use the injection mechanism below).

3. Git Authentication (SSH Agent Forwarding)

Private SSH keys never leave the developer's local machine.

• Setup: The local CLI ensures ssh-agent is running and the required keys are added.
• Connection: The SSH connection from the CLI uses the -A (Agent Forwarding) flag.
• Remote: Git on the remote VM automatically uses the forwarded agent socket for cloning or pushing to repositories (GitHub, GitLab, internal).

4. GitHub CLI (gh) Authentication

For advanced integration (PRs, issues), the GitHub CLI requires a token.

• Injection Process:
  1. Local CLI fetches a GitHub Personal Access Token (PAT) from the OS Keychain (e.g., via keytar).
  2. During the SSH handshake, the CLI writes the token to /dev/shm/.gh_token (a memory-only, non-persistent mount).
  3. The remote shell profile (.bashrc or .zshrc) exports GH_TOKEN=$(cat /dev/shm/.gh_token).
• Cleanup: Terminating the workspace container or VM wipes the /dev/shm mount, ensuring no long-lived PATs remain on the remote disk.

5. Hub Authentication

Access to the Workspace Hub API is secured via Google OAuth.

• Local: The CLI uses the gcloud or a built-in OAuth flow to obtain a token.
• Hub: The Hub service (on Cloud Run) validates the bearer token and extracts the sub (Google User ID) to partition data in Firestore.

6. Multi-Device "Handover" Workflow

1. Device A (Laptop): Creates workspace work-1. Hub records owner=user-x.
2. Device B (Surface): User moves to a coffee shop. Runs gemini workspace connect work-1.
3. Hub Check: Hub verifies the user is user-x.
4. Client Sync: Device B pushes its local ~/.gemini settings and its own GitHub PAT to work-1.
5. Result: work-1 now behaves exactly like the user's local Device B environment.