reference configuration

Configuration

DroidProxy has three configuration surfaces:

1. The bundled backend config config.yaml, merged into merged-config.yaml at runtime.
2. AppPreferences keys persisted in UserDefaults.
3. Info.plist keys that govern bundle identity and Sparkle updates.

Bundled backend config

The backend config template ships at /Users/nikhilanand/droidproxy/src/Sources/Resources/config.yaml. At startup ServerManager.getConfigPath() (/Users/nikhilanand/droidproxy/src/Sources/ServerManager.swift) reads the bundled template, overlays user preferences, and writes the result to ~/.cli-proxy-api/merged-config.yaml. CLIProxyAPI is launched against that merged file, not the bundled template.

Key	Default	Purpose	Overridden at merge time
port	8318	Port CLIProxyAPI listens on; ThinkingProxy on :8317 forwards to it.	No
host	127.0.0.1	Bind address. Localhost-only by default to avoid exposure on public IPs.	Yes — first host: 127.0.0.1 anchor is replaced with AppPreferences.bindAddress; a missing anchor logs a warning.
remote-management.allow-remote	false	Enables the remote management API.	Yes — allow-remote: false replaced with the value of AppPreferences.allowRemote.
remote-management.secret-key	""	Secret for the management API; empty disables it.	Yes — the empty secret-key: "" line is replaced with AppPreferences.secretKey.
auth-dir	"~/.cli-proxy-api"	Directory holding OAuth tokens (Claude / Codex / Gemini / Kimi).	No
debug	false	Verbose backend debug logging.	Yes — replaced with AppPreferences.verboseLogging.
logging-to-file	false	Writes backend logs to file.	Yes — replaced with AppPreferences.verboseLogging.
usage-statistics-enabled	true	Backend usage statistics.	No
proxy-url	""	Optional network proxy for corporate environments.	No
request-retry	3	Retry count for upstream provider requests.	No
request-timeout	"10m"	Upstream request timeout; "0" disables it. Generous to allow long extended-thinking requests.	No
disable-cooling	true	Disables global auth/model cooldown scheduling so a single transient failure does not blackout every auth (issue #57).	No
routing.strategy	"round-robin"	Upstream auth selection strategy.	No
routing.session-affinity	true	Pins a session to one upstream auth so stateful Responses API traffic (encrypted reasoning state, previous_response_id) survives follow-up turns (issue #58).	No
routing.session-affinity-ttl	"2h"	Lifetime of a session-to-auth pin.	No
quota-exceeded.switch-project	true	Switch project on quota exhaustion.	No
quota-exceeded.switch-preview-model	true	Switch preview model on quota exhaustion.	No
generative-language-api-key	[]	Generative Language API keys; empty because providers are OAuth-based.	No

Merge behavior

getConfigPath() performs surgical, anchor-based string replacement rather than re-serializing the YAML:

• host, allow-remote, secret-key, debug, and logging-to-file are replaced by matching their exact anchor lines. The host replacement targets only the first host: 127.0.0.1 occurrence and logs a warning if the anchor is absent.
• For any provider toggled off in the UI, an oauth-excluded-models: block is appended (sorted), with each disabled provider mapped to - "*". CLIProxyAPI hot-reloads this, so provider enable/disable does not require a restart.
• The merged content is written atomically to ~/.cli-proxy-api/merged-config.yaml, after which the file's POSIX permissions are set to 0o600 (owner read/write only). If the write fails, the code falls back to returning the bundled template path.

User-facing settings (allow-remote, secret-key, bind address) live in UserDefaults rather than the YAML so they persist across app updates that replace the bundled template.

AppPreferences (UserDefaults)

Defined in /Users/nikhilanand/droidproxy/src/Sources/AppPreferences.swift.

Key	Default	Controls
gpt53CodexFastMode	false	Inject service_tier=priority for gpt-5.3-codex (fast mode).
gpt54FastMode	false	Inject service_tier=priority for gpt-5.4.
gpt55FastMode	false	Inject service_tier=priority for gpt-5.5.
allowRemote	false	Written into merged-config.yaml as remote-management.allow-remote.
secretKey	""	Written into merged-config.yaml as remote-management.secret-key.
bindAddress	"127.0.0.1"	Backend host bind address. Beta-gated — only honored when betaFlag is true; otherwise the default is used.
oledTheme	false	OLED (true-black) settings theme.
backgroundOpacity	0.55	Settings window background opacity. Falls back to the default when the key is unset.
betaFlag / BETA_FLAG	false	Gates beta features, including the custom bind address.
verboseLogging	false	Drives both backend debug and logging-to-file in the merged config.

Bind address validation

AppPreferences.bindAddress is only read when betaFlag is true; otherwise it returns 127.0.0.1. The stored value is trimmed of surrounding whitespace and rejected (falling back to the default) if it is empty or contains a newline. This prevents an invalid NWEndpoint host and stops extra lines from being injected into the generated YAML.

Info.plist keys

From /Users/nikhilanand/droidproxy/src/Info.plist. The version strings (CFBundleShortVersionString, CFBundleVersion) are overwritten at build time by create-app-bundle.sh.

Key	Value	Role
CFBundleExecutable	CLIProxyMenuBar	Executable name inside the bundle.
CFBundleIdentifier	com.droidproxy.app	Bundle identifier / app identity.
LSUIElement	true	Menu-bar (agent) app with no Dock icon.
LSMinimumSystemVersion	13.0	Minimum supported macOS.
SUFeedURL	https://raw.githubusercontent.com/anand-92/droidproxy/main/appcast.xml	Sparkle appcast feed.
SUPublicEDKey	sB98dHKSN9fEe3vmVAufZoI4TbRWE6hHvAGSbzKweYM=	EdDSA public key for verifying updates.
SUScheduledCheckInterval	86400	Sparkle check interval in seconds (24 hours).
SUEnableAutomaticChecks	true	Enables scheduled update checks.

Related pages

• Server manager
• Fast mode
• Security
• Deployment