Claude Code Router

https://musistudio.github.io/claude-code-router/docs
Admin
Claude Code Router routes Claude Code requests to different model providers and supports custom...
Tokens:34,017
Snippets:441
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Complete Example: Global and Project Configurations

Source: https://musistudio.github.io/claude-code-router/docs/cli/config/project-level

Illustrates a complete setup with global configuration and specific project configurations for web and AI projects.

```json
### Global Configuration (~/.claude-code-router/config.json)
{
  "Providers": [
    {
      "name": "openai",
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "$OPENAI_API_KEY",
      "models": ["gpt-4", "gpt-3.5-turbo"]
    },
    {
      "name": "anthropic",
      "baseUrl": "https://api.anthropic.com/v1",
      "apiKey": "$ANTHROPIC_API_KEY",
      "models": ["claude-3-5-sonnet-20241022"]
    }
  ],
  "Router": {
    "default": "openai,gpt-4",
    "background": "openai,gpt-3.5-turbo"
  }
}

### Web Project Configuration
{
  "Router": {
    "default": "openai,gpt-4"
  }
}

### AI Project Configuration
{
  "Router": {
    "default": "anthropic,claude-3-5-sonnet-20241022",
    "think": "anthropic,claude-3-5-sonnet-20241022"
  }
}
```

--------------------------------

### Install a Preset from a Local Directory

Source: https://musistudio.github.io/claude-code-router/docs/cli/commands/preset

Installs a preset by providing the path to its directory or by specifying the name of an already installed preset to reconfigure.

```bash
ccr preset install <source>
```

```bash
# Install from directory  
ccr preset install ./my-preset  
  
# Reconfigure an installed preset  
ccr preset install my-preset
```

--------------------------------

### Create Advanced Preset with Dynamic Configuration

Source: https://musistudio.github.io/claude-code-router/docs/presets/intro

This snippet shows how to create an advanced preset with dynamic configuration options, including multi-provider support and conditional prompts. It guides through creating the preset directory, manifest.json, installing, and using the preset.

```bash
# Create preset directory  
mkdir -p ~/.claude-code-router/presets/advanced-config  
  
# Create manifest.json  
cat > ~/.claude-code-router/presets/advanced-config/manifest.json << 'EOF'  
{
  "name": "advanced-config",
  "version": "1.0.0",
  "description": "Advanced configuration with multi-provider support",
  "author": "Your Name",
  "keywords": ["openai", "deepseek", "multi-provider"],

  "schema": [
    {
      "id": "provider",
      "type": "select",
      "label": "Select Provider",
      "prompt": "Choose your primary LLM provider",
      "options": {
        "type": "static",
        "options": [
          {
            "label": "OpenAI",
            "value": "openai",
            "description": "Use OpenAI's GPT models"
          },
          {
            "label": "DeepSeek",
            "value": "deepseek",
            "description": "Use DeepSeek's cost-effective models"
          }
        ]
      },
      "defaultValue": "openai",
      "required": true
    },
    {
      "id": "apiKey",
      "type": "password",
      "label": "API Key",
      "prompt": "Enter your API Key",
      "placeholder": "sk-…",
      "required": true
    },
    {
      "id": "enableProxy",
      "type": "confirm",
      "label": "Enable Proxy",
      "prompt": "Access API through a proxy?",
      "defaultValue": false
    },
    {
      "id": "proxyUrl",
      "type": "input",
      "label": "Proxy URL",
      "prompt": "Enter proxy server address",
      "placeholder": "http://127.0.0.1:7890",
      "required": true,
      "when": {
        "field": "enableProxy",
        "operator": "eq",
        "value": true
      }
    }
  ],

  "template": {
    "Providers": [
      {
        "name": "#{provider}",
        "api_base_url": "#{provider === 'openai' ? 'https://api.openai.com/v1/chat/completions' : 'https://api.deepseek.com/v1/chat/completions'}",
        "api_key": "#{apiKey}",
        "models": ["gpt-4o", "gpt-4o-mini"]
      }
    ],
    "Router": {
      "default": "#{provider},gpt-4o",
      "background": "#{provider},gpt-4o-mini"
    }
  },

  "configMappings": [
    {
      "target": "PROXY_URL",
      "value": "#{proxyUrl}",
      "when": {
        "field": "enableProxy",
        "operator": "eq",
        "value": true
      }
    }
  ]
}
EOF  
  
# Configure preset (will prompt for input)  
ccr preset install advanced-config  
  
# Use preset  
ccr advanced-config "your prompt"  


```

--------------------------------

### View Preset Information

Source: https://musistudio.github.io/claude-code-router/docs/presets/intro

Get detailed information about a specific installed preset.

```bash
ccr preset info my-preset  
```

--------------------------------

### Start Claude Code with a Preset

Source: https://musistudio.github.io/claude-code-router/docs/presets/intro

After installing a preset, use its name to start Claude Code with its pre-configured settings.

```bash
# Start with a specific preset  
ccr my-preset "your prompt"  
```

--------------------------------

### List All Installed Presets

Source: https://musistudio.github.io/claude-code-router/docs/presets/intro

Display all installed presets, including their names, versions, and descriptions.

```bash
ccr preset list  
```

--------------------------------

### Install Preset from Local Directory

Source: https://musistudio.github.io/claude-code-router/docs/presets/intro

Use this command to install a preset from a local directory on your machine.

```bash
ccr preset install /path/to/preset-directory  
```

--------------------------------

### Install a Preset

Source: https://musistudio.github.io/claude-code-router/docs/cli/commands/preset

