Claude Relay Service (CRS)

The Client Restriction feature allows you to control which clients can use a specific API Key by identifying them via their User-Agent. This improves API security by preventing unauthorized tools from using your keys.

How to use:

1. Enable Restriction: When creating or editing an API Key in the admin interface, check the "启用客户端限制" (Enable Client Restriction) option.
2. Select Clients: Choose one or more allowed clients from the multi-select list.

Predefined Clients:

• ClaudeCode: Matches the official Claude CLI (format: claude-cli/x.x.x (external, cli)).
• Gemini-CLI: Matches the Gemini CLI tool (format: GeminiCLI/vx.x.x (platform; arch)).

Debugging:

• If a client is rejected, the system returns a 403 error.
• Check the service logs to see the actual User-Agent string being sent. This allows you to create custom client definitions if needed.
• Successful Auth Log Example: 🔓 Authenticated request from key: [name] ([id]) in [ms] User-Agent: "claude-cli/1.0.58 (external, cli)"
• Failed Restriction Log Example: 🔍 Checking client restriction for key: [id] ([name]) User-Agent: "[UA_STRING]" Allowed clients: [list] 🚫 Client restriction failed...

// Example of a failed restriction log entry
🔍 Checking client restriction for key: key-id (测试Key)
   User-Agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
   Allowed clients: claude_code, gemini_cli
🚫 Client restriction failed for key: key-id (测试Key) from 127.0.0.1, User-Agent: Mozilla/5.0...

The system automatically pauses account routing when upstream errors occur. You can control this behavior globally via .env or override it on a per-account basis in the admin interface.

Global Configuration (via .env):

• UPSTREAM_ERROR_503_TTL_SECONDS
• UPSTREAM_ERROR_5XX_TTL_SECONDS
• UPSTREAM_ERROR_OVERLOAD_TTL_SECONDS
• UPSTREAM_ERROR_AUTH_TTL_SECONDS
• UPSTREAM_ERROR_TIMEOUT_TTL_SECONDS

Account-Level Overrides (in Admin UI): When editing a Claude Official OAuth Account, you can set:

• Disable temporary cooling (禁用该账号临时冷却): Account will not enter temporary pause even on 503/5xx.
• 503 Cooling Seconds (503 冷却秒数): Leave empty to follow global; 0 to disable.
• 5xx Cooling Seconds (5xx 冷却秒数): Leave empty to follow global; 0 to disable.

Priority Order:

1. Account-level "Disable temporary cooling"
2. Account-level 503/5xx cooling seconds
3. Custom TTL passed during code invocation
4. Global environment variable defaults.

Nginx Proxy Manager (NPM) is ideal for Docker-based deployments. It provides a GUI for managing SSL certificates and proxy hosts.

1. Proxy Host Configuration

Create a new Proxy Host with these settings:

• Domain Names: relay.example.com
• Scheme: http
• Forward Hostname / IP: The IP of your Docker machine (e.g., 192.168.0.1)
• Forward Port: 3000
• Block Common Exploits: Enabled
• Websockets Support: DISABLED (Required to prevent SSE/streaming failure)
• Cache Assets: DISABLED (Required to prevent SSE/streaming failure)

2. SSL Settings

• SSL Certificate: Request a new Let's Encrypt certificate.
• Force SSL: Enabled
• HTTP/2 Support: Enabled
• HSTS Enabled: Enabled
• HSTS Subdomains: Enabled

3. Advanced Nginx Configuration

Add the following to the Advanced tab to ensure correct IP forwarding, streaming support (SSE), and security headers:

# Pass real user IP
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

# Support streaming (WebSocket/SSE)
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_buffering off;

# Long connection timeouts for AI streaming
proxy_read_timeout 300s;
proxy_send_timeout 300s;
proxy_connect_timeout 30s;

# Security Headers
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
add_header X-Frame-Options "DENY" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "no-referrer-when-downgrade" always;
add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;

# Hide server info
proxy_hide_header Server;

# Disable proxy caching for immediate SSE response
proxy_cache_bypass $http_upgrade;
proxy_no_cache $http_upgrade;
proxy_request_buffering off;

