<!-- Source: https://console.uubright.com/docs/local-mode/ -->
# 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](https://console.uubright.com/docs/security/#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](https://console.uubright.com/docs/repositories/#change-where-uubright-console-looks)). 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](https://console.uubright.com/docs/repositories/#add-a-repository-by-path).