Installs a preset from a local or remote path. Users can install presets shared by others using this command.

```bash
ccr preset install /path/to/my-preset
```

--------------------------------

### ccr start Usage

Source: https://musistudio.github.io/claude-code-router/docs/cli/commands/start

The basic usage of the ccr start command. Use this to start the server with default settings.

```bash
ccr start [options]  
```

--------------------------------

### Start with Default Settings

Source: https://musistudio.github.io/claude-code-router/docs/cli/commands/start

Starts the Claude Code Router server using all default configurations.

```bash
ccr start  
```

--------------------------------

### Start with Custom Configuration File

Source: https://musistudio.github.io/claude-code-router/docs/cli/commands/start

Starts the Claude Code Router server and points it to a specific configuration file.

```bash
ccr start --config /path/to/config.json  
```

--------------------------------

### Minimal Configuration Example

Source: https://musistudio.github.io/claude-code-router/docs/cli/config/basic

A basic configuration including an API key and an OpenAI provider.

```json
{
  // API key (optional, used to protect service)  
  "APIKEY": "your-api-key-here",  
  
  // LLM providers  
  "Providers": [
    {
      "name": "openai",
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "$OPENAI_API_KEY",
      "models": ["gpt-4", "gpt-3.5-turbo"]
    }
  ],
  
  // Default routing  
  "Router": {
    "default": "openai,gpt-4"
  }
}
```

--------------------------------

### List Installed Presets

Source: https://musistudio.github.io/claude-code-router/docs/cli/commands/preset

Displays a list of all presets that have been installed on your system, including their version, description, and author.

```bash
ccr preset list
```

--------------------------------

### Configuration File Example

Source: https://musistudio.github.io/claude-code-router/docs/server/deployment

Example JSON configuration file for the Claude Code Router server, including server, logging, LLM provider, and routing settings.

```json
{
  // Server configuration  
  "HOST": "0.0.0.0",  
  "PORT": 3456,  
  "APIKEY": "your-api-key-here",  
  
  // Logging configuration  
  "LOG": true,  
  "LOG_LEVEL": "info",  
  
  // LLM provider configuration  
  "Providers": [  
    {
      "name": "openai",  
      "baseUrl": "https://api.openai.com/v1",  
      "apiKey": "$OPENAI_API_KEY",  
      "models": ["gpt-4", "gpt-3.5-turbo"]  
    }
  ],  
  
  // Routing configuration  
  "Router": {  
    "default": "openai,gpt-4"  
  }
}

```

--------------------------------

### Reconfigure Installed Preset

Source: https://musistudio.github.io/claude-code-router/docs/presets/intro

Reconfigure an already installed preset by running the install command with the preset name.

```bash
ccr preset install my-preset  
```

--------------------------------

### Configuration Mappings Example

Source: https://musistudio.github.io/claude-code-router/docs/presets/intro

Illustrates using 'configMappings' to precisely control where values are placed in the configuration, including conditional placement.

```json
"configMappings": [
  {
    "target": "Providers[0].api_key",
    "value": "{{apiKey}}"
  },
  {
    "target": "PROXY_URL",
    "value": "{{proxyUrl}}",
    "when": {
      "field": "useProxy",
      "operator": "eq",
      "value": true
    }
  }
]
```

--------------------------------

### Complete Claude Code Router Configuration Example

Source: https://musistudio.github.io/claude-code-router/docs/server/config/basic

A comprehensive example demonstrating the integration of providers, router settings, transformers, and environment variables in a single configuration file.

```json
{
  "port": 8080,
  "Providers": [
    {
      "NAME": "deepseek",
      "HOST": "https://api.deepseek.com",
      "APIKEY": "$DEEPSEEK_API_KEY",
      "MODELS": ["deepseek-chat", "deepseek-coder"],
      "transformers": ["anthropic"]
    },
    {
      "NAME": "groq",
      "HOST": "https://api.groq.com/openai/v1",
      "APIKEY": "$GROQ_API_KEY",
      "MODELS": ["llama-3.3-70b-versatile"],
      "transformers": ["anthropic"]
    }
  ],
  "Router": {
    "default": "deepseek,deepseek-chat",
    "longContextThreshold": 100000,
    "background": "groq,llama-3.3-70b-versatile"
  },
  "transformers": [
    {
      "name": "anthropic",
      "providers": ["deepseek", "groq"]
    }
  ]
}
```

--------------------------------

### Example Model Selection

Source: https://musistudio.github.io/claude-code-router/docs/server/config/providers

This is an example of how to specify a model for routing, using the DeepSeek provider and its 'deepseek-chat' model.

```plaintext
deepseek,deepseek-chat

```

--------------------------------

### Full Routing and Fallback Configuration

Source: https://musistudio.github.io/claude-code-router/docs/server/config/routing

A comprehensive configuration example demonstrating default routing, specific scenario routing, and a detailed fallback strategy for multiple scenarios.

```json
{
  "Router": {
    "default": "deepseek,deepseek-chat",
    "background": "ollama,qwen2.5-coder:latest",
    "think": "deepseek,deepseek-reasoner",
    "longContext": "openrouter,google/gemini-2.5-pro-preview",
    "longContextThreshold": 60000,
    "webSearch": "gemini,gemini-2.5-flash"
  },
  "fallback": {
    "default": [
      "aihubmix,Z/glm-4.5",
      "openrouter,anthropic/claude-sonnet-4"
    ],
    "background": [
      "ollama,qwen2.5-coder:latest"
    ],
    "think": [
      "openrouter,anthropic/claude-3.7-sonnet:thinking"
    ],
    "longContext": [
      "modelscope,Qwen/Qwen3-Coder-480B-A35B-Instruct"
    ],
    "webSearch": [
      "openrouter,anthropic/claude-sonnet-4"
    ]
  }
}

```

