Desktop integration (Electron)

Browser cookie inheritance does not work in Electron, mobile, or any native app. Those clients use an OAuth-style device flow against xcity-home.

Flow

desktop app                      xcity-home                    user browser
   │                                  │                              │
   │  POST /api/auth/device/start ───▶│                              │
   │  { client: "xct-agent-desktop"}  │                              │
   │                                  │                              │
   │ ◀── { device_code, user_code,    │                              │
   │       verify_url, interval }     │                              │
   │                                  │                              │
   │ open verify_url in browser ─────────────────────────────────────▶│
   │                                  │ ◀── user logs in, approves ──│
   │                                  │                              │
   │  POST /api/auth/device/poll ────▶│                              │
   │  { device_code }                 │                              │
   │                                  │                              │
   │ ◀── { access_token, refresh,     │                              │
   │       expires_in }               │                              │

Poll every interval seconds (default 5s). Stop on 400 expired_token or 200.

Token storage

Store the access token in the OS keychain:

• macOS — keytar writing to Keychain.
• Windows — Credential Manager.
• Linux — Secret Service (gnome-keyring/kwallet).

Never persist to plain files. Refresh on 401.

Using the token

Same as browser — but pass it via Authorization: Bearer header instead of relying on the cookie:

const res = await fetch('https://www.xcity.one/api/me/litellm-key', {
  headers: { Authorization: `Bearer ${accessToken}` },
});

The /api/me/litellm-key envelope is identical. From there, identical inference flow.

Updates

xct-agent-desktop self-updates from /api/agent-desktop/releases. The endpoint returns a manifest with current/min versions and a signed download URL.

Last updated: May 15, 2026