<!-- Source: https://console.uubright.com/docs/how-it-works/ -->
# How it works

uuBright Console has two parts: a **control plane** that you talk to, and one **runner** per
task that runs Claude Code. Everything runs on your own server.

```
 Browser / installed app        Discord bot (optional)
            │ owner token              │ owner's Discord ID
            ▼                          ▼
 ┌──────────────────────────────────────────────┐
 │ control plane (ccr-cloud)                    │
 │  HTTP API · task records · event logs · push │
 └──────────────────────────────────────────────┘
            ▲ runner connects out over a WebSocket
            │ (events and commands are acknowledged)
 ┌──────────┴───────────┐   ┌──────────────────────┐
 │ runner → Claude Code │   │ runner → Claude Code │  one per task
 │ task workspace       │   │ task workspace       │
 └──────────────────────┘   └──────────────────────┘
```

## Experimental relay package

`services/relay/` contains a blind Cloudflare Worker and per-host Durable Object with short-lived connection admission. `src/relay/connector.ts` is an outbound host connector, and `src/relay/account.ts` signs a host in to the managed uuBright relay and fetches its registration proofs. The managed entry point (`services/relay/src/managed.ts`) adds an account API and per-account host binding; it is not deployed yet. Direct access and the self-hosted core continue to work without it. The relay package contract describes its admission and binary routing frames.

## The control plane

