Configuration
uuBright Console reads its settings from environment variables. In host mode, setup writes them to server.env in the data directory (~/.local/share/ccr-cloud/server.env by default) and the service loads that file at startup. Restart the service after any change.
Keep server.env private. It holds your owner token and any bot credentials.
#Core
| Variable | Default | Description |
|---|---|---|
CCR_CLOUD_TOKEN | Generated by setup | Owner token for the app and API. Anyone with it controls your tasks. |
CCR_CLOUD_DRIVER | host (written by setup) | host runs Claude Code as the server user; docker runs containers. |
CCR_CLOUD_COMPUTER_NAME | Host’s friendly name | Name shown during pairing and on connected phones. On macOS, defaults to System Settings’ computer name; generated EC2 hostnames become “Cloud server”. Set a distinct name such as “Research server”; restart the service to apply it. Stable identity and existing custom phone names stay unchanged. |
CCR_CLOUD_LOCAL | Unset | 1 enables the desktop local defaults: loopback only, local token handoff, and the macOS data path. |
STUDIO_ENABLED | Off | 1 restores the built-in Studio workspace, native page, and native API during the transition. Off creates no new Studio workspace at startup; existing native-only records remain stored, while built-in workspaces with an installed connector and legacy connector workspaces remain available through connector chat. |
STUDIO_REDIRECTS_ENABLED | Off | 1 sends the old /studio-native page to https://scimigo.com/. Enable only after existing Studio history is available there. This switch never redirects API requests. |
CCR_CLOUD_HOST_DRIVER | tmux when available, otherwise process | Set process to run host tasks without tmux. |
CCR_CLOUD_HOST_CGROUP | Unset | systemd starts each host task's runner in its own transient systemd user scope (systemd-run --user --scope), a cgroup that holds the whole task. Scopes belong to your user's systemd manager, which stops them when your last login ends unless lingering is on: run loginctl enable-linger first. Without a working user manager, runners start as plain process groups and the server logs why. If a scope later fails to start (for example, the user manager went away), that runner starts again without one, and so do later runners. |
CCR_CLOUD_BOOT_START | Unset | off stops npm run setup -- --start from installing the boot unit described in After a reboot. Read from the shell, not server.env. |
CCR_CLOUD_HOST_TASK_MEMORY_MAX | Unset | With CCR_CLOUD_HOST_CGROUP=systemd: a memory limit per task, as systemd's MemoryMax (4G, 50%). |
CCR_CLOUD_DATA | ~/.local/share/ccr-cloud | Data directory: configuration, tasks, logs, workspaces, push keys. Use the same value for setup, doctor and updates. |
CCR_CLOUD_HOST | 127.0.0.1 | Address the app and API listen on. Change it only for a VPN. |
CCR_CLOUD_PORT | 8787 | Port for the app and API. |
CCR_CLOUD_SOCKET | Unset | Local mode only: serve the app and API on this Unix socket instead of CCR_CLOUD_HOST/CCR_CLOUD_PORT. Its folder must be yours and not writable by others. The desktop app uses it. |
CCR_CLOUD_REPO_ROOTS | ~/src on Linux; five common folders on macOS | Colon-separated folders that replace the default repository discovery roots in host mode, including the common folders searched two levels deep and Desktop and Documents. |
CCR_CLOUD_PUSH_SUBJECT | The project URL | Your mailto: or https: contact for push services. Apple rejects localhost. |
CCR_CLOUD_QUIET_HOURS | 22:00-08:00 | When notifications wait until morning, except urgent decisions. off turns quiet hours off. |
CCR_CLOUD_PUSH_FALLBACK_MIN | 3 | Minutes after a decision was held back because you were using the app (recent input on a focused window) before a notification follows, if it is still open and you haven't opened its task. 0 turns it off. |
CCR_CLOUD_TIMEZONE | UTC | Time zone for quiet hours until a device turns on notifications; after that, the zone of the most recently registered device is used. An IANA name such as Europe/London; the server refuses to start with an unknown one. |
CCR_CLOUD_PUSH | decisions | all also notifies finished turns, failures, ready and merged PRs and room notes. |
GH_TOKEN | Unset | GitHub token passed to tasks. In host mode, prefer the server user's own Git credentials. |
CCR_CLOUD_BROWSER_BIN | Unset | Path to Chromium or Chrome. Each task then starts its own headless browser with a throwaway profile (tasks never share one), gets a live Screen, and can ask you to take over the browser for a sign-in (preview, host mode). |
CCR_CLOUD_BROWSER_NO_SANDBOX | Unset | 1 starts that browser without Chromium's sandbox, for hosts that refuse it (Ubuntu 23.10+ AppArmor, many containers). The task account is then the only boundary. |
CCR_CLOUD_CODEX_SANDBOX | Unset (workspace-write) | danger-full-access runs Codex host tasks without Codex's own sandbox, for hosts where it can't start; they then have the server user's access, like Claude host tasks. See Codex. Host mode only. |
CCR_CLOUD_ENABLE_DEEPSEEK_EXPERIMENT | Off | 1 enables the host-only DeepSeek Harness ACP route when its separate executable, absolute DSH_HOME and credential are configured. The New Task choice is hidden otherwise. |
DEEPSEEK_BIN | Unset | Absolute path to the separately installed pinned dsh executable. Keep its Node 24 path first in PATH; the Console server can continue running on Node 22. |
DSH_HOME | Unset | Absolute, host-owned Harness state/profile directory outside task worktrees. The pinned ACP profile reads DEEPSEEK_API_KEY from its private .env file there or the host environment. |
CCR_CLOUD_MAX_STARTS | 3 | How many tasks may start at once on this host, for example after a reboot brings back every task that was mid-turn (1–32). |
CCR_CLOUD_STALL_MINUTES | 20 | How long a running turn may go without output or tool calls, with none of the agent's commands running, before it shows as Stalled (1–1440). Applies to tasks created after the change. |
CCR_CLOUD_MAX_REVIEWERS | 2 | How many PR reviewer tasks may run at once on this host (1–16). |
CCR_CLOUD_ACTIVITY_RETENTION_DAYS | 180 | Days the activity log keeps entries, a whole number from 30 to 3650; anything else stops the server at start-up. Older entries are removed at start-up and once a day, counted back from the newest entry, behind an anchor that keeps the rest verifiable. Removed entries can't be brought back. |
CCR_CLOUD_AUTO_RETIRE_HOURS | 24 | Hours a worker must be idle or exited, with its branch pushed or its PR merged or closed, before the server retires it to free disk. 0 turns it off. Tasks you started are never retired automatically. |
CCR_CLOUD_REVIEW_TIMEOUT_MIN | 20 | Minutes a PR reviewer task may run before it is stopped and marked failed (1–240). |
CCR_CLOUD_HELP_TIMEOUT_MS | 900000 (15 min) | How long an agent waits for you to take over its browser before it gets the browser back. |
#Runner connection
Tasks connect back to the control plane on this endpoint. You rarely need to change these.
| Variable | Default | Description |
|---|---|---|
CCR_CLOUD_RUNNER_HOST | 127.0.0.1 (host), 172.17.0.1 (Docker) | Address the runner endpoint listens on. In Docker mode, keep it on the bridge. |
CCR_CLOUD_RUNNER_PORT | 8788 | Port of the runner endpoint. |
CCR_CLOUD_RUNNER_URL | ws://127.0.0.1:8788 (host), ws://host.docker.internal:8788 (Docker) | The endpoint as seen from inside a task. |
#CCR gateway and Docker mode
| Variable | Default | Description |
|---|---|---|
CCR_GATEWAY_KEY | Required in Docker mode | CCR client key given to tasks. |
CCR_GATEWAY_URL | http://host.docker.internal:3456 (Docker); unset (host) | CCR gateway as seen from a task. In host mode, usually http://127.0.0.1:3456. |
CCR_CLOUD_IMAGE | ccr-cloud-session:dev | Session image built by npm run image. |
In host mode, CCR_GATEWAY_URL and CCR_GATEWAY_KEY are optional. Setting both lets you choose Model access: CCR gateway for a task instead of your Claude account; see Switch models with CCR.
#Model access
Model access connected in the app (⋯ → Settings → Model access) or with npm run setup -- --anthropic-key-stdin, --bedrock-region or --ccr-url isn't in server.env. It's saved in model-access.json in the data directory, readable only by the server user, and applies without a restart. See Bring your own model.
- A gateway in
server.env(CCR_GATEWAY_URL) takes precedence over one saved there. - A saved Anthropic key or Bedrock choice takes precedence over
ANTHROPIC_API_KEY,CLAUDE_CODE_USE_BEDROCKor AWS variables inserver.envand over the server user's Claude login, for Claude tasks in workspaces that use the host's login.
#Remote access
| Variable | Default | Description |
|---|---|---|
CCR_CLOUD_SSH_TARGET | Unset | Your SSH destination, such as my-ec2. Setup uses it only to print a ready-to-copy tunnel command. |
CCR_CLOUD_TUNNEL_NAME | ccr-cloud-HOSTNAME | Name of the Cloudflare tunnel setup creates or reuses. |
CCR_CLOUD_RELAY_URL | Unset | HTTPS origin of a compatible blind relay. Enables the outbound encrypted host connector, including in local mode; the API keeps its loopback binding. |
CCR_CLOUD_RELAY_REGISTRATION_SECRET | Unset | Self-hosted relay registration secret. Keep it in the host's private server.env; it never enters a browser or runner. |
CCR_CLOUD_RELAY_ACCOUNT_TOKEN | Unset | A uuBright relay host token, set by the desktop app from the Keychain. Server hosts use npm run relay -- login instead, which writes relay-account.json and turns the relay on without CCR_CLOUD_RELAY_URL. With CCR_CLOUD_RELAY_ACCOUNT_USER, the username shown in status. The token is only ever sent to CCR_CLOUD_RELAY_ACCOUNT_ORIGIN (default https://relay.uubright.com); if CCR_CLOUD_RELAY_URL names any other relay, the token is ignored. If CCR_CLOUD_RELAY_URL names the uuBright relay but no usable sign-in exists, the relay stays off rather than running as self-hosted. |
CCR_CLOUD_RELAY_ACCOUNT_BOUND | Unset | 1 (set by the desktop app, without a token) runs the uuBright relay for a host that is already registered. The host reconnects with its key and uses the plan saved in relay-plan.json. If the relay refuses it, GET /api/relay/status reports account.state: "token_needed" and the app supplies the token again. |
#Phone access through a relay
With CCR_CLOUD_RELAY_URL set, the host creates a persistent Ed25519 identity and relay device registry in its data directory. The relay connector dials out. Direct HTTP and local mode continue to work without the relay. The owner, with the owner token over direct access, can call POST /api/relay/pairing to obtain a ten-minute, one-use pairing payload (relay, hostId, hostKey, secret); a paired device can't. The phone QR screen is a separate step; keep this payload private. GET /api/relay/devices lists relay devices and the owner revokes one with DELETE /api/relay/devices/:id (a phone can revoke only itself). An owner-grade device, which is the Mac app's connection to a server it manages over SSH, may do both as the owner does.
The encrypted channel carries API calls and session or room event subscriptions. Mutations use durable action IDs; after a dropped response, the phone checks the recorded outcome before trying again. A host crash during a mutation can leave an uncertain outcome, which the phone surfaces for manual reconciliation. The relay does not store missed events. The phone resumes from the host's append-only log at its last applied offset plus one. Application frames are capped below the relay's 256 KiB frame limit, so large API responses need pagination. Artifact files go through the managed relay's encrypted file storage instead of the channel (files over the relay).
#Not yet over the relay
- Live screen: the PWA hides the screen control in relay mode. A direct screen request receives a clear unsupported message instead of opening SSE.
- Artifact files on a self-hosted relay: it has no file storage. Metadata, approval and other JSON API calls work; opening a file asks the phone to use direct access. Signed file URL grants (
POST /api/artifacts/:id/url) are refused over any relay.
#Discord
The owner can configure Discord without a restart in ⋯ → Settings → Messaging. See Discord control. The variables below remain supported and take precedence over PWA-saved credentials. Remove the Discord configuration variables and restart once to transfer management to the PWA.
| Variable | Default | Description |
|---|---|---|
DISCORD_BOT_TOKEN | Unset | Bot token for environment-managed setup; requires DISCORD_OWNER_ID. If unset, PWA-saved setup may be used. |
DISCORD_OWNER_ID | Unset | Your numeric Discord user ID. Only this user can use the bot. |
DISCORD_GUILD_ID | Unset | Register commands in one server for faster testing. |
DISCORD_NOTIFICATIONS | On | Set to 0 to turn off proactive notices from other tasks; selected-chat replies still arrive. |
CCR_CLOUD_PUBLIC_URL | Unset | HTTPS address of your app, used for Open links in Discord and for npm run pair links. |
CCR_CLOUD_PEER_ORIGINS | Unset | Comma-separated origins (scheme, host and port, no path) of your other uuBright Console servers. This server's app may connect to them, and their apps may call this server's API with a bearer token (CORS). Set it on both servers to show them in one window. |
CCR_CLOUD_SSH_HOST | Unset | How an editor reaches this server over SSH, such as ubuntu@ec2.example.com. Enables Open in VS Code / Cursor (Remote-SSH) for task worktrees. |
CCR_CLOUD_TRUST_PROXY | Off | Set to 1 when a reverse proxy you run is the only way in and appends X-Forwarded-For. Wrong pairing codes are then limited per phone address (the last entry) instead of per proxy. Leave it off otherwise: a client could forge the header. |
#Tools and output
| Variable | Default | Description |
|---|---|---|
CLAUDE_BIN | claude | Claude Code executable that setup checks and host tasks run. Resuming a host task applies the current value. |
CODEX_BIN | codex | Codex executable for Codex host tasks. Resuming a host task applies the current value. |
CLAUDE_CONFIG_DIR | Claude Code's default | Honored as usual; host tasks inherit it. |
TAILSCALE_BIN, CLOUDFLARED_BIN | tailscale, cloudflared | Executables setup uses for remote access. |
NO_COLOR, FORCE_COLOR | Unset | Turn colored CLI output off or force it on. |
#Development server
npm run dev uses its own settings and never touches your real data.
| Variable | Default | Description |
|---|---|---|
CCR_CLOUD_DEV_DATA | .data/dev | Data directory for the dev server. |
CCR_CLOUD_DEV_TOKEN | dev | Owner token for the dev server. |
PORT | 8790 | Dev server port. |
#Personal WeChat (experimental)
| Variable | Default | Purpose |
|---|---|---|
WECHAT_ENABLED | unset | Set 1 to enable or 0 to disable via environment. Either value overrides PWA settings; unset allows PWA management. |
WECHAT_NOTIFICATIONS | 1 | Set 0 to suppress and consume unsolicited notices. |
WECHAT_CONTEXT_TTL_SECONDS | 3600 | Local reply-context age limit, 1–86400 seconds. |
WECHAT_ILINK_VERSION | adapter default | Wire compatibility override; not phone app version. |
See Personal WeChat for pairing, privacy and recovery.
#Personal WhatsApp (experimental)
| Variable | Default | Purpose |
|---|---|---|
WHATSAPP_ENABLED | unset | Set 1 to enable the already-paired self-chat channel. |
WHATSAPP_NOTIFICATIONS | unset | Set 1 to send unsolicited task notices. |
See Personal WhatsApp for spare-number pairing and limitations.