Local mode
The desktop app can start this repository's control plane with CCR_CLOUD_LOCAL=1. Local mode selects host execution and binds both the API and runner endpoint to 127.0.0.1. It rejects a public URL, a non-loopback bind address, and a remote runner endpoint. It does not create a tunnel. On macOS the default data directory is ~/Library/Application Support/CCR Cloud/; on Linux it is ~/.local/share/ccr-cloud/. CCR_CLOUD_DATA can override the directory.
With CCR_CLOUD_SOCKET=/path/service.sock the API listens on that Unix socket instead of a TCP port; the desktop app sets it. Any local account can bind a free loopback port while the service is down and collect the token from clients that still send it there. No other account can create a socket in a folder only you can write, so the server refuses a folder that others can write and creates the socket with mode 0600. A stale socket from a crash is replaced only after it refuses two connections in a row (macOS also refuses a live socket whose backlog is full). If another instance is still serving it, for example one shutting down during an update, the new one waits up to 15 seconds and then exits. A .lock file next to the socket keeps two instances starting at once from both clearing it. It records the holder's PID and process start time and appears complete or not at all; a lock whose PID has exited or now belongs to another process (after a crash or reboot) is cleared. The socket path may be at most 103 bytes (the macOS limit), so keep CCR_CLOUD_DATA short.
The control plane creates owner-token once, with mode 0600, for the desktop app to copy into Keychain. The desktop then calls POST /api/local/owner-token/handoff-complete with owner authentication and the core deletes the file. Only a SHA-256 hash remains in owner-token.sha256; restarts do not recreate the raw file. Existing installs with a raw token are migrated on startup. If Keychain loses the token, stop uuBright Console, run CCR_CLOUD_LOCAL=1 uubright local reset-owner-token, start it again, and copy the new owner-token handoff into Keychain. The previous token stops working. See What tasks on your Mac can access.
Host tasks use tmux when available. On a Mac without tmux they use the process driver automatically. Set CCR_CLOUD_HOST_DRIVER=process to select it explicitly. Each task runs in its own detached process group; its private state directory contains process.json (PID and process start time) and runner.log. Stopping a task interrupts its group and then terminates it if needed. Task runners reconnect to the control plane after it restarts. A machine reboot stops task processes; use Resume to restart them.
The server looks for Claude Code and Codex using CLAUDE_BIN and CODEX_BIN, then the login shell, common user and Homebrew locations, and npm's global bin. If none of those gives a Codex that runs and supports app-server (0.163.0 or newer), it uses the CLI bundled with the Codex app (/Applications/ChatGPT.app/Contents/Resources/codex-cli/bin/codex, or the same path under ~/Applications). GET /api/setup reports agents.claude and agents.codex, each with found, path, version, and a best-effort loggedIn value. A Codex task can run without Claude Code installed. For Codex, install a CLI that supports app-server (version 0.163.0 or newer). The desktop app should verify which executable its Codex installation exposes and test a task before relying on an existing login.
On macOS, local repository discovery checks ~/src, ~/code, ~/Projects, ~/Developer, and ~/GitHub. On Linux it checks ~/src. On both it also looks two levels deep in ~/workspace, ~/repos and the other common folders; on a Mac, ~/Desktop and ~/Documents only after you choose Look in Desktop and Documents (why). Setting CCR_CLOUD_REPO_ROOTS replaces these defaults on either platform. Saved projects continue to work as before. A checkout elsewhere can be added by its path.