The control plane serves the web app and the [HTTP API](https://console.uubright.com/docs/api/), stores each task's
record and an append-only log of everything that happened, and sends
[notifications](https://console.uubright.com/docs/notifications/). It listens on `127.0.0.1:8787` by default, and
every API call needs the owner token.

The web app's scripts are also served at `/v/<version>/…`, where they never change and a browser may keep them
for good; the page's import map sends every import there. The version is a hash of the app's files, so any update is a
new version and a version is always one consistent set. After a first load, opening the app again fetches the page and
none of its scripts, which matters on a slow link and in the iPhone app, which has no service worker. A page left open
across an update that asks for its old version gets nothing rather than a newer file, and the app's update notice asks
you to reload. Browsers without import maps (Safari before 16.4) load the scripts from their plain addresses, as before.

The runner also offers an [artifact publishing tool](https://console.uubright.com/docs/artifacts/) over its
acknowledged RPC link. The control plane stores versioned artifact records in a
separate index, appends a publication notice to the task log, and serves host
workspace files through short-lived capability URLs. The runner protocol is v0.12.

A task asks the owner a [decision](https://console.uubright.com/docs/tasks/#answer-decisions) the same way, with the
`ask_owner` tool on that link. The control plane logs it on the task (a runner can't
log one itself), keeps it open on the task record until answered, and sends the
answers back as a message through the task's outbox, so a stopped or reconnecting
task gets them like any other message. A resent call finds the decision it already
made. Notifications follow one policy (`src/server/push-policy.ts`): decisions only,
batched, and held during quiet hours.

### Session view

Claude Code's raw output is large: in a typical task, tool output and inputs are
most of the log. The control plane translates the log into a short *session view*
in one place (`src/server/view.ts`), so the app, notifications and chat channels
don't each read Claude Code's stream format:

- **Items**: your messages, Claude's text, decision cards (updated in place once
  answered; the message carrying your answers stays off the feed), turn ends (completed, failed or
  interrupted; a turn with background tasks ends once they finish, with a marker
  where Claude's own part ended), status changes, changes summaries and pull requests.
- **Tool groups**: consecutive tool calls between two pieces of Claude text become
  one item with a title ("Explored · 14 steps (8 reads, 4 searches, 2 fetches) · 1
  error") and one line per step: a short verb and what it acted on ("Shell", then
  the command). Claude's thinking blocks are steps too, read back only when opened,
  and never counted. A subagent's own calls count inside the step that
  started it. Approvals attach to the call that asked for them.
- **Order**: items follow the log, except follow-ups you send while the agent
  works. A queued follow-up stays at the bottom, below the current turn's output,
  and moves to just before its own turn when the runner starts it. A withdrawn or
  uncertain one goes back to where you sent it. Runners before protocol 0.9 queue
  follow-ups themselves without reporting when they start, so theirs stay where
  they were sent.
- **Detail on demand**: a step's input and output are fetched by offset only when
  someone opens it.
- **Task card**: state, what the agent is doing now, the last few steps, step and
  error counts, files changed, a waiting approval and the start of the last
  answer. Its activity text is public-safe ("Running tests"), never a raw command
  or output, because it may be shown on other services.

The log stays the source of truth; the view is rebuilt from it, so nothing about
reconnects or recovery changes. See the [`/view` and `/detail`
endpoints](https://console.uubright.com/docs/api/#sessions).

The PR watcher stores when a PR first becomes ready to merge, separately from the
task's last agent activity. That timestamp brings a newly ready PR back to **Needs
you** even if you already saw the task while checks were pending. Viewing the
ready result, or marking its finished card seen, clears that device's attention
until the PR becomes ready again after another change. The PR still stays under **Ready to review** in the task list and on
the board until it merges; only the Needs you count and inbox clear.

### Board

The [board](https://console.uubright.com/docs/tasks/#see-the-board) is a second fold, in `src/server/board.ts`: task records, their tracked PRs,
local review rounds and reported deploys become cards in four states (Needs you, Working, Ready, Done this week), plus a
`planned` mark on workers that haven't started, which the app shows as To do. Like
the session view it is derived, never edited, so it is recomputed whenever a task logs an event, a record changes
(the PR watcher, a review finishing) or a deploy is reported, and streamed to the app as whole snapshots. The only
per-device part is "seen": each card carries the state its task takes once the device has opened it. A task's state
comes from `src/server/public/states.js`, the same module the task list uses, so the two always agree.

## Runners

An owner can mark a task as a [lead](https://console.uubright.com/docs/lead/). Its `ccr-lead` tools reach the
control plane over the runner's authenticated connection to create and follow
workers. Worker tasks retain their own runner connections and event logs.

Each task has a runner process. It prepares the workspace, starts Claude Code in
headless mode, or the [preview Codex app-server adapter](https://console.uubright.com/docs/codex/), and relays Claude's output and permission requests to the control
plane. The runner always **dials out** to the control plane, so a task never needs
an open port.

Dropped connections and control plane restarts don't lose task activity. Runner
events are numbered and resent until the control plane stores them, and your
messages and approvals are resent until the runner confirms them. When you reopen
the app, it replays the task's log. A crashed runner can still lose what it hadn't
reported, and actions aren't exactly-once; see
[Failure and recovery](https://console.uubright.com/docs/reliability/).

Foreground turns and background work are tracked separately. Raw agent results
remain in the log for usage/history; a `turn_completed` event signals logical
completion for the clients and messaging channels. Status events carry foreground
activity and the live background-task count. This uses the same numbered,
acknowledged event stream; snapshots replace the background set, and transient
child IDs are not restored across runner boots. Older unmarked result events
remain renderable when reading existing logs. Managed raw results contribute usage
immediately, while the turn count and completion cost settle at logical completion.
On upgrade, saved usage records migrate once to logical-turn counts and completion
costs from their event logs; already recorded total spend, tokens, billing and the
current process baseline are preserved.
Newer Claude Code versions echo the submitted user-message UUID on results; the
runner uses that join key to reject delayed results from older sends. Older
producers without this field retain the legacy result-based acknowledgement and
cannot disambiguate a delayed, distinct result from the next silent user turn.
A terminal child notification waits briefly for foreground output; after one quiet
second it releases that wait if no assistant output started. A later autonomous
reply appears as new activity. Task/run tombstones retain the latest 2,048 ends per
runner boot; authoritative task snapshots remain the reconciliation source.

## Execution modes

| | Host mode (default) | Docker mode |
|---|---|---|
| Runs Claude Code or Codex | As your user, in tmux or a detached process group | In one container per task |
| Model access | Your server user's Claude login or API config, or optionally a [CCR gateway](https://console.uubright.com/docs/switch-models/) | A [Claude Code Router](https://github.com/musistudio/claude-code-router) gateway |
| Git credentials | Your server user's SSH keys and helpers | An optional `GH_TOKEN` |
| Workspaces | A Git worktree per task, or a scratch folder | A volume per task, cloned from a URL |
| Isolation | None beyond separate folders | Non-root container, no capabilities, resource limits |
| Set up with | [Getting started](https://console.uubright.com/docs/getting-started/) | [Docker and CCR sessions](https://console.uubright.com/docs/docker/) |

## What a task can access

- **Host mode** tasks have everything your server user has: files, credentials,
  cloud permissions and network. A worktree keeps files apart; it isn't a sandbox.
  Use a dedicated account you trust for coding work.
- **Docker mode** tasks get only a CCR client key and, if you set it, `GH_TOKEN`.
  Your model provider keys stay in the CCR gateway, and the host's SSH keys and
  Claude login are never mounted. The agent can read `GH_TOKEN` from its shell.
- In both modes, the runner's own session token is removed from Claude's
  environment, so the agent can't act as the runner.

uuBright Console serves one owner. Don't use it to give untrusted people access to a
server. See the [Security model](https://console.uubright.com/docs/security/) for what is and isn't enforced.

## Where data lives

Everything is in the data directory, `~/.local/share/ccr-cloud` by default
(`~/Library/Application Support/CCR Cloud/` for [desktop local mode](https://console.uubright.com/docs/local-mode/) on macOS):
configuration and owner token (`server.env` in server mode, a hash after local handoff), task records and event logs, task
workspaces (`host/SESSION_ID/`), [rooms](https://console.uubright.com/docs/rooms/), saved projects, push keys, registered devices and a week of reported deploys (`deploys.json`),
and what Insights has already worked out from each task's log (`insights-digests.json`: counts and times, no message
text; safe to delete, it is rebuilt from the logs).
Keep it private and [back it up](https://console.uubright.com/docs/operations/#back-up-your-data).

Workspace records and project links live under `workspaces/`. A startup migration
creates Default and assigns existing projects, tasks and rooms to it. New tasks
receive the selected workspace's Git and GitHub identity in their runner
environment. See [Workspaces](https://console.uubright.com/docs/workspaces/).

## Your agreements stay yours

uuBright Console is software you run. It doesn't host agents or sell model access. You
use Claude Code, and any provider behind CCR, under your own agreements with them.

## Next steps

- [Getting started](https://console.uubright.com/docs/getting-started/)
- [Configuration](https://console.uubright.com/docs/configuration/)
