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

VariableDefaultDescription
CCR_CLOUD_TOKENGenerated by setupOwner token for the app and API. Anyone with it controls your tasks.
CCR_CLOUD_DRIVERhost (written by setup)host runs Claude Code as the server user; docker runs containers.
CCR_CLOUD_COMPUTER_NAMEHost’s friendly nameName 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_LOCALUnset1 enables the desktop local defaults: loopback only, local token handoff, and the macOS data path.
STUDIO_ENABLEDOff1 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_ENABLEDOff1 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_DRIVERtmux when available, otherwise processSet process to run host tasks without tmux.
CCR_CLOUD_HOST_CGROUPUnsetsystemd 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_STARTUnsetoff 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_MAXUnsetWith CCR_CLOUD_HOST_CGROUP=systemd: a memory limit per task, as systemd's MemoryMax (4G, 50%).
CCR_CLOUD_DATA~/.local/share/ccr-cloudData directory: configuration, tasks, logs, workspaces, push keys. Use the same value for setup, doctor and updates.
CCR_CLOUD_HOST127.0.0.1Address the app and API listen on. Change it only for a VPN.
CCR_CLOUD_PORT8787Port for the app and API.
CCR_CLOUD_SOCKETUnsetLocal 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 macOSColon-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_SUBJECTThe project URLYour mailto: or https: contact for push services. Apple rejects localhost.
CCR_CLOUD_QUIET_HOURS22:00-08:00When notifications wait until morning, except urgent decisions. off turns quiet hours off.
CCR_CLOUD_PUSH_FALLBACK_MIN3Minutes 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_TIMEZONEUTCTime 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_PUSHdecisionsall also notifies finished turns, failures, ready and merged PRs and room notes.
GH_TOKENUnsetGitHub token passed to tasks. In host mode, prefer the server user's own Git credentials.
CCR_CLOUD_BROWSER_BINUnsetPath 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_SANDBOXUnset1 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_SANDBOXUnset (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_EXPERIMENTOff1 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_BINUnsetAbsolute 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_HOMEUnsetAbsolute, 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_STARTS3How 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_MINUTES20How 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_REVIEWERS2How many PR reviewer tasks may run at once on this host (1–16).
CCR_CLOUD_ACTIVITY_RETENTION_DAYS180Days 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_HOURS24Hours 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_MIN20Minutes a PR reviewer task may run before it is stopped and marked failed (1–240).
CCR_CLOUD_HELP_TIMEOUT_MS900000 (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.

VariableDefaultDescription
CCR_CLOUD_RUNNER_HOST127.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_PORT8788Port of the runner endpoint.
CCR_CLOUD_RUNNER_URLws://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

VariableDefaultDescription
CCR_GATEWAY_KEYRequired in Docker modeCCR client key given to tasks.
CCR_GATEWAY_URLhttp://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_IMAGEccr-cloud-session:devSession 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_BEDROCK or AWS variables in server.env and over the server user's Claude login, for Claude tasks in workspaces that use the host's login.

#Remote access

VariableDefaultDescription
CCR_CLOUD_SSH_TARGETUnsetYour SSH destination, such as my-ec2. Setup uses it only to print a ready-to-copy tunnel command.
CCR_CLOUD_TUNNEL_NAMEccr-cloud-HOSTNAMEName of the Cloudflare tunnel setup creates or reuses.
CCR_CLOUD_RELAY_URLUnsetHTTPS 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_SECRETUnsetSelf-hosted relay registration secret. Keep it in the host's private server.env; it never enters a browser or runner.
CCR_CLOUD_RELAY_ACCOUNT_TOKENUnsetA 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_BOUNDUnset1 (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.

VariableDefaultDescription
DISCORD_BOT_TOKENUnsetBot token for environment-managed setup; requires DISCORD_OWNER_ID. If unset, PWA-saved setup may be used.
DISCORD_OWNER_IDUnsetYour numeric Discord user ID. Only this user can use the bot.
DISCORD_GUILD_IDUnsetRegister commands in one server for faster testing.
DISCORD_NOTIFICATIONSOnSet to 0 to turn off proactive notices from other tasks; selected-chat replies still arrive.
CCR_CLOUD_PUBLIC_URLUnsetHTTPS address of your app, used for Open links in Discord and for npm run pair links.
CCR_CLOUD_PEER_ORIGINSUnsetComma-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_HOSTUnsetHow 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_PROXYOffSet 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

VariableDefaultDescription
CLAUDE_BINclaudeClaude Code executable that setup checks and host tasks run. Resuming a host task applies the current value.
CODEX_BINcodexCodex executable for Codex host tasks. Resuming a host task applies the current value.
CLAUDE_CONFIG_DIRClaude Code's defaultHonored as usual; host tasks inherit it.
TAILSCALE_BIN, CLOUDFLARED_BINtailscale, cloudflaredExecutables setup uses for remote access.
NO_COLOR, FORCE_COLORUnsetTurn colored CLI output off or force it on.

#Development server

npm run dev uses its own settings and never touches your real data.

VariableDefaultDescription
CCR_CLOUD_DEV_DATA.data/devData directory for the dev server.
CCR_CLOUD_DEV_TOKENdevOwner token for the dev server.
PORT8790Dev server port.

#Personal WeChat (experimental)

VariableDefaultPurpose
WECHAT_ENABLEDunsetSet 1 to enable or 0 to disable via environment. Either value overrides PWA settings; unset allows PWA management.
WECHAT_NOTIFICATIONS1Set 0 to suppress and consume unsolicited notices.
WECHAT_CONTEXT_TTL_SECONDS3600Local reply-context age limit, 1–86400 seconds.
WECHAT_ILINK_VERSIONadapter defaultWire compatibility override; not phone app version.

See Personal WeChat for pairing, privacy and recovery.

#Personal WhatsApp (experimental)

VariableDefaultPurpose
WHATSAPP_ENABLEDunsetSet 1 to enable the already-paired self-chat channel.
WHATSAPP_NOTIFICATIONSunsetSet 1 to send unsolicited task notices.

See Personal WhatsApp for spare-number pairing and limitations.