overview getting started

Getting started

This page covers installing the released app, building from source, and the developer loop. For the full release pipeline see Deployment.

Prerequisites

• macOS 13.0 (Ventura) or later
• Apple Silicon (arm64) — there is no Intel build
• For building from source: a recent Xcode / Swift 5.9 toolchain
• A Factory account and the Droid CLI, plus at least one AI subscription (Claude, ChatGPT/Codex, Gemini/Antigravity, or Kimi)

Install the released app

1. Download DroidProxy-arm64.zip from Releases.
2. Unzip and drag DroidProxy.app into /Applications.
3. Launch it. The app lives in the menu bar (it has no dock icon).

Releases are code-signed with an Apple Developer ID and notarized, and installed copies auto-update via Sparkle.

First-run setup

1. Click the menu bar icon and choose Open Settings.
2. In Services, click Add Account next to a provider and complete the OAuth flow in your browser.
3. Click Apply next to Factory custom models to write the DroidProxy model aliases into ~/.factory/settings.json (a timestamped backup is made first).
4. In Factory, restart or open a new session and pick a DroidProxy: … model from the picker.

Manual Factory configuration (if you prefer editing settings.json by hand) is documented in SETUP.md at the repo root.

Build from source

The Swift package lives in src/, so run swift commands from there.

# Debug build (no .app bundle)
cd src && swift build

# Run the tests
cd src && swift test

# Release build + signed .app bundle (run from the repo root)
./create-app-bundle.sh

# Preferred dev loop: kill running DroidProxy, rebuild the signed .app, relaunch
./dev-relaunch.sh

swift run does not work for this app because it is an LSUIElement menu bar app — you must build the .app bundle and open it. dev-relaunch.sh handles this: it kills any running CLIProxyMenuBar / cli-proxy-api processes, runs create-app-bundle.sh (which does swift build -c release and assembles the signed bundle), then launches the fresh build.

What create-app-bundle.sh does

create-app-bundle.sh (repo root) builds DroidProxy.app:

1. swift build -c release (honors TARGET_ARCH if set).
2. Assembles Contents/MacOS, Contents/Resources, and Contents/Frameworks.
3. Copies the executable, bundled resources (including cli-proxy-api), Sparkle.framework, and Info.plist.
4. Injects the version (APP_VERSION env or latest git tag) and build number (git rev-list --count HEAD).
5. Code-signs the binary, the bundled backend, Sparkle, and the whole bundle (using CODESIGN_IDENTITY or an auto-detected Developer ID, falling back to ad-hoc).

Verifying it works

• The menu bar item shows Server: Running (port 8317) when both servers are up.
• Copy Server URL puts http://localhost:8317 on the clipboard.
• Open Dashboard opens the backend management page at http://127.0.0.1:8318/management.html (only useful when remote management is configured).
• Per-request reasoning is logged to /tmp/droidproxy-debug.log.

Next steps

• Understand the design in Architecture.
• Learn the request rewriting rules in Thinking proxy.
• See how models are registered in Reasoning and models.
• Read Patterns and conventions before making changes.