claude-code-router/docs/docs/server/advanced/presets.md

sidebar_position

sidebar_position
3

Presets

Use predefined configurations for quick setup.

What are Presets?

Presets are pre-configured settings that include provider configurations, routing rules, and transformers optimized for specific use cases.

Dynamic Configuration System (v2.0+)

CCR 2.0 introduces a powerful dynamic configuration system that supports:

• Multiple Input Types: Selectors, multi-select, confirm boxes, text input, number input, etc.
• Conditional Logic: Dynamically show/hide configuration fields based on user input
• Variable References: Configuration fields can reference each other
• Dynamic Options: Option lists can be dynamically generated from preset configuration or user input

Schema Field Types

Type	Description	Example
password	Password input (hidden)	API Key
input	Single-line text input	Base URL
number	Number input	Max tokens
select	Single-select dropdown	Choose Provider
multiselect	Multi-select	Enable features
confirm	Confirmation box	Use proxy
editor	Multi-line text editor	Custom config

Condition Operators

Operator	Description	Example
eq	Equals	{"field": "provider", "operator": "eq", "value": "openai"}
ne	Not equals	{"field": "advanced", "operator": "ne", "value": true}
in	In (array)	{"field": "feature", "operator": "in", "value": ["a", "b"]}
nin	Not in (array)	{"field": "type", "operator": "nin", "value": ["x", "y"]}
exists	Field exists	{"field": "apiKey", "operator": "exists"}
gt/lt/gte/lte	Greater/less than (or equal)	For number comparisons

Dynamic Options Types

static - Static Options

"options": {
  "type": "static",
  "options": [
    {"label": "Option 1", "value": "value1"},
    {"label": "Option 2", "value": "value2"}
  ]
}

providers - Extract from Providers Configuration

"options": {
  "type": "providers"
}

Automatically extracts names from the Providers array as options.

models - Extract from Specified Provider's Models

"options": {
  "type": "models",
  "providerField": "{{selectedProvider}}"
}

Dynamically displays models based on the user-selected provider.

Template Variables

Use {{variableName}} syntax to reference user input in the template:

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

Configuration Mappings

For complex configuration needs, use configMappings to precisely control value placement:

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

Complete Example

{
  "name": "multi-provider-example",
  "version": "1.0.0",
  "description": "Multi-provider configuration example - Switch between OpenAI and DeepSeek",
  "author": "CCR Team",
  "keywords": ["openai", "deepseek", "multi-provider"],
  "ccrVersion": "2.0.0",
  "schema": [
    {
      "id": "primaryProvider",
      "type": "select",
      "label": "Primary Provider",
      "prompt": "Select 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"
          }
        ]
      },
      "required": true,
      "defaultValue": "openai"
    },
    {
      "id": "apiKey",
      "type": "password",
      "label": "API Key",
      "prompt": "Enter your API Key",
      "placeholder": "sk-...",
      "required": true
    },
    {
      "id": "defaultModel",
      "type": "select",
      "label": "Default Model",
      "prompt": "Select the default model to use",
      "options": {
        "type": "static",
        "options": [
          {"label": "GPT-4o", "value": "gpt-4o"},
          {"label": "GPT-4o-mini", "value": "gpt-4o-mini"}
        ]
      },
      "required": true,
      "defaultValue": "gpt-4o",
      "when": {
        "field": "primaryProvider",
        "operator": "eq",
        "value": "openai"
      }
    },
    {
      "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": "{{primaryProvider}}",
        "api_base_url": "https://api.openai.com/v1",
        "api_key": "{{apiKey}}",
        "models": ["{{defaultModel}}"]
      }
    ],
    "Router": {
      "default": "{{primaryProvider}}/{{defaultModel}}"
    },
    "PROXY_URL": "{{proxyUrl}}"
  },
  "configMappings": [
    {
      "target": "PROXY_URL",
      "value": "{{proxyUrl}}",
      "when": {
        "field": "enableProxy",
        "operator": "eq",
        "value": true
      }
    }
  ]
}

Available Presets

Development

Optimized for software development tasks:

• Fast response times
• Good for code generation
• Cost-effective

Research

Optimized for research and analysis:

• Long context support
• High-quality responses
• More capable models

Balanced

A balance between speed and quality:

• Good general-purpose performance
• Reasonable costs
• Wide model support

Using Presets

Use the CLI to apply a preset:

ccr preset apply development

List available presets:

ccr preset list

Creating Custom Presets

Using the Dynamic Configuration System

Create a preset file with schema and template:

# Create preset directory
mkdir -p ~/.claude-code-router/presets/my-preset

# Create manifest.json
cat > ~/.claude-code-router/presets/my-preset/manifest.json << 'EOF'
{
  "name": "my-preset",
  "version": "1.0.0",
  "description": "My custom preset",
  "schema": [
    {
      "id": "apiKey",
      "type": "password",
      "label": "API Key",
      "required": true
    }
  ],
  "template": {
    "Providers": [
      {
        "name": "my-provider",
        "api_key": "{{apiKey}}"
      }
    ]
  }
}
EOF

# Apply preset (will prompt for API Key)
ccr my-preset

You can also save and reload your current configuration:

# Save current configuration as a preset
ccr preset save my-preset

# Load a saved preset
ccr preset apply my-preset

Preset Management

List All Presets

ccr preset list

Output example:

Available presets:
  development    - Development optimized configuration
  research       - Research optimized configuration
  balanced       - Balanced configuration
  my-preset      - Custom preset

Apply a Preset

ccr preset apply <preset-name>

The server will automatically restart to load the new configuration.

Delete a Preset

ccr preset delete <preset-name>

Preset File Location

Presets are stored in:

~/.claude-code-router/presets/

Each preset is a directory containing a manifest.json file.

Exporting and Importing Presets

Export Current Configuration

ccr config show > my-config.json

Import Configuration

ccr config edit
# Then paste the imported configuration

Best Practices

1. Use Dynamic Configuration: Use the schema system for configuration items that require user input
2. Provide Defaults: Set reasonable defaults for optional fields
3. Conditional Display: Use when conditions to avoid unnecessary inputs
4. Clear Labels: Provide clear label and prompt for each field
5. Validate Input: Use validator to ensure input validity
6. Version Control: Keep commonly used presets in version control
7. Document: Add descriptions and version info for custom presets

Next Steps

• CLI Reference - Complete CLI command reference
• Configuration - Detailed configuration guide