Guide · Open source

How to use claude-relay-service: setup, keys and Claude Code

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

claude-relay-service is an open-source server you host yourself. It sits between tools such as Claude Code and the official AI APIs, so you can add your own subscription accounts, issue a separate key to each person and track token usage per key. This guide covers requirements, installation, account and key setup, and how to point Claude Code and Gemini CLI at your server.

CRSWei-Shaw/claude-relay-service · ★ 12.8k · MIT Install options & downloads

Quick start

1Check prerequisites. Confirm Node.js 18+ and Redis 6+ are available on a Linux machine you control.
2Install the service. Run the management script installer from the README, or clone the repository for manual setup.
3Configure secrets and Redis. Set JWT_SECRET and ENCRYPTION_KEY in .env and check the Redis settings in config.
4Sign in to the admin panel. Open /web on your server and use the admin credentials from data/init.json or your preset environment variables.
5Add a Claude account. Generate the OAuth link, log in to Claude, and paste the Authorization Code back into the admin page.
6Create per-user keys. Create one API key per person and set any rate, concurrency, model or client limits you need.
7Point your tools at the server. Set ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN in your shell, then start claude.

Check the requirements before you start

The README lists Node.js 18 or higher and Redis 6 or higher as software requirements, and recommends Linux as the operating system. The project is designed for self-hosting only, so you need a machine you can keep running.

The README also notes that the server should be able to reach the Anthropic API, and that some overseas cloud hosts were blocked by Cloudflare in the author's tests.

Node.js 18 or newer
Redis 6 or newer
Linux recommended; the script installer also lists Ubuntu/Debian, CentOS/RedHat, Arch Linux and macOS
Basic command-line experience and willingness to maintain the server

Install claude-relay-service with the management script

The README recommends the management script, which detects your system, installs Node.js 18+ and Redis if needed, asks for port and Redis settings, and starts the service.

After installation, the script provides a crs command for managing the service.

crs start, crs stop, crs restart and crs status control the service
crs update and crs uninstall handle upgrades and removal

curl -fsSL https://pincc.ai/manage.sh -o manage.sh && chmod +x manage.sh && ./manage.sh install

Alternative: manual installation from the repository

If you prefer manual setup, clone the repository, install dependencies, copy the example config files, then edit .env and config/config.js. The README asks you to set JWT_SECRET and ENCRYPTION_KEY and to point Redis settings at your instance.

Then build the web front end and initialise the admin account. The README notes that the admin credentials are saved to data/init.json unless you preset them with environment variables.

Copy config/config.example.js to config/config.js and .env.example to .env
JWT_SECRET should be at least 32 characters; ENCRYPTION_KEY must be 32 characters
Admin credentials can be preset with ADMIN_USERNAME and ADMIN_PASSWORD

git clone https://github.com/Wei-Shaw//claude-relay-service.git
cd claude-relay-service
npm install
npm run setup

Add Claude accounts and create API keys

Open the web admin at /web on your server, for example http://your-server:3000/web. In the Claude Accounts tab, add an account through OAuth: generate the authorisation link, log in and approve access on the new page, then paste the Authorization Code back into the admin page. The README notes this step may need a proxy if you are in mainland China.

In the API Keys tab, create one key per person. You can name each key and optionally set rate limits, concurrency limits, a model allow-list and client restrictions such as ClaudeCode or Gemini-CLI.

Rate limit: requests and token usage per time window
Concurrency limit: simultaneous requests
Model restriction: which models a key may access
Client restriction: which clients may use the key

Point Claude Code at your server

Claude Code reads the base URL and token from environment variables. Replace the address with your server's IP or domain and use the API key you created in the admin panel.

For Antigravity-channel Claude models, the README uses a separate base URL path and sets ANTHROPIC_MODEL. The README also describes a config file for the VS Code Claude extension.

ANTHROPIC_BASE_URL points at your server, ending in /api/ for the standard pool
ANTHROPIC_AUTH_TOKEN is the key you created in the admin panel

export ANTHROPIC_BASE_URL="http://127.0.0.1:3000/api/"
export ANTHROPIC_AUTH_TOKEN="your-key-created-in-admin"

Run with Docker Compose instead

The README offers a Docker path. A helper script generates the docker-compose.yml file, then docker-compose up -d starts the stack. The compose file includes Redis, data and log volume mounts, a health check and automatic restart.

Set JWT_SECRET and ENCRYPTION_KEY in .env before starting. To find the admin credentials, read data/init.json or run docker logs claude-relay-service.

docker-compose up -d

Keep the service safe and up to date

The README contains a security notice: versions v1.1.248 and below have an admin authentication bypass. It says to update to v1.1.249 or later, or move to CRS 2.0 (sub2api). Check the repository for the current release before you deploy.

The README also warns that using the project may violate Anthropic's terms of service and may lead to account bans, so treat any account you add as at risk.

Update to a fixed release as soon as possible
Review Anthropic's user agreement before use

What people use it for

Splitting one shared Claude Code Max subscription among a small group of friends, with a separate key for each member
Giving a team member access to Claude through a key that tracks their token usage
Routing Claude Code and Gemini CLI through one self-hosted endpoint
Restricting a key to specific models or to a specific client such as ClaudeCode

Frequently asked questions

Is claude-relay-service free to use?

The project is released under the MIT licence, as listed in the repository. You still pay for the server you run it on, and the README estimates a light cloud server at 30 to 60 per month, plus your own Claude subscription.

What do I need to install claude-relay-service?

You need Node.js 18 or higher and Redis 6 or higher, with Linux recommended. The README also expects you to be comfortable with the command line and to handle OAuth setup for each Claude account.

Can I use claude-relay-service without running my own server?

No. The README describes self-hosting only, so you need a server to run it on and must maintain it yourself.

Is it safe to use with Claude accounts?

The README warns that using the project may violate Anthropic's terms of service and may lead to account bans. It also says versions v1.1.248 and below have an admin authentication bypass and should be updated to v1.1.249 or later.

What are the alternatives to claude-relay-service?

The source names sub2api as a comparable project, and the README points to CRS 2.0 (sub2api) as its successor. Compare features and maintenance status before choosing.

Why do Claude Code requests fail or hang on my server?

The README says the server must reach the Anthropic API, and that some overseas cloud hosts from Alibaba Cloud and Tencent Cloud were blocked by Cloudflare in the author's tests. Try a host in a region the README recommends, and check that your Redis and key settings are correct.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

claude-relay-service suits developers and small groups who are comfortable running Node.js and Redis, and who want per-person keys and usage tracking for a Claude subscription they share. It is a poor fit for anyone who wants a hosted service, needs guaranteed access, or has no command-line experience. Given the security notice and the terms-of-service warning in the README, check the current release and the sub2api successor before you deploy.

Install options & downloads