# Crush

Crush is the terminal coding agent of Charm. This guide adds the exchange as an OpenAI-compatible provider in a `crushrc` file.

Each team member can use the same file with a separate buyer key.

## Start with the Liquid CLI

The [Liquid CLI](https://inference.ai.exchange/docs/cli.md) starts Crush with the exchange as its provider. It uses its own `crushrc` for that process only, so your own Crush settings are not read or changed. Use it unless you must keep the settings in your own files.

```bash
curl -fsSL https://inference.ai.exchange/cli/install.sh | bash
liquid login
liquid crush
```

Add `--model liquid.auto:cheapest` to rank the offers by price, or `--cap 0.50` to limit what one request can cost. To set up Crush yourself, follow the steps below.

## Before you start

- A workspace with a balance and a `spend` key. See [API keys](https://inference.ai.exchange/docs/keys.md).
- Node.js and npm for the install command below.

## 1. Install Crush

```bash
npm install -g @charmland/crush
```

## 2. Create the config directory

```bash
mkdir -p ~/.config/crush
```

Crush reads `~/.config/crush/crushrc` on macOS and Linux. If you set `XDG_CONFIG_HOME` or `CRUSH_GLOBAL_CONFIG`, use that directory instead.

## 3. Export the buyer key

Replace the placeholder with your buyer key. Use the same shell to start Crush.

```bash
export LIQUID_API_KEY=sk-liquid-...
```

| Setting          | Purpose                                     |
| ---------------- | ------------------------------------------- |
| `LIQUID_API_KEY` | The buyer key that the provider file reads. |

Keep this key outside the config files. Do not share it. Each team member must use their own key.

## 4. Write the provider file

A `crushrc` is a shell script. This file uses the Crush commands `provider add`, `model add` and `model large`. It replaces only `liquid.sh`.

```bash
cat > ~/.config/crush/liquid.sh <<'EOF'
provider add liquid --name 'Liquid Inference' --type openai-compat \
  --base-url 'https://router.inference.ai.exchange/v1' \
  --api-key "$LIQUID_API_KEY" \
  --extra-header 'X-Title' 'Crush' \
  --extra-header 'x-liquid-cap-usd' '1.00'
model add 'liquid/liquid.auto' --name 'liquid.auto' --context-window 128000 --default-max-tokens 16384
model large 'liquid/liquid.auto'
model small 'liquid/liquid.auto'

EOF
```

| Setting                | Purpose                                                                                                                  |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `--name`               | The provider and model names in the model picker.                                                                        |
| `--type`               | `openai-compat` selects the OpenAI-compatible API for a non-OpenAI provider.                                             |
| `--base-url`           | The exchange URL, with `/v1`.                                                                                            |
| `--api-key`            | Reads the buyer key from `$LIQUID_API_KEY`, so the file holds no key.                                                    |
| `--extra-header`       | Sets `X-Title`, which identifies Crush on the receipt, and `x-liquid-cap-usd`, which limits the charge for each request. |
| `--context-window`     | The number of tokens in the model's context window.                                                                      |
| `--default-max-tokens` | The output limit of a request.                                                                                           |

`model large` and `model small` select the model for the main agent and for small tasks.

If no live context limit is available, the example uses 128,000 tokens. Change it to match your model.

## 5. Load the file from your crushrc

```bash
touch ~/.config/crush/crushrc
grep -qxF 'source ~/.config/crush/liquid.sh' ~/.config/crush/crushrc || echo 'source ~/.config/crush/liquid.sh' >> ~/.config/crush/crushrc
```

## 6. Start Crush and check it works

```bash
crush
```

Send a short request. Open **Credits → Receipts** to check the charge and the Crush client label.

To use another model, change the model in `liquid.sh`. Use an exact model, a router model or a preset. See [Connect an app](https://inference.ai.exchange/docs/connect-overview.md).

## Control the cost

The `x-liquid-cap-usd` header limits each request. Change its value in `liquid.sh` to set a different cap.

A task can cause several requests, and the request cap does not limit the total charge. Set a spend limit on the key to limit total spend. See [API keys](https://inference.ai.exchange/docs/keys.md).

Use a preset for other purchasing rules. See [Purchasing rules](https://inference.ai.exchange/docs/rules.md).

## Troubleshooting

| Symptom                 | Cause and fix                                                                        |
| ----------------------- | ------------------------------------------------------------------------------------ |
| The provider is absent. | Check that `crushrc` loads `liquid.sh`. Restart Crush.                               |
| `401`                   | Export `LIQUID_API_KEY` in the shell that starts Crush. Check that the key is valid. |
| `403`                   | Check the key's `spend` scope, address restriction and preset rules.                 |
| `402`                   | Add credit to the workspace or check the key's spend limit.                          |
| The model is absent.    | Check the live offers and the workspace presets. Use an exact model name.            |
| `cap_exceeds_buyer_cap` | Increase the request cap or select a cheaper model.                                  |

See [Errors](https://inference.ai.exchange/docs/errors.md) for the exchange's error codes and causes.

## Next steps

- [Market data](https://inference.ai.exchange/docs/market.md): models and live offers.
- [API keys](https://inference.ai.exchange/docs/keys.md): key scope and spend limits.
- [Purchasing rules](https://inference.ai.exchange/docs/rules.md): request caps and presets.