mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-03-26 05:50:56 -07:00
49 lines
2.7 KiB
Markdown
49 lines
2.7 KiB
Markdown
# 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.
|