<!-- Source: https://console.uubright.com/docs/configuration/ -->
# 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](https://console.uubright.com/docs/operations/#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](https://console.uubright.com/docs/docker/). |
| `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](https://console.uubright.com/docs/local-mode/): 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](https://console.uubright.com/docs/operations/#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](https://console.uubright.com/docs/remote-access/#your-own-vpn-or-reverse-proxy). |
| `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](https://console.uubright.com/docs/local-mode/) uses it. |
| `CCR_CLOUD_REPO_ROOTS` | `~/src` on Linux; five common folders on macOS | Colon-separated folders that replace the default [repository discovery](https://console.uubright.com/docs/repositories/#change-where-uubright-console-looks) 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](https://console.uubright.com/docs/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](https://console.uubright.com/docs/notifications/) 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](https://console.uubright.com/docs/codex/). Host mode only. |
| `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](https://console.uubright.com/docs/reliability/#stalled-tasks) (1–1440). Applies to tasks created after the change. |
| `CCR_CLOUD_MAX_REVIEWERS` | `2` | How many [PR reviewer tasks](https://console.uubright.com/docs/lead/#local-pr-review) may run at once on this host (1–16). |
| `CCR_CLOUD_ACTIVITY_RETENTION_DAYS` | `180` | Days the [activity log](https://console.uubright.com/docs/security/#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](https://console.uubright.com/docs/tasks/#automatic-retire) 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](https://console.uubright.com/docs/switch-models/).

## 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](https://console.uubright.com/docs/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

| 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](https://console.uubright.com/docs/relay-managed/) 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](https://console.uubright.com/docs/security/#who-can-do-what), 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](https://console.uubright.com/docs/relay-managed/#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](https://console.uubright.com/docs/discord/#set-up-from-the-pwa). 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](https://console.uubright.com/docs/multi-host/). |
| `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](https://console.uubright.com/docs/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](https://console.uubright.com/docs/whatsapp/) for spare-number pairing and limitations.
