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, stores each task's record and an append-only log of everything that happened, and sends 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 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 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.

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 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. 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 Codex app-server adapter, and relays the agent'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.

An experimental DeepSeek Harness ACP host route appears in New Task when the host has explicitly configured its pinned runtime and credential; it can also be selected through the owner API. It uses a separately installed stdio subprocess and the same runner transport and worktree; unsupported task features are rejected.

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.

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 CodexAs your user, in tmux or a detached process groupIn one container per task
Model accessYour server user's Claude login or API config, or optionally a CCR gatewayA Claude Code Router gateway
Git credentialsYour server user's SSH keys and helpersAn optional GH_TOKEN
WorkspacesA Git worktree per task, or a scratch folderA volume per task, cloned from a URL
IsolationNone beyond separate foldersNon-root container, no capabilities, resource limits
Set up withGetting startedDocker and CCR sessions

#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 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 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, 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.

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.

#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