--------------------------------

### OpenAI Provider Configuration

Source: https://musistudio.github.io/claude-code-router/docs/cli/config/basic

Example configuration for using the OpenAI provider.

```json
{
  "Providers": [
    {
      "name": "openai",
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "$OPENAI_API_KEY",
      "models": ["gpt-4", "gpt-3.5-turbo"]
    }
  ],
  "Router": {
    "default": "openai,gpt-4"
  }
}
```

--------------------------------

### Current Server Configuration Response

Source: https://musistudio.github.io/claude-code-router/docs/server/api/config-api

Example of the JSON response when fetching the server configuration.

```json
{
  "HOST": "0.0.0.0",
  "PORT": 3456,
  "APIKEY": "sk-xxxxx",
  "Providers": [
    {
      "name": "openai",
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "sk-...",
      "models": ["gpt-4", "gpt-3.5-turbo"]
    }
  ],
  "Router": {
    "default": "openai,gpt-4"
  },
  "transformers": [
    "anthropic"
  ]
}
```

--------------------------------

### Install Claude Code Router with Yarn

Source: https://musistudio.github.io/claude-code-router/docs/cli/installation

Use this command to install the package globally using Yarn. Ensure Yarn is installed.

```bash
yarn global add @musistudio/claude-code-router  

```

--------------------------------

### Pino Log Format Example

Source: https://musistudio.github.io/claude-code-router/docs/server/api/logs-api

This is an example of the log entry format used by the application, adhering to the Pino logging standard.

```json
{
  "level": 30,
  "time": 1703550622000,
  "pid": 12345,
  "hostname": "server",
  "msg": "Incoming request",
  "req": {
    "id": 1,
    "method": "POST",
    "url": "/v1/messages",
    "remoteAddress": "127.0.0.1"
  }
}
```

--------------------------------

### Install Claude Code Router with npm

Source: https://musistudio.github.io/claude-code-router/docs/cli/installation

Use this command to install the package globally using npm. Ensure Node.js and npm are installed and meet the version requirements.

```bash
npm install -g @musistudio/claude-code-router  

```

--------------------------------

### Start with Debug Logging

Source: https://musistudio.github.io/claude-code-router/docs/cli/commands/start

Starts the Claude Code Router server with the log level set to debug for detailed output.

```bash
ccr start --log-level debug  
```

--------------------------------

### Start as Daemon

Source: https://musistudio.github.io/claude-code-router/docs/cli/commands/start

Starts the Claude Code Router server to run as a background daemon process.

```bash
ccr start --daemon  
```

--------------------------------

### Create Simple OpenAI Preset

Source: https://musistudio.github.io/claude-code-router/docs/presets/intro

This snippet demonstrates how to create a basic preset for OpenAI. It involves creating a directory, defining a manifest.json file, installing the preset, and then using it.

```bash
# Create preset directory  
mkdir -p ~/.claude-code-router/presets/simple-openai  
  
# Create manifest.json  
cat > ~/.claude-code-router/presets/simple-openai/manifest.json << 'EOF'  
{
  "name": "simple-openai",
  "version": "1.0.0",
  "description": "Simple OpenAI configuration",
  "author": "Your Name",

  "Providers": [
    {
      "name": "openai",
      "api_base_url": "https://api.openai.com/v1/chat/completions",
      "api_key": "${OPENAI_API_KEY}",
      "models": ["gpt-4o", "gpt-4o-mini"]
    }
  ],

  "Router": {
    "default": "openai,gpt-4o",
    "background": "openai,gpt-4o-mini"
  }
}
EOF  
  
# Configure preset (input API Key)  
ccr preset install simple-openai  
  
# Use preset  
ccr simple-openai "your prompt"  


```

--------------------------------

### Start on Custom Port

Source: https://musistudio.github.io/claude-code-router/docs/cli/commands/start

Starts the Claude Code Router server and specifies a custom port for it to listen on.

```bash
ccr start --port 3000  
```

--------------------------------

### Preset Metadata Example

Source: https://musistudio.github.io/claude-code-router/docs/presets/intro

Defines essential information about the preset, such as its name, version, description, author, and compatibility.

```json
{
  "name": "my-preset",
  "version": "1.0.0",
  "description": "My custom preset",
  "author": "Your Name",
  "homepage": "https://github.com/yourname/ccr-presets",
  "repository": "https://github.com/yourname/ccr-presets.git",
  "license": "MIT",
  "keywords": ["openai", "production"],
  "ccrVersion": "2.0.0"
}
```

--------------------------------

### Install Claude Code Router with pnpm

Source: https://musistudio.github.io/claude-code-router/docs/cli/installation

Use this command to install the package globally using pnpm. Ensure pnpm is installed and meets the version requirements.

```bash
pnpm add -g @musistudio/claude-code-router  

```

--------------------------------

### Dynamic Configuration Schema and Template Example

Source: https://musistudio.github.io/claude-code-router/docs/presets/intro

Defines an interactive configuration system using a schema for input forms and a template for variable substitution.

