Claude Relay Service Deployment Guide

Complete deployment tutorial for Claude Relay Service, supporting script, Docker, and manual deployment.

🚀 System Requirements

Minimum Configuration

• CPU: 1 core
• Memory: 512MB (1GB recommended)
• Storage: 30GB available space
• OS: Ubuntu/Debian, CentOS/RedHat, Arch Linux, macOS
• Network: Access to Anthropic API (US region server recommended)

Recommended Configuration

• CPU: 2+ cores
• Memory: 4GB RAM
• Network: Fast connection to home country (improve speed)
• Note: Alibaba Cloud and Tencent Cloud overseas hosts may be blocked by Cloudflare and cannot directly access Claude API

Cost Estimation

• Server: Lightweight cloud server, $5-10 per month
• Claude Subscription: Depends on your cost-sharing arrangement
• Other: Domain name (optional)

🚀 Script Deployment (Recommended)

Recommended one-click deployment using management script, simple and fast, automatically handles all dependencies and configurations.

Quick Installation

# Download and run management script
curl -fsSL https://raw.githubusercontent.com/Wei-Shaw/claude-relay-service/main/scripts/manage.sh -o manage.sh
chmod +x manage.sh
./manage.sh install

# After installation, use crs command to manage service
crs  # Show interactive menu

Script Features

• ✅ One-Click Installation: Automatically detect system environment, install Node.js 18+, Redis and other dependencies
• ✅ Interactive Configuration: Friendly configuration wizard, set port, Redis connection, etc.
• ✅ Auto Start: Automatically start service after installation and display access address
• ✅ Easy Management: Manage service status anytime with crs command

Management Commands

crs status    # Check service status
crs start     # Start service
crs stop      # Stop service
crs restart   # Restart service
crs logs      # View logs
crs update    # Update service
crs uninstall # Uninstall service

🐳 Docker Deployment

For users familiar with Docker, you can use Docker Compose for quick deployment.

Prerequisites

Make sure Docker and Docker Compose are installed on your server:

# Install Docker (Ubuntu/Debian)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Quick Deployment

# Clone project
git clone https://github.com/Wei-Shaw/claude-relay-service.git
cd claude-relay-service

# Start service
docker-compose up -d

# View logs
docker-compose logs -f

Configuration

Edit the docker-compose.yml file to modify configurations:

version: '3.8'
services:
  claude-relay:
    image: weishaw/claude-relay-service:latest
    ports:
      - "8080:8080"
    environment:
      - PORT=8080
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis

  redis:
    image: redis:alpine
    volumes:
      - redis_data:/data

volumes:
  redis_data:

⚙️ Manual Deployment

For advanced users who want full control over the deployment process.

Prerequisites

• Node.js 18+
• Redis 6+
• Git

Installation Steps

# 1. Clone project
git clone https://github.com/Wei-Shaw/claude-relay-service.git
cd claude-relay-service

# 2. Install dependencies
npm install

# 3. Configure environment
cp .env.example .env
# Edit .env file according to your needs

# 4. Build project
npm run build

# 5. Start service
npm start

Environment Configuration

Edit the .env file:

# Server Configuration
PORT=8080
HOST=0.0.0.0

# Redis Configuration
REDIS_URL=redis://localhost:6379

# Claude API Configuration
CLAUDE_API_BASE_URL=https://api.anthropic.com

# Other Configuration
LOG_LEVEL=info
MAX_CONCURRENT_REQUESTS=10

🔧 Post-Deployment Configuration

After successful deployment, you need to configure Claude accounts and client access.

1. Access Web Interface

Open browser and visit: http://your-server-ip:8080

2. Add Claude Accounts

In the web interface:

1. Click "Account Management"
2. Click "Add Account"
3. Enter Claude session token
4. Set account alias and priority

3. Configure Client

For Claude Code client:

# Configure API endpoint
export ANTHROPIC_API_URL=http://your-server-ip:8080/v1
export ANTHROPIC_API_KEY=your-relay-token

# Test connection
claude-code --version

🔒 Security Considerations

Firewall Configuration

# Only open necessary ports
sudo ufw allow 22    # SSH
sudo ufw allow 8080  # Service port
sudo ufw enable

HTTPS Configuration (Optional)

For production use, it's recommended to configure HTTPS:

# Install Certbot
sudo apt install certbot

# Generate certificate
sudo certbot certonly --standalone -d your-domain.com

# Configure Nginx reverse proxy (recommended)

🐛 Troubleshooting

Common Issues

1. Service Won't Start

# Check logs
crs logs

# Check port occupancy
sudo netstat -tlnp | grep 8080

# Check Node.js version
node --version  # Should be 18+

2. Redis Connection Failed

# Check Redis status
sudo systemctl status redis

# Test Redis connection
redis-cli ping

3. Claude API Request Failed

• Check if server can access Anthropic API
• Verify Claude account session token is valid
• Check if IP is blocked by Cloudflare

Log Analysis

# View real-time logs
crs logs -f

# View error logs only
crs logs | grep ERROR

# View specific time range logs
journalctl -u claude-relay-service --since "1 hour ago"

📞 Support

If you encounter issues during deployment:

1. Check the FAQ
2. Search existing issues on GitHub
3. Join our carpool service service for professional support

🔄 Updates and Maintenance

Update Service

# Script deployment update
crs update

# Docker deployment update
docker-compose pull
docker-compose up -d

# Manual deployment update
git pull
npm install
npm run build
crs restart

Regular Maintenance

• Monitor service status regularly
• Check log files for errors
• Update Claude account tokens when they expire
• Backup configuration files and data

---

Deployment complete! 🎉 Your Claude Relay Service is now running and ready to provide secure and efficient Claude API relay services.