Note: Ensure the Claude Relay Service is listening on 0.0.0.0, the container IP, or the host IP so NPM can reach it.

If you prefer manual installation, follow these steps to set up the environment, download the source, and build the service.

1. Environment Preparation

Ubuntu/Debian:

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo apt update && sudo apt install redis-server

CentOS/RHEL:

curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
sudo yum install -y nodejs
sudo yum install redis

2. Download and Configuration

git clone https://github.com/Wei-Shaw//claude-relay-service.git
cd claude-relay-service
npm install
cp config/config.example.js config/config.js
cp .env.example .env

3. Configuration Files

• .env: Set JWT_SECRET (min 32 chars), ENCRYPTION_KEY (32 chars), and Redis connection details (REDIS_HOST, REDIS_PORT, REDIS_PASSWORD).
• config/config.js: Configure server.port, server.host, and redis.host/redis.port.

4. Build and Start

npm run install:web
npm run build:web
npm run setup # Generates admin credentials in data/init.json
npm run service:start:daemon # Starts service in background

# Example of setting admin credentials via env before setup
export ADMIN_USERNAME=cr_admin_custom
export ADMIN_PASSWORD=your-secure-password
npm run setup

To deploy the service on a Linux server (Ubuntu/Debian or CentOS/RHEL), follow these steps:

1. Install Dependencies: Ensure Node.js 18+ and Redis 6+ are installed.
2. Clone and Install: Clone the repository and run npm install.
3. Configure: Copy config/config.example.js to config/config.js and .env.example to .env.
4. Set Environment Variables: In .env, define JWT_SECRET and a 32-character ENCRYPTION_KEY.
5. Initialize: Run npm run setup to generate the initial admin credentials (stored in data/init.json).
6. Start: Run npm run service:start:daemon to run the service in the background.

# Example for Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo apt update && sudo apt install redis-server

# Project setup
git clone https://github.com/Wei-Shaw/claude-relay-service.git
cd claude-relay-service
npm install
cp config/config.example.js config/config.js
cp .env.example .env

# Initialization
npm run setup
npm run service:start:daemon

For containerized deployment, use Docker Compose. This method includes automatic administrator account initialization, data persistence (mounting logs and data directories), a Redis database, health checks, and auto-restart capabilities.

Follow these steps:

1. Download and run the compose generator script.
2. Start the containers.

Required Environment Variables:

• JWT_SECRET: JWT key (at least 32 characters).
• ENCRYPTION_KEY: Encryption key (must be exactly 32 characters).

Optional Environment Variables:

• ADMIN_USERNAME: Set a custom admin username.
• ADMIN_PASSWORD: Set a custom admin password.
• LOG_LEVEL: Logging level (default: info).

To retrieve generated credentials, check the container logs or the ./data/init.json file.

# Step 1: Download and run the compose generator script
curl -fsSL https://pincc.ai/crs-compose.sh -o crs-compose.sh && chmod +x crs-compose.sh && ./crs-compose.sh

# Step 2: Start the service
docker-compose up -d

# Retrieve credentials
docker logs claude-relay-service
# OR
cat ./data/init.json

Droid CLI uses ~/.factory/config.json. Add custom models pointing to the CRS endpoints. Replace http://127.0.0.1:3000 with your actual server address and use your cr_ prefixed API key.

{
  "custom_models": [
    {
      "model_display_name": "Opus 4.5 [crs]",
      "model": "claude-opus-4-5-20251101",
      "base_url": "http://127.0.0.1:3000/droid/claude",
      "api_key": "your_api_key",
      "provider": "anthropic",
      "max_tokens": 64000
    },
    {
      "model_display_name": "GPT5.5 [crs]",
      "model": "gpt-5.5",
      "base_url": "http://127.0.0.1:3000/droid/openai",
      "api_key": "your_api_key",
      "provider": "openai",
      "max_tokens": 16384
    },
    {
      "model_display_name": "Gemini-3-Pro [crs]",
      "model": "gemini-3-pro-preview",
      "base_url": "http://127.0.0.1:3000/droid/comm/v1/",
      "api_key": "your_api_key",
      "provider": "generic-chat-completion-api",
      "max_tokens": 65535
    }
  ]
}