```json
{
  "schema": [
    {
      "id": "apiKey",
      "type": "password",
      "label": "API Key",
      "prompt": "Enter your API Key",
      "required": true
    },
    {
      "id": "provider",
      "type": "select",
      "label": "Provider",
      "options": {
        "type": "static",
        "options": [
          {"label": "OpenAI", "value": "openai"},
          {"label": "DeepSeek", "value": "deepseek"}
        ]
      },
      "defaultValue": "openai"
    }
  ],
  "template": {
    "Providers": [
      {
        "name": "#{provider}",
        "api_key": "#{apiKey}"
      }
    ]
  }
}
```

--------------------------------

### Example: ccr status Command Execution

Source: https://musistudio.github.io/claude-code-router/docs/cli/commands/status

An example demonstrating the execution of the 'ccr status' command and its typical output when the server is running.

```bash
$ ccr status  
  
Claude Code Router Status: Running  
Version: 2.0.0  
PID: 12345  
Port: 8080  
Uptime: 2h 34m  


```

--------------------------------

### Multiple Providers Configuration

Source: https://musistudio.github.io/claude-code-router/docs/cli/config/basic

Example configuration with both OpenAI and Anthropic providers, and specific routing rules.

```json
{
  "Providers": [
    {
      "name": "openai",
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "$OPENAI_API_KEY",
      "models": ["gpt-4", "gpt-3.5-turbo"]
    },
    {
      "name": "anthropic",
      "baseUrl": "https://api.anthropic.com/v1",
      "apiKey": "$ANTHROPIC_API_KEY",
      "models": ["claude-3-5-sonnet-20241022", "claude-3-opus-20240229"]
    }
  ],
  "Router": {
    "default": "openai,gpt-4",
    "think": "anthropic,claude-3-5-sonnet-20241022",
    "background": "openai,gpt-3.5-turbo"
  }
}
```

--------------------------------

### Set Environment Variables

Source: https://musistudio.github.io/claude-code-router/docs/cli/config/basic

Example of setting environment variables in .bashrc or .zshrc.

```bash
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."  

```

--------------------------------

### Start Docker Compose Service

Source: https://musistudio.github.io/claude-code-router/docs/server/deployment

Starts the services defined in the docker-compose.yml file in detached mode.

```bash
docker-compose up -d  

```

--------------------------------

### Environment Variable Interpolation Example 1

Source: https://musistudio.github.io/claude-code-router/docs/server/api/config-api

Demonstrates using environment variables directly for API keys within the configuration.

```json
{
  "Providers": [
    {
      "apiKey": "$OPENAI_API_KEY"
    }
  ]
}
```

--------------------------------

### Show Detailed Information About a Preset

Source: https://musistudio.github.io/claude-code-router/docs/cli/commands/preset

Retrieves and displays comprehensive details about a specific installed preset, including its metadata, configuration summary, and required inputs.

```bash
ccr preset info <name>
```

```bash
ccr preset info my-config
```

--------------------------------

### Interactive Model Selection Example

Source: https://musistudio.github.io/claude-code-router/docs/cli/commands/model

Demonstrates the interactive prompts and output when selecting a model using the 'ccr model' command.

```bash
$ ccr model  
  
? Select a provider: deepseek  
? Select a model: deepseek-chat  
  
Default model set to: deepseek,deepseek-chat  

```

--------------------------------

### Anthropic Provider Configuration

Source: https://musistudio.github.io/claude-code-router/docs/cli/config/basic

Example configuration for using the Anthropic provider.

```json
{
  "Providers": [
    {
      "name": "anthropic",
      "baseUrl": "https://api.anthropic.com/v1",
      "apiKey": "$ANTHROPIC_API_KEY",
      "models": ["claude-3-5-sonnet-20241022", "claude-3-opus-20240229"]
    }
  ],
  "Router": {
    "default": "anthropic,claude-3-5-sonnet-20241022"
  }
}
```

--------------------------------

### Configuration Update Success Response

Source: https://musistudio.github.io/claude-code-router/docs/server/api/config-api

Example of a successful response after updating the server configuration.

```json
{
  "success": true,
  "message": "Config saved successfully"
}
```

--------------------------------

### Start Claude Code Router UI

Source: https://musistudio.github.io/claude-code-router/docs/cli/quick-start

Launch the web interface for configuring providers visually by running the `ccr ui` command.

```bash
ccr ui

```

--------------------------------

### Return Format Example

Source: https://musistudio.github.io/claude-code-router/docs/server/advanced/custom-router

The expected string format for the return value of a custom router function, specifying the provider and model name.

```text
deepseek,deepseek-chat  

```

--------------------------------

### Environment Variable Interpolation Example 2

Source: https://musistudio.github.io/claude-code-router/docs/server/api/config-api

Shows an alternative format for environment variable interpolation using `${VAR_NAME}` for base URLs.

```json
{
  "baseUrl": "${API_BASE_URL}"
}
```

--------------------------------

### Tool Use (Function Calling) Request

Source: https://musistudio.github.io/claude-code-router/docs/server/api/messages-api

Example request payload demonstrating tool use. Define available tools with their names, descriptions, and input schemas to enable function calling.

```json
{
  "model": "claude-3-5-sonnet-20241022",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "What's the weather like?"
    }
  ],
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "City name"
          }
        },
        "required": ["location"]
      }
    }
  ]
}
```

--------------------------------

### Verify Claude Code Router Installation

Source: https://musistudio.github.io/claude-code-router/docs/cli/installation

Run this command after installation to confirm that the 'ccr' command is available and to display its version number.

```bash
ccr --version  

```

--------------------------------

### Custom Router Logic Example

Source: https://musistudio.github.io/claude-code-router/docs/server/advanced/custom-router

A basic example of a custom router function that returns a model string based on scenario, token count, or request content. This function is exported from a JavaScript file.

```javascript
// custom-router.js  
module.exports = function(config, context) {  
  const { scenario, projectId, tokenCount, request } = context;  
  
  // Your custom logic here  
  if (scenario === 'background') {  
    return 'groq,llama-3.3-70b-versatile';  
  }  
  
  if (tokenCount > 100000) {  
    return 'gemini,gemini-1.5-pro';  
  }  
  
  // Check request content  
  if (request && request.system && request.system.includes('code')) {  
    return 'deepseek,deepseek-coder';  
  }  
  
  // Default  
  return 'deepseek,deepseek-chat';  
};  

```

--------------------------------

### Start Claude Code Execution

Source: https://musistudio.github.io/claude-code-router/docs/cli/intro

Launch Claude Code and route requests through the configured provider. Ensure the service is configured before running this command.

```bash
ccr code  

```

--------------------------------

### Get Server Configuration

Source: https://musistudio.github.io/claude-code-router/docs/server/api/config-api

Use this endpoint to retrieve the current server configuration. Requires an API key.

```bash
curl http://localhost:3456/api/config \
  -H "x-api-key: your-api-key"
```

--------------------------------

### Condition Operator Example (Field Exists)

Source: https://musistudio.github.io/claude-code-router/docs/presets/intro

Demonstrates the 'exists' operator to check if a field is present.

```json
{"field": "apiKey", "operator": "exists"}
```

--------------------------------

### Get List of Log Files

Source: https://musistudio.github.io/claude-code-router/docs/server/api/logs-api

Use this endpoint to retrieve a list of all available log files on the server. Requires an API key for authentication.

```bash
curl http://localhost:3456/api/logs/files \
  -H "x-api-key: your-api-key"
```

--------------------------------

### Successful Server Startup Output

Source: https://musistudio.github.io/claude-code-router/docs/cli/commands/start

This output indicates that the Claude Code Router server has started successfully and provides the URLs for the running server and its API endpoint.

```text
Claude Code Router is running on http://localhost:8080  
API endpoint: http://localhost:8080/v1  
```

--------------------------------

### Fallback Configuration for Primary Model Quota Exhaustion

Source: https://musistudio.github.io/claude-code-router/docs/server/config/routing

Illustrates a fallback setup where backup models are used when the primary model's quota is exhausted.

```json
{
  "Router": {
    "default": "openrouter,anthropic/claude-sonnet-4"
  },
  "fallback": {
    "default": [
      "deepseek,deepseek-chat",
      "aihubmix,Z/glm-4.5"
    ]
  }
}

```

--------------------------------

### Open Web UI

Source: https://musistudio.github.io/claude-code-router/docs/cli/config/basic

Launch the web interface for visual configuration.

```bash
ccr ui  
```

--------------------------------

### Log Monitoring of Fallback Process

Source: https://musistudio.github.io/claude-code-router/docs/server/config/routing

Shows example log messages indicating the system's fallback process, including retries and success/failure of backup models.

```log
[warn] Request failed for default, trying 2 fallback models
[info] Trying fallback model: aihubmix,Z/glm-4.5
[warn] Fallback model aihubmix,Z/glm-4.5 failed: API rate limit exceeded
[info] Trying fallback model: openrouter,anthropic/claude-sonnet-4
[info] Fallback model openrouter,anthropic/claude-sonnet-4 succeeded

```

--------------------------------

### Manually Create Project Configuration

Source: https://musistudio.github.io/claude-code-router/docs/cli/config/project-level

Create the project configuration directory and file manually. Use 'cat' with a heredoc to populate the configuration.

```bash
# Create project configuration directory
mkdir -p ~/.claude/projects/abc123def456

# Create configuration file
cat > ~/.claude/projects/abc123def456/claude-code-router.json << 'EOF'
{
  "Router": {
    "default": "anthropic,claude-3-5-sonnet-20241022",
    "background": "openai,gpt-3.5-turbo"
  }
}
EOF
```

--------------------------------

### Get Loaded Transformers

Source: https://musistudio.github.io/claude-code-router/docs/server/api/config-api

Use this endpoint to retrieve a list of all transformers currently loaded by the server. Requires an API key.

```bash
curl http://localhost:3456/api/transformers \
  -H "x-api-key: your-api-key"
```

--------------------------------

### Schema for Dynamic Select Options

Source: https://musistudio.github.io/claude-code-router/docs/cli/commands/preset

Example of a schema field using 'select' type with dynamic options sourced from available providers.

```json
{
  "id": "provider",
  "type": "select",
  "label": "Select Provider",
  "options": {
    "type": "providers"
  }
}

```

--------------------------------

### Time-Based Routing Example

Source: https://musistudio.github.io/claude-code-router/docs/server/advanced/custom-router

A custom router that selects models based on the current hour, using faster models during work hours and more capable models outside of them.

```javascript
module.exports = function(config, context) {  
  const hour = new Date().getHours();  
  
  // Use faster models during work hours  
  if (hour >= 9 && hour <= 18) {  
    return 'groq,llama-3.3-70b-versatile';  
  }  
  
  // Use more capable models outside work hours  
  return 'deepseek,deepseek-chat';  
};  

```

--------------------------------

### Configuration Fields Example

Source: https://musistudio.github.io/claude-code-router/docs/presets/intro

Merges directly into CCR's configuration, specifying providers, routing rules, transformers, and other settings. Includes CLI-only fields like 'noServer'.

```json
{
  "Providers": [
    {
      "name": "openai",
      "api_base_url": "https://api.openai.com/v1/chat/completions",
      "api_key": "${OPENAI_API_KEY}",
      "models": ["gpt-4o", "gpt-4o-mini"]
    }
  ],
  "Router": {
    "default": "openai,gpt-4o",
    "background": "openai,gpt-4o-mini"
  },
  "PORT": 8080
}
```

--------------------------------

### Multimodal Support with Image Input

Source: https://musistudio.github.io/claude-code-router/docs/server/api/messages-api

Example of a user message containing both an image and text. The image is provided as a base64 encoded string.

```json
{
  "role": "user",
  "content": [
    {
      "type": "image",
      "source": {
        "type": "base64",
        "media_type": "image/png",
        "data": "iVBORw0KGgo..."
      }
    },
    {
      "type": "text",
      "text": "Describe this image"
    }
  ]
}
```

--------------------------------

### Cost Optimization Routing Example

Source: https://musistudio.github.io/claude-code-router/docs/server/advanced/custom-router

A custom router designed for cost optimization, selecting a specific model for requests exceeding a certain token count threshold.

```javascript
module.exports = function(config, context) {  
  const { tokenCount } = context;  
  
  // Use cheaper models for large requests  
  if (tokenCount > 50000) {  
    return 'groq,llama-3.3-70b-versatile';  
  }  
  
  // Use default for smaller requests  
  return 'deepseek,deepseek-chat';  
};  

```

--------------------------------

### Get Server Configuration

Source: https://musistudio.github.io/claude-code-router/docs/server/api/config-api

Retrieves the current server configuration settings. This includes details about the host, port, API keys, configured providers, and transformers.

```APIDOC
## GET /api/config

### Description
Get current server configuration.

### Method
GET

### Endpoint
/api/config

### Request Example
```bash
curl http://localhost:3456/api/config \
  -H "x-api-key: your-api-key"
```

### Response Example (200 OK)
```json
{
  "HOST": "0.0.0.0",
  "PORT": 3456,
  "APIKEY": "sk-xxxxx",
  "Providers": [
    {
      "name": "openai",
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "sk-...",
      "models": ["gpt-4", "gpt-3.5-turbo"]
    }
  ],
  "Router": {
    "default": "openai,gpt-4"
  },
  "transformers": [
    "anthropic"
  ]
}
```
```

--------------------------------

### Delete Installed Preset

Source: https://musistudio.github.io/claude-code-router/docs/presets/intro

Remove a preset from your installed list.

```bash
ccr preset delete my-preset  
```

--------------------------------

### Start Claude Code Router Service

Source: https://musistudio.github.io/claude-code-router/docs/cli/quick-start

Start the Claude Code Router service using the `ccr start` command. The router will be accessible at `http://localhost:8080` by default.

```bash
ccr start

```

--------------------------------

### Scenario 2: Test Projects Use Low-Cost Models

Source: https://musistudio.github.io/claude-code-router/docs/cli/config/project-level

Configure test projects to use lower-cost models like GPT-3.5-turbo for both default and background tasks.

```json
~/.claude/projects/test-project-id/claude-code-router.json:
{
  "Router": {
    "default": "openai,gpt-3.5-turbo",
    "background": "openai,gpt-3.5-turbo"
  }
}
```

--------------------------------

### Scenario 1: Different Projects Use Different Models

Source: https://musistudio.github.io/claude-code-router/docs/cli/config/project-level

Configure distinct default models for web and AI projects by creating separate project configuration files.

```json
// Web project uses GPT-4
~/.claude/projects/web-project-id/claude-code-router.json:
{
  "Router": {
    "default": "openai,gpt-4"
  }
}

// AI project uses Claude
~/.claude/projects/ai-project-id/claude-code-router.json:
{
  "Router": {
    "default": "anthropic,claude-3-5-sonnet-20241022"
  }
}
```

--------------------------------

### Delete an Installed Preset

Source: https://musistudio.github.io/claude-code-router/docs/cli/commands/preset

Removes a specified preset from your installed configurations. This command accepts 'delete', 'rm', or 'remove' as aliases.

```bash
ccr preset delete <name>
```

```bash
ccr preset rm <name>
```

```bash
ccr preset remove <name>
```

```bash
ccr preset delete my-config
```

--------------------------------

### View Configuration File

Source: https://musistudio.github.io/claude-code-router/docs/cli/config/basic

Display the content of the configuration file using the cat command.

```bash
cat ~/.claude-code-router/config.json  
```

--------------------------------

### Host and Port Configuration

Source: https://musistudio.github.io/claude-code-router/docs/cli/config/basic

Configure the listen address and port for the service.

```json
{
  "HOST": "127.0.0.1",  // Listen address  
  "PORT": 3456          // Listen port  
}
```

--------------------------------

### GET /api/logs/files

Source: https://musistudio.github.io/claude-code-router/docs/category/api

API endpoint to access log files.

```APIDOC
## GET /api/logs/files

### Description
API endpoint to access log files.

### Method
GET

### Endpoint
/api/logs/files
```

--------------------------------

### GET /api/config

Source: https://musistudio.github.io/claude-code-router/docs/category/api

API endpoint to retrieve the current configuration.

```APIDOC
## GET /api/config

### Description
API endpoint to retrieve the current configuration.

### Method
GET

### Endpoint
/api/config
```

--------------------------------

### List Configured Models

Source: https://musistudio.github.io/claude-code-router/docs/cli/commands/model

Displays a list of all AI models currently configured in the system.

```bash
ccr model list  

```

--------------------------------

### Pass Configuration Options to Transformers

Source: https://musistudio.github.io/claude-code-router/docs/server/config/transformers

Demonstrates how to pass configuration options to transformers like 'maxtoken' and 'customparams'.

```json
{
  "transformers": [
    {
      "name": "maxtoken",
      "options": {
        "max_tokens": 8192
      }
    },
    {
      "name": "customparams",
      "options": {
        "custom_param_1": "value1",
        "custom_param_2": 42
      }
    }
  ]
}

```

--------------------------------

### View Current Model Configuration Output

Source: https://musistudio.github.io/claude-code-router/docs/cli/commands/model

Shows the expected output format when listing configured models.

```bash
Configured Models:  
  deepseek,deepseek-chat (default)  
  groq,llama-3.3-70b-versatile  
  gemini,gemini-1.5-pro  

```

--------------------------------

### Loaded Transformers Response

Source: https://musistudio.github.io/claude-code-router/docs/server/api/config-api

Example of the JSON response when fetching the list of loaded transformers.

```json
{
  "transformers": [
    {
      "name": "anthropic",
      "endpoint": null
    },
    {
      "name": "openai",
      "endpoint": null
    },
    {
      "name": "gemini",
      "endpoint": "https://generativelanguage.googleapis.com"
    }
  ]
}
```

--------------------------------

### Condition Operator Example

Source: https://musistudio.github.io/claude-code-router/docs/presets/intro

Demonstrates the 'eq' operator for checking if a field equals a specific value.

```json
{"field": "provider", "operator": "eq", "value": "openai"}
```

--------------------------------

### Edit Configuration File

Source: https://musistudio.github.io/claude-code-router/docs/cli/config/basic

Use this command to open the configuration file in the nano editor.

```bash
nano ~/.claude-code-router/config.json  
```

--------------------------------

### Condition Operator Example (Not Equals)

Source: https://musistudio.github.io/claude-code-router/docs/presets/intro

Demonstrates the 'ne' operator for checking if a field does not equal a specific value.

```json
{"field": "advanced", "operator": "ne", "value": true}
```

--------------------------------

### Template Variable Usage

Source: https://musistudio.github.io/claude-code-router/docs/presets/intro

Shows how to use template variables to reference user input within configuration.

```json
"template": {
  "Providers": [
    {
      "name": "{{providerName}}",
      "api_key": "{{apiKey}}"
    }
  ]
}
```

--------------------------------

### Condition Operator Example (Not In Array)

Source: https://musistudio.github.io/claude-code-router/docs/presets/intro

Demonstrates the 'nin' operator for checking if a field's value is not present in an array.

```json
{"field": "type", "operator": "nin", "value": ["x", "y"]}
```

--------------------------------

### Preset Directory Structure

Source: https://musistudio.github.io/claude-code-router/docs/presets/intro

Defines the required and optional files within a custom preset directory.

```bash
~/.claude-code-router/presets/<preset-name>/  
├── manifest.json           # Required: Preset configuration file  
├── transformers/           # Optional: Custom transformers  
│   └── custom-transformer.js  
├── scripts/               # Optional: Custom scripts  
│   └── status.js  
└── README.md              # Optional: Documentation  

```

--------------------------------

### Condition Operator Example (In Array)

Source: https://musistudio.github.io/claude-code-router/docs/presets/intro

Demonstrates the 'in' operator for checking if a field's value is present in an array.

```json
{"field": "feature", "operator": "in", "value": ["a", "b"]}
```

--------------------------------

### Mount Configuration File

Source: https://musistudio.github.io/claude-code-router/docs/server/deployment

Run the Docker container and mount a specific configuration file into the container's configuration directory.

```bash
docker run -d \
  --name claude-code-router \
  -p 3456:3456 \
  -v $(pwd)/config.json:/app/.claude-code-router/config.json \
  musistudio/claude-code-router:latest  

```

--------------------------------

### Error Response: 401 Unauthorized

Source: https://musistudio.github.io/claude-code-router/docs/server/api/messages-api

Example of a 401 Unauthorized error response, indicating an issue with the provided API key.

```json
{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}
```

--------------------------------

### Verify Project Configuration using CLI

Source: https://musistudio.github.io/claude-code-router/docs/cli/config/project-level

Use 'ccr status' to view the routing rules currently applied to your project. Check logs for detailed routing decisions.

```bash
# View routing used by current project
ccr status

# Check logs to confirm routing decisions
tail -f ~/.claude-code-router/claude-code-router.log
```

--------------------------------

### Project Configuration File Path

Source: https://musistudio.github.io/claude-code-router/docs/cli/config/project-level

The project configuration file is located in ~/.claude/projects/<project-id>/claude-code-router.json.

```bash
~/.claude/projects/<project-id>/claude-code-router.json
```

--------------------------------

### Build Docker Image from Source

Source: https://musistudio.github.io/claude-code-router/docs/server/deployment

Clones the repository and builds a local Docker image for the Claude Code Router server.

```bash
git clone https://github.com/musistudio/claude-code-router.git  
cd claude-code-router  
docker build -t claude-code-router:latest .  

```

--------------------------------

### Get Default Log Content

Source: https://musistudio.github.io/claude-code-router/docs/server/api/logs-api

Retrieves the content of the default log file ('app.log'). An API key is required for authentication.

```bash
curl "http://localhost:3456/api/logs" \
  -H "x-api-key: your-api-key"
```

--------------------------------

### Export a Preset

Source: https://musistudio.github.io/claude-code-router/docs/cli/commands/preset

Exports the current preset configuration to a directory. This is the first step in sharing a preset.

```bash
ccr preset export my-preset
```

--------------------------------

### Get Transformers List

Source: https://musistudio.github.io/claude-code-router/docs/server/api/config-api

Retrieves a list of all transformers loaded by the server. This includes built-in transformers like anthropic, openai, and gemini.

```APIDOC
## GET /api/transformers

### Description
Get list of all transformers loaded by the server.

### Method
GET

### Endpoint
/api/transformers

### Request Example
```bash
curl http://localhost:3456/api/transformers \
  -H "x-api-key: your-api-key"
```

### Response Example (200 OK)
```json
{
  "transformers": [
    {
      "name": "anthropic",
      "endpoint": null
    },
    {
      "name": "openai",
      "endpoint": null
    },
    {
      "name": "gemini",
      "endpoint": "https://generativelanguage.googleapis.com"
    }
  ]
}
```

### Transformer List
Built-in transformers:
  * `anthropic` - Anthropic Claude format
  * `openai` - OpenAI format
  * `deepseek` - DeepSeek format
  * `gemini` - Google Gemini format
  * `openrouter` - OpenRouter format
  * `groq` - Groq format
  * `maxtoken` - Adjust max_tokens parameter
  * `tooluse` - Tool use conversion
  * `reasoning` - Reasoning mode conversion
  * `enhancetool` - Enhance tool functionality
```

--------------------------------

### Configure HTTPS with Certbot

Source: https://musistudio.github.io/claude-code-router/docs/server/deployment

Command to obtain and configure a free SSL certificate using Let's Encrypt and Certbot for a specified domain.

```bash
sudo certbot --nginx -d your-domain.com  

```

--------------------------------

### Use Claude Code

Source: https://musistudio.github.io/claude-code-router/docs/cli/quick-start

Interact with Claude Code normally after starting the router. Requests will be routed through Claude Code Router to your configured LLM providers.

```bash
ccr code

```

--------------------------------

### Environment Variable Interpolation

Source: https://musistudio.github.io/claude-code-router/docs/cli/config/basic

Demonstrates how to use environment variables for API keys within the configuration.

```json
{
  "Providers": [
    {
      "apiKey": "$OPENAI_API_KEY"  // Read from environment variable  
    }
  ]
}
```

--------------------------------

### Schema for Conditional Fields

Source: https://musistudio.github.io/claude-code-router/docs/cli/commands/preset

Example of a conditional schema field that appears based on a previous selection, dynamically fetching model options for the selected provider.

```json
{
  "id": "model",
  "type": "select",
  "label": "Select Model",
  "when": {
    "field": "provider",
    "operator": "exists"
  },
  "options": {
    "type": "models",
    "providerField": "#{selectedProvider}"
  }
}

```

--------------------------------

### Configure Groq Provider

Source: https://musistudio.github.io/claude-code-router/docs/server/config/providers

This configuration is for connecting to the Groq API. Remember to substitute 'your-api-key' with your Groq API key.

```json
{
  "NAME": "groq",
  "HOST": "https://api.groq.com/openai/v1",
  "APIKEY": "your-api-key",
  "MODELS": ["llama-3.3-70b-versatile"],
  "transformers": ["anthropic"]
}

```

--------------------------------

### Error Response: 400 Bad Request

Source: https://musistudio.github.io/claude-code-router/docs/server/api/messages-api

Example of a 400 Bad Request error response, typically indicating missing or invalid parameters in the request.

```json
{
  "error": {
    "type": "invalid_request_error",
    "message": "messages is required"
  }
}
```

--------------------------------

### Logging Configuration

Source: https://musistudio.github.io/claude-code-router/docs/cli/config/basic

Enable and configure logging levels for the service.

```json
{
  "LOG": true,          // Enable logging  
  "LOG_LEVEL": "info"   // Log level  
}
```

--------------------------------

### Configure Gemini Provider

Source: https://musistudio.github.io/claude-code-router/docs/server/config/providers

Set up your configuration for the Gemini API. Replace 'your-api-key' with your Google Cloud API key for Gemini.

```json
{
  "NAME": "gemini",
  "HOST": "https://generativelanguage.googleapis.com/v1beta",
  "APIKEY": "your-api-key",
  "MODELS": ["gemini-1.5-pro"],
  "transformers": ["anthropic"]
}

```

--------------------------------

### Configuration Backup File Path

Source: https://musistudio.github.io/claude-code-router/docs/server/api/config-api

Indicates the location and naming convention for automatically backed-up configuration files.

```text
~/.claude-code-router/config.backup.{timestamp}.json
```

--------------------------------

### Non-streaming Response Format

Source: https://musistudio.github.io/claude-code-router/docs/server/api/messages-api

Example of a non-streaming response from the API. It includes message ID, role, content, model used, stop reason, and token usage.

```json
{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help you today?"
    }
  ],
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 10,
    "output_tokens": 20
  }
}
```

--------------------------------

### Create Project Configuration using ccr model Command

Source: https://musistudio.github.io/claude-code-router/docs/cli/config/project-level

Use the 'ccr model --project' command within your project directory to automatically create or update project configuration.

```bash
# Run in project directory
cd /path/to/your/project
ccr model --project
```

--------------------------------

### Get Specific Log File Content

Source: https://musistudio.github.io/claude-code-router/docs/server/api/logs-api

Retrieves the content of a specified log file by providing its path in the query parameters. Requires an API key for authentication.

```bash
curl "http://localhost:3456/api/logs?file=/home/user/.claude-code-router/logs/ccr-20241226143022.log" \
  -H "x-api-key: your-api-key"
```
Tokens:
Raw