Docker and CCR sessions
Run each task in its own container, with model access through a 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 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.
#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, thenccr uito set it up. - For phone access: an HTTPS address. See Access from your phone.
- Optional: a GitHub token if sessions should clone private repos or push branches.
#1. Prepare CCR
- In the CCR UI, create a client API key for uuBright Console. Sessions use it to call the gateway.
Make sure the gateway is reachable from Docker containers. Containers cannot reach
127.0.0.1on the host, so the gateway must listen on the Docker bridge address (usually172.17.0.1) or on all interfaces. Check from a container:SHELLdocker 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;
000means 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. 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:
# 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-cloudUse 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 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, then add a repository by URL (Work with repositories). Rebuild the image with npm run image after each update.