systems

Systems

Active contributors: Ran, Nik

This lens documents the long-lived runtime components of DroidProxy — the parts that start when the app launches and keep running in the background. DroidProxy is a macOS menu bar app that runs two local servers so Factory Droid can talk to your Claude/Codex/Gemini/Kimi subscriptions as custom models. For the high-level request flow and process model, see ../overview/architecture.md.

Pages in this lens

• Thinking proxy — the raw TCP HTTP proxy on localhost:8317 that Droid CLI connects to. Parses requests, applies a closed set of mutations (Anthropic-Beta rewriting, Claude thinking-block sanitization, OpenAI fast-mode, model-alias and path rewrites, Cursor routing), and forwards to the backend.
• Backend supervisor / ServerManager — starts, stops, and supervises the bundled cli-proxy-api child process on 127.0.0.1:8318, merges config, and runs provider login flows.
• Auth management — scans ~/.cli-proxy-api/ for per-provider auth JSON, parses accounts, detects expiry, and toggles per-account enabled state.
• OAuth usage tracker — reads Codex/Claude OAuth quota windows for the settings "OAuth Quota Usage" section.
• App shell & UI — the LSUIElement menu bar app: lifecycle, settings window, Sparkle updater, auth-directory watching, and startup ordering of the two servers.

How the systems connect

graph TD
    Droid["Droid CLI"] -->|":8317 HTTP"| TP["Thinking proxy<br/>(thinking-proxy.md)"]
    TP -->|":8318 forward"| CP["cli-proxy-api<br/>(server-manager.md)"]
    TP -->|"cursor-* models"| Cursor["cursor-api.standardagents.ai"]
    CP -->|"upstream"| Upstream["Provider APIs<br/>(Claude / Codex / Gemini / Kimi)"]

    Shell["App shell & UI<br/>(app-shell.md)"] -->|"start/stop"| TP
    Shell -->|"supervises"| SM["ServerManager<br/>(server-manager.md)"]
    SM -->|"spawns"| CP
    Shell -->|"watches dir"| AuthDir["~/.cli-proxy-api/"]
    Auth["Auth management<br/>(auth.md)"] -->|"reads"| AuthDir
    Usage["OAuth usage tracker<br/>(oauth-usage-tracker.md)"] -->|"reads quota"| AuthDir
    SM -->|"writes merged-config.yaml"| AuthDir
    TP -->|"reads cursor.json / enabledProviders"| AuthDir

Loading

See also: ../overview/architecture.md.