Crush

Configure an OpenAI-compatible CoffeeRouter provider for the Crush terminal coding agent.

Before You Begin

  • Prepare a CoffeeRouter API key and the exact model ID.
  • Choose an installation method such as npm, Homebrew, Winget, Scoop, or an official binary.
  • Confirm that the target model is suitable for agentic coding and supports the tools you need.

Configuration Steps

1. Install Crush

npm:

npm install -g @charmland/crush

Homebrew on macOS:

brew install charmbracelet/tap/crush

Windows:

winget install charmbracelet.crush

Run crush --version after installation.

2. Set the API Key

Linux / macOS:

export COFFEEROUTER_API_KEY="sk-your-api-key"

Windows PowerShell:

$env:COFFEEROUTER_API_KEY="sk-your-api-key"

3. Create the Crush Configuration

Crush reads configuration in this priority order:

  1. .crush.json in the project directory
  2. crush.json in the project directory
  3. $HOME/.config/crush/crush.json globally

Create the appropriate file and add:

{
    "$schema": "https://charm.land/crush.json",
    "providers": {
        "coffeerouter": {
            "type": "openai-compat",
            "base_url": "https://www.coffeerouter.ai/v1",
            "api_key": "$COFFEEROUTER_API_KEY",
            "models": [
                {
                    "id": "your-model-id",
                    "name": "CoffeeRouter Model",
                    "context_window": 128000,
                    "default_max_tokens": 8192,
                    "can_reason": false
                }
            ]
        }
    }
}

Adjust the model ID, context window, maximum output, and reasoning capability to match the actual model.

4. Start Crush and Select the Model

cd /path/to/your-project
crush

Press Ctrl+L to open the model selector, then choose the coffeerouter provider and your model.

Verify the Integration

Send a test task that reads a file and proposes a change. A normal response without tool-protocol errors confirms the integration.

FAQ

Why is the coffeerouter provider missing?

Check the file location and JSON syntax. Also check whether the current project contains a higher-priority .crush.json or crush.json.

Why does Crush return 401 Unauthorized?

Confirm that COFFEEROUTER_API_KEY is exported in the environment that launches Crush, then check the token status and access restrictions.

Why does Crush say the model does not exist?

models[].id must exactly match the model ID shown in CoffeeRouter. Save the configuration, exit Crush, and start it again.

Can Crush fetch models automatically?

Recent Crush versions can discover models for some OpenAI-compatible providers, depending on the service's /models endpoint. Listing models manually is explicit and lets you control the available set.

Security

  • crush.json is trusted configuration. Crush expands environment variables and may execute $(...) expressions from it. Never run an untrusted configuration file.
  • Do not write a real API key directly into project configuration or commit it to version control.
  • Use a dedicated Crush token and restrict its models, quota, and expiration.
  • Crush sends task descriptions, code context, and tool-call data to CoffeeRouter.

Official Resources