# Google Workspace Setup on Restricted Headless Servers (e.g. ZimaOS)

## Problem
Running the Google Workspace setup script on a headless, package-manager-less system fails with ModuleNotFoundError because `pip` is missing.

## Root cause
- ZimaOS/CasaOS has no `apt-get` and no system pip.
- The `google-workspace` skill's `setup.py` tries `python3 -m pip install` internally and crashes before any OAuth setup can begin.
- OAuth device-code auth (`--device-auth`) is the only viable auth path because the server has no browser for normal OAuth callback.

## Solution path

### Step 1: Bootstrap pip first
Before running the setup script, ensure pip exists in user space:

```bash
export PYTHONUSERBASE=/DATA/AppData/hermes/.local
python3 -m ensurepip --upgrade --user
```

If `ensurepip` is also missing:
```bash
curl -sSL https://bootstrap.pypa.io/get-pip.py -o /tmp/get-pip.py
PYTHONUSERBASE=/DATA/AppData/hermes/.local python3 /tmp/get-pip.py --user
```

### Step 2: Install Google API deps manually
Because the setup script's internal dependency installer uses `python -m pip install` (system python, not your PYTHONUSERBASE), install deps explicitly:

```bash
export PATH="$PYTHONUSERBASE/bin:$PATH"
pip install --user google-api-python-client google-auth-oauthlib google-auth-httplib2
```

### Step 3: Run setup.py through PYTHONUSERBASE
```bash
export HERMES_HOME=/DATA/AppData/hermes
export PYTHONUSERBASE=/DATA/AppData/hermes/.local
export PATH="$PYTHONUSERBASE/bin:$PATH"

python3 $HERMES_HOME/skills/productivity/google-workspace/scripts/setup.py --check
```

### Step 4: Device-auth for headless servers
The normal setup flow's Step 3 (auth URL) must use device-code auth because there's no browser. For the Google Workspace skill specifically, the device-auth flow may require the gws CLI to expose it fully. The fallback:

```bash
# If gws is installed
gws auth login --device
# → user opens URL on another device, enters code
```

For Codex specifically (which also uses Google OAuth), device auth is native:
```bash
codex login --device-auth
```

Both flows cache the token locally at `$HERMES_HOME/.hermes/google_token.json`.

## Key learnings
- Missing pip is a _precondition_ that must be fixed before any Python-based skill setup can run.
- `ensurepip` is the fastest fix on systems that bundle pip wheels (true for ZimaOS Python 3.12).
- Setup scripts that internally call `python -m pip install` silently assume a working pip and don't fall back gracefully.
- Always pre-install deps into a user PYTHONUSERBASE before running complex setup scripts on headless servers.
- Device-code auth is the canonical headless OAuth strategy across both gws and codex CLI.