---
name: Kiro Gateway token sync architecture
description: How kiro-gateway HA cluster handles AWS SSO OIDC tokens — Mac is the single auth authority, syncs to LXCs every 20min via LaunchAgent
type: reference
---

Three kiro-gateway LXCs (900/.215 on PX1, 901/.216 on PX2, 902/.217 on PX3) proxy Kiro IDE's API behind VIP 192.168.86.210:8000.

Auth uses AWS SSO OIDC via kiro-cli. Credentials are in `/root/.local/share/kiro-cli/data.sqlite3` on each LXC (`auth_kv` table, key `kirocli:odic:token`).

**Critical:** AWS SSO OIDC refresh tokens are single-use. Multiple LXCs cannot independently hold the same token — whichever refreshes first invalidates the others.

**Solution:** Mac is the single token authority. LaunchAgent `com.csader.kiro-token-sync` (script at `~/.local/bin/kiro-token-sync.sh`) syncs Mac's `~/Library/Application Support/kiro-cli/data.sqlite3` to all three LXCs every 20 minutes via scp + pct push. Log at `~/Library/Logs/kiro-token-sync.log`.

**If tokens expire:** Copy Mac's DB manually, or run `kiro-cli login` (requires browser) then run the sync script. No non-interactive re-auth path exists once refresh token is dead.

Full ops doc: `4 - Areas/Home/Homelab-2026/Operations/Kiro Gateway Operations.md`