<!-- Source: https://console.uubright.com/docs/docker/ -->
# Docker and CCR sessions

Run each task in its own container, with model access through a
[Claude Code Router](https://github.com/musistudio/claude-code-router) (CCR) gateway.
Use this when you want isolation from the host or a provider CCR supports. For
regular Claude Code on your existing server, use [Getting started](https://console.uubright.com/docs/getting-started/)
instead.

Containers get only a CCR client key and, optionally, a GitHub token. Your provider
keys stay in the gateway, and the host's SSH keys and Claude login are never
mounted. See [How it works](https://console.uubright.com/docs/how-it-works/#what-a-task-can-access).

## What you need

- A Linux server with **Docker**: a cloud VM (AWS EC2, Alicloud ECS, …), a home server or a spare machine.
  2 CPUs and 4 GB of memory per concurrent session is a good starting point.
- **Node.js 22.18 or newer**.
- **CCR** with at least one provider configured: `npm install -g @musistudio/claude-code-router`, then
  `ccr ui` to set it up.
- For phone access: an HTTPS address. See [Access from your phone](https://console.uubright.com/docs/remote-access/).
- Optional: a **GitHub token** if sessions should clone private repos or push branches.

## 1. Prepare CCR

1. In the CCR UI, create a **client API key** for uuBright Console. Sessions use it to call the gateway.
2. Make sure the gateway is reachable from Docker containers. Containers cannot reach `127.0.0.1` on the
   host, so the gateway must listen on the Docker bridge address (usually `172.17.0.1`) or on all
   interfaces. Check from a container:

   ```sh
   docker run --rm --add-host host.docker.internal:host-gateway curlimages/curl \
     -s -o /dev/null -w '%{http_code}\n' http://host.docker.internal:3456/
   ```

   Any HTTP status code means it is reachable; `000` means it is not. If the gateway listens on all
   interfaces, block port 3456 from the internet with your firewall or cloud security group.

## 2. Install uuBright Console

Request the Docker-enabled server package from
[support@uubright.com](mailto:support@uubright.com). Follow the package
instructions for installing the service and preparing the session image.

## 3. Configure and start it

Create an environment file, for example `/etc/ccr-cloud.env`, readable only by the user that runs uuBright Console:

```sh
# Owner token: the password for the web app and API. Generate a long random one:
#   openssl rand -hex 24
CCR_CLOUD_DRIVER=docker
CCR_CLOUD_TOKEN=...

# The CCR client key from step 1
CCR_GATEWAY_KEY=...

# Contact address for push services (yours, not localhost)
CCR_CLOUD_PUSH_SUBJECT=mailto:you@example.com

# Optional: lets sessions clone private repos and push branches (see "GitHub repositories")
# GH_TOKEN=github_pat_...

# Where sessions, logs and notification keys are stored
CCR_CLOUD_DATA=/var/lib/ccr-cloud
```

Use the service start command supplied with your package to verify the control
plane at `http://127.0.0.1:8787`. The runner connects out to the control plane
over WebSocket. If you use systemd, configure the service to read the private
environment file and run under an account with the required Docker access.

## Docker settings

These are the settings Docker mode uses. See [Configuration](https://console.uubright.com/docs/configuration/) for
every setting.

| Variable | Default | What it does |
|---|---|---|
| `CCR_CLOUD_TOKEN` | required | Owner token for the web app and API |
| `CCR_GATEWAY_KEY` | required | CCR client key given to sessions |
| `CCR_GATEWAY_URL` | `http://host.docker.internal:3456` | CCR gateway address as seen from a container |
| `CCR_CLOUD_PUSH_SUBJECT` | the project URL | Your contact address for push services |
| `GH_TOKEN` | unset | GitHub token passed to sessions |
| `CCR_CLOUD_DATA` | `.data` | Sessions, event logs, notification keys and devices |
| `CCR_CLOUD_IMAGE` | `ccr-cloud-session:dev` | Session image |
| `CCR_CLOUD_HOST` / `CCR_CLOUD_PORT` | `127.0.0.1` / `8787` | Where the web app and API listen |
| `CCR_CLOUD_RUNNER_HOST` / `CCR_CLOUD_RUNNER_PORT` | `172.17.0.1` / `8788` | Where sessions connect back (Docker bridge only) |
| `CCR_CLOUD_RUNNER_URL` | `ws://host.docker.internal:8788` | That address as seen from a container |


## Credentials and isolation

The server user must have Docker access. Host SSH keys and Claude logins are not
mounted into containers. Configure Git identity in the session image and provide
`GH_TOKEN` only if tasks need it; the agent can use the token from its shell.
CCR keeps provider keys on the gateway; containers receive its client key.
Keep the API on loopback and the runner endpoint on the Docker bridge.
Container limits reduce interference but do not establish a multi-tenant service.

## Next steps

After the service starts, connect and run a scratch task as in
[Getting started](https://console.uubright.com/docs/getting-started/#2-connect-from-your-laptop), then add a
repository by URL ([Work with repositories](https://console.uubright.com/docs/repositories/#add-a-repository-by-url)).
Rebuild the image with `npm run image` after each update.
