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, then ccr ui to 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

  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:

    SHELL
    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. 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:

SHELL
# 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 for every setting.

VariableDefaultWhat it does
CCR_CLOUD_TOKENrequiredOwner token for the web app and API
CCR_GATEWAY_KEYrequiredCCR client key given to sessions
CCR_GATEWAY_URLhttp://host.docker.internal:3456CCR gateway address as seen from a container
CCR_CLOUD_PUSH_SUBJECTthe project URLYour contact address for push services
GH_TOKENunsetGitHub token passed to sessions
CCR_CLOUD_DATA.dataSessions, event logs, notification keys and devices
CCR_CLOUD_IMAGEccr-cloud-session:devSession image
CCR_CLOUD_HOST / CCR_CLOUD_PORT127.0.0.1 / 8787Where the web app and API listen
CCR_CLOUD_RUNNER_HOST / CCR_CLOUD_RUNNER_PORT172.17.0.1 / 8788Where sessions connect back (Docker bridge only)
CCR_CLOUD_RUNNER_URLws://host.docker.internal:8788